CAT-SOOP is a flexible, programmable learning management system based on the Python programming language.
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

232 lines
9.3 KiB

  1. <python>
  2. cs_content_header = "CAT-SOOP Hacker's Guide"
  3. </python>
  4. Welcome to the CAT-SOOP hacker's guide! This page is aimed primarily at people
  5. who are interested in helping to continue to evolve CAT-SOOP as a platform in a
  6. direct way, by working on the code of CAT-SOOP itself. It is intended to give
  7. you a brief overview of the CAT-SOOP code base and surrounding infrastructure,
  8. as well as the process for setting up a local testing copy and for contributing
  9. changes back to CAT-SOOP.
  10. <tableofcontents/>
  11. <section>Getting Set Up</section>
  12. If you intend to make changes that you will eventually push upstream, a good
  13. first step is to make yourself an account on the [CAT-SOOP Gitea
  14. Instance](/git/catsoop/catsoop), which is the main hub for CAT-SOOP development
  15. and discussion. You should also add an SSH public key to your account.
  16. You may also want to make an account on the [forum](/forum/), though that is
  17. less necessary.
  18. <subsection>Cloning the Repository</subsection>
  19. After you have set up an account on the Gitea instance and added an SSH key,
  20. you should "fork" the [main repository](/git/catsoop/catsoop) by navigating to
  21. it and clicking the "fork" button. This will create a copy of the repository
  22. associated with your username.
  23. Then you can clone that repository:
  24. ```nohighlight
  25. $ git clone
  26. ```
  27. You may also want to add your fork as a secondary remote, so that you
  28. can push to it, with a command like the following:
  29. ```nohighlight
  30. $ git remote add mine
  31. ```
  32. <subsection>Installing CAT-SOOP</subsection>
  33. The recommended setup for CAT-SOOP involves setting up a development
  34. environment inside of a Python virtualenv, which can be created with the
  35. following command (assuming virtualenv is installed):
  36. ```nohighlight
  37. $ python3 -m virtualenv -p `which python3` ENV_PATH
  38. ```
  39. where `ENV_PATH` is the location on disk where you want to create your new
  40. virtual environment. Then, you can activate the virtual environment so that
  41. `python3` and `pip3` refer to the virtual environment, rather than to your
  42. system-wide Python installation:
  43. ```nohighlight
  44. $ source ENV_PATH/bin/activate
  45. ```
  46. Once you have activated the virtual environment, you can install CAT-SOOP by
  47. navigating to your clone of the repository and running:
  48. ```
  49. $ python3 develop
  50. ```
  51. Once it has been installed, you should configure it:
  52. ```
  53. $ catsoop configure
  54. ```
  55. and then you can start the server with:
  56. ```
  57. $ catsoop start
  58. ```
  59. and navigate your browser to `http://localhost:6010`.
  60. In order for this page to be interesting, you will want to put a course in the
  61. CAT-SOOP data root (default: `~/.local/share/catsoop`). You may wish to clone
  62. the sample course if you do not already have another course to work with, using
  63. the following command:
  64. ```nohighlight
  65. $ git clone ~/.local/share/catsoop/courses/sample_course
  66. ```
  67. (if you want, you can also fork the `sample_course` repository and clone your own copy)
  68. <subsection>Making a First Change</subsection>
  69. As a test to make sure everything is set up, make a small change. For example,
  70. try adding `print('HOORAY!')` to the top of the `main` function in
  71. `catsoop/scripts/`. After doing so, `HOORAY!` should be
  72. printed to the terminal alongside all the usual output when running `catsoop
  73. start`.
  74. <subsection>Next Steps</subsection>
  75. <ref overview><a href="{link}">Section {number}</a></ref> provides an overview
  76. of the codebase, which you may wish to read as a starting point. Additionally,
  77. issues in hive that are labeled as "beginner-friendly" might be other good
  78. opportunities to jump into the codebase. You can view these issues
  79. [here](/git/catsoop/catsoop/issues?q=&type=all&state=open&labels=8&milestone=0&assignee=0),
  80. or by manually searching for them from the catsoop issue tracker.
  81. <section label="overview">Brief Overview of Codebase</section>
  82. TODO
  83. <subsection>Anatomy of a Page Load</subsection>
  84. TODO
  85. <section>Rules to Write/Commit By</section>
  86. 1. User-facing APIs should be as generic and robust as possible.
  87. 1. In most cases, if a sacrifice needs to be made, efficiency should be the
  88. first thing to go. Flexibility and ease of use should be given top
  89. priority.
  90. 1. All substantial new public-facing functions should have docstrings. These
  91. docstrings should be formatted using CAT-SOOP Markdown, as the [API
  92. Documentation](COURSE/docs/api) is automatically generated from them. In
  93. cases of adding new functionality or changing existing functionality, the
  94. documentation should also be updated.
  95. 1. Substantial new functionality should have associated unit tests where
  96. appropriate. Code related to user interaction / user interface is
  97. difficult to test, but it should still be tested where it's feasible to do
  98. so.
  99. 1. Functions and dictionaries are preferable to classes.
  100. 1. To ensure consistency across the codebase, CAT-SOOP uses the
  101. [black]( code formatting tool.
  102. Please run your changes through `black`.
  103. 1. Logically separate changes should have separate commits in the repository.
  104. 1. Commit messages should be as descriptive as possible. Where it makes sense
  105. to do so, it is fine to squash/strip/rebase commits to make the history
  106. cleaner. That is, if you use multiple small commits when working locally,
  107. these should ideally be broken down into logical commits with descriptive
  108. commit messages before they are merged into CAT-SOOP proper.
  109. <section>Sending Changes Upstream</section>
  110. Once you've made some changes, we'd appreciate you sending them our way so that
  111. we can include them in CAT-SOOP (if you're comfortable doing so)! This section
  112. provides some guidance on doing just that.
  113. <subsection>Licensing</subsection>
  114. CAT-SOOP (including its documentation) is available under the terms of the [GNU
  115. Affero General Public License, version
  116. 3+]( By sending your contributions
  117. as described below, you are licensing them to us under those same terms, and
  118. you are asserting that you have the right to license your contributions under
  119. those terms.
  120. <subsection>Checklist</subsection>
  121. Before sending your changes, please:
  122. 1. Make sure that new features are documented/tested as described above.
  123. 1. Run `black` on the entire codebase, and make sure that no files change.
  124. 1. Run `python3 test` and make sure that all tests pass (including new
  125. tests you've written).
  126. 1. Add an appropriate entry to ``, and, if you wish, add your name to
  127. the `` file.
  128. <subsection>Sending</subsection>
  129. We prefer using Gitea's "pull request" feature for managing contributed changes
  130. to catsoop. In order to start the process, you should push your changes to a
  131. new branch on your fork of the main repository. When pushing, you should see a
  132. link for creating a new pull request. You can follow this link, fill out a
  133. little bit of information about the changes, and submit your pull request.
  134. Alternatively, if you prefer it, feel free to send patches via e-mail to
  135. `` using `git format-patch` or `git send-email`.
  136. <subsection>Feedback</subsection>
  137. After you've sent your changes, you should receive a response (hopefully in a
  138. day or two) in one of the following flavors:
  139. 1. Thanks! We'll add these to CAT-SOOP!
  140. 1. Thanks! I'm hosed right now but will take a detailed look when I get a chance.
  141. 1. Thanks! Here are some questions / thoughts / suggested changes.
  142. If you don't hear back right away, feel free to send a follow-up message. And
  143. in any case, feel free to continue the conversation, to make changes, etc.
  144. <section>Versioning and Releases</section>
  145. In general, the goal is to release a new version of CAT-SOOP once every
  146. semester. As MIT's semesters start in September and February, respectively,
  147. the goal is to release a new major version just before the start of each
  148. semester. These releases will be versioned by date, with version `20YY.9`
  149. referring to the September release, and `20YY.2` referring to the February
  150. release.
  151. Beyond this, additional "minor" version numbers may also be used, usually for
  152. bug fixes. In general, version `20YY.M.V` refers to the `V`<sup>th</sup>
  153. release of version `20YY.M`. `V` starts from `0`, so the initial release of
  154. each major version is `20YY.M.0`. Unlike major version bumps, these minor
  155. versions will not happen on a fixed schedule, but, rather, will be released as
  156. necessary, or as interesting new features are added.
  157. Most major versions will only be supported for one semester (until the next
  158. version's release) and may contain backwards-incompatible changes, but,
  159. starting with `2019.9`, the September releases in odd-numbered years will be
  160. tagged as **long-term support** (LTS) releases and will continue to be
  161. supported for two full years. These versions will receive no
  162. backwards-incompatible changes during that time (except in the case where such
  163. a change is necessary for security reasons). Each LTS version will have a
  164. separate branch in the repository, named like `lts-20YY.M`, where bugfixes
  165. will be backported from the `default` branch.
  166. Each new release (including minor releases) will be accompanied by an e-mail to
  167. ``. These e-mails will include information about what
  168. changed from the previous version, as well as an indication of steps that need
  169. to be taken when upgrading.