|
|
|
|
@ -4,38 +4,30 @@ cs_content_header = "CAT-SOOP Hacker's Guide"
|
|
|
|
|
|
|
|
|
|
Welcome to the CAT-SOOP hacker's guide! This page is aimed primarily at people
|
|
|
|
|
who are interested in helping to continue to evolve CAT-SOOP as a platform in a
|
|
|
|
|
direct way, by working on the code of CAT-SOOP itself. It is intended to give
|
|
|
|
|
you a brief overview of the CAT-SOOP codebase and surrounding infrastructure,
|
|
|
|
|
as well as the process for setting up a local testing copy and for contributing
|
|
|
|
|
changes back to CAT-SOOP.
|
|
|
|
|
direct way, by working on the code of CAT-SOOP itself (or the associated
|
|
|
|
|
documentation). This page is intended to give you a brief overview of the
|
|
|
|
|
CAT-SOOP codebase and surrounding infrastructure, as well as the process for
|
|
|
|
|
setting up a local testing copy and for contributing changes back to CAT-SOOP.
|
|
|
|
|
|
|
|
|
|
<tableofcontents/>
|
|
|
|
|
|
|
|
|
|
<section>Getting Set Up</section>
|
|
|
|
|
|
|
|
|
|
If you intend to make changes that you will eventually push upstream, a good
|
|
|
|
|
first step is to make sure you have an account on the [community
|
|
|
|
|
forum](/community), which is the main place where catsoop-related discussion
|
|
|
|
|
happens. In general, it is a good idea to make a post there describing the
|
|
|
|
|
changes you plan to make (or if there is already a forum thread about it, to
|
|
|
|
|
indicate your interest in a post to that thread).
|
|
|
|
|
|
|
|
|
|
While the forum is used for general questions, the `catsoop-dev@mit.edu`
|
|
|
|
|
mailing list is used to coordinate development. You should also consider
|
|
|
|
|
making an account for yourself on the [bug tracker](/bugs/), which is where
|
|
|
|
|
development is coordinated.
|
|
|
|
|
first step is to make yourself an account on the [CAT-SOOP Gitea
|
|
|
|
|
Instance](/git/catsoop/catsoop), which is the main hub for CAT-SOOP development
|
|
|
|
|
and discussion. You should also add an SSH public key to your account.
|
|
|
|
|
|
|
|
|
|
<subsection>Cloning the Repository</subsection>
|
|
|
|
|
|
|
|
|
|
When it is time to go ahead and make your change(s) to the code, it will be
|
|
|
|
|
important to have a local copy of the code, by cloning the
|
|
|
|
|
[Git](https://git-scm.com/) repository:
|
|
|
|
|
After you have set up an account on the Gitea instance and added an SSH key,
|
|
|
|
|
you should be able to clone the [main repository](/git/catsoop/catsoop):
|
|
|
|
|
|
|
|
|
|
```nohighlight
|
|
|
|
|
@{TOR_STRING('git')} clone git://@{cs_url_root.split('/', 2)[-1]}/catsoop.git
|
|
|
|
|
$ git clone git@catsoop.org:catsoop/catsoop
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
<subsection>Installing CAT-SOOP</subsection>
|
|
|
|
|
<subsection>Installing CAT-SOOP for Development</subsection>
|
|
|
|
|
|
|
|
|
|
The recommended setup for CAT-SOOP involves setting up a development
|
|
|
|
|
environment inside of a Python "virtual environment," which can be created with
|
|
|
|
|
@ -85,7 +77,7 @@ clone the sample course if you do not already have another course to work with,
|
|
|
|
|
using the following command:
|
|
|
|
|
|
|
|
|
|
```nohighlight
|
|
|
|
|
@{TOR_STRING('git')} clone git://@{cs_url_root.split('/', 2)[-1]}/sample_course.git ~/.local/share/catsoop/courses/sample_course
|
|
|
|
|
git clone git@catsoop.org:catsoop/sample_course ~/.local/share/catsoop/courses/sample_course
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
@ -105,8 +97,8 @@ process and restarting it.
|
|
|
|
|
|
|
|
|
|
If you don't already have an idea in mind, some issues in the issue tracker are
|
|
|
|
|
marked as potential good opportunities for a first dive into the codebase. You
|
|
|
|
|
can view these issues [here](/bugs/view_all_bug_page.php?filter=6042230d31597),
|
|
|
|
|
or by manually searching for them from the catsoop issue tracker, and feel free
|
|
|
|
|
can view these issues [here](https://catsoop.org/git/catsoop/catsoop/issues?q=&type=all&state=open&labels=17&milestone=0&assignee=0&poster=0),
|
|
|
|
|
or by manually searching for them from the catsoop issue tracker. Feel free
|
|
|
|
|
to reach out if you need help!
|
|
|
|
|
|
|
|
|
|
<section>Rules to Write/Commit By</section>
|
|
|
|
|
@ -118,12 +110,13 @@ to reach out if you need help!
|
|
|
|
|
priority.
|
|
|
|
|
|
|
|
|
|
1. All substantial new public-facing functions should have docstrings. These
|
|
|
|
|
docstrings should be formatted using CAT-SOOP Markdown, as the [API
|
|
|
|
|
docstrings should be formatted using CAT-SOOP Markdown since the [API
|
|
|
|
|
Documentation](COURSE/docs/api) is automatically generated from them. In
|
|
|
|
|
cases of adding new functionality or changing existing functionality, the
|
|
|
|
|
documentation should also be updated where appropriate.
|
|
|
|
|
cases of adding new functionality or changing existing functionality, this
|
|
|
|
|
website (Git repo [here](/git/catsoop/website)) should also be updated
|
|
|
|
|
where appropriate.
|
|
|
|
|
|
|
|
|
|
1. Substantial new functionality should have associated unit tests where
|
|
|
|
|
1. Substantial new functionality should have associated tests where
|
|
|
|
|
appropriate. Code related to user interaction / user interface is
|
|
|
|
|
difficult to test, but it should still be tested where it's feasible to do
|
|
|
|
|
so.
|
|
|
|
|
@ -133,7 +126,8 @@ to reach out if you need help!
|
|
|
|
|
|
|
|
|
|
1. To ensure consistency across the codebase, CAT-SOOP uses the
|
|
|
|
|
<a href="https://black.readthedocs.io/en/stable/" target="_blank">black</a>
|
|
|
|
|
code formatting tool. Please run your changes through `black`.
|
|
|
|
|
code formatting tool. Please run your changes through `black` before
|
|
|
|
|
submitting them.
|
|
|
|
|
|
|
|
|
|
1. Logically separate changes should have separate commits in the repository.
|
|
|
|
|
|
|
|
|
|
@ -173,43 +167,24 @@ Before sending your changes, please:
|
|
|
|
|
1. Add an appropriate entry to `CHANGELOG`, and, if you wish, add your name
|
|
|
|
|
to the `CONTRIBUTORS` file.
|
|
|
|
|
|
|
|
|
|
<subsection>Preparing and Sending Patches</subsection>
|
|
|
|
|
|
|
|
|
|
In general, we follow a patch-based contribution model, coordinated via the
|
|
|
|
|
`catsoop-dev@mit.edu` mailing list and the [bug tracker](/bugs/). The next
|
|
|
|
|
step in that process, after making your changes and committing them locally, is
|
|
|
|
|
to prepare patches to be shared with us.
|
|
|
|
|
|
|
|
|
|
!!! note: Note
|
|
|
|
|
If you are having trouble generating your patch files, or if you have other
|
|
|
|
|
questions about the process, please reach out via the mailing lists, and we'd
|
|
|
|
|
be happy to help!
|
|
|
|
|
|
|
|
|
|
There are a few different ways that we'll accept patches.
|
|
|
|
|
<subsection>Sending Changes</subsection>
|
|
|
|
|
|
|
|
|
|
1. For small patches, you can use the `git send-email` command to send your
|
|
|
|
|
patches via email. There is a nice tutorial about this approach at
|
|
|
|
|
<https://git-send-email.io/>. Please make sure to send patches to
|
|
|
|
|
`catsoop-dev@mit.edu`.
|
|
|
|
|
We're not terribly picky about how your changes reach us, so there are at least
|
|
|
|
|
two options:
|
|
|
|
|
|
|
|
|
|
1. You can instead use `git format-patch`.
|
|
|
|
|
If you are using Bash, then the following command, for example, will
|
|
|
|
|
generate a patch file containing all of the commits not present in the base
|
|
|
|
|
repo:
|
|
|
|
|
1. You can use Gitea's "fork" functionality to create a copy of the catsoop
|
|
|
|
|
repository under your own username in Gitea and then use Gitea's "pull
|
|
|
|
|
request" feature. In order to start the process, you should push your
|
|
|
|
|
changes to a new branch on your fork of the main repository. When pushing,
|
|
|
|
|
you should see a link for creating a new pull request. You can follow this
|
|
|
|
|
link, fill out a little bit of information about the changes, and submit
|
|
|
|
|
your pull request.
|
|
|
|
|
|
|
|
|
|
```nohighlight
|
|
|
|
|
git format-patch "$(git merge-base dev `git branch --show-current`)" --stdout > NAME.patch
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
You can then attach the patch to an e-mail to `catsoop-dev@mit.edu` (or, if
|
|
|
|
|
you prefer, as an attachment in the forum or the bug tracker).
|
|
|
|
|
|
|
|
|
|
3. Alternatively, if your copy of the repository is accessible over a network
|
|
|
|
|
connection (for example, on a public source forge like Gitlab, or in a
|
|
|
|
|
publicly-accessible directory on Athena), it is fine to send a pointer to that
|
|
|
|
|
repository instead of sending patches (you could use `git request-pull` or
|
|
|
|
|
any other mechanism).
|
|
|
|
|
1. You can send patches via e-mail (by using `git-send-email` or
|
|
|
|
|
`git-request-pull`, or by attaching the output from `git format-patch`)
|
|
|
|
|
to `catsoop-dev@mit.edu`.
|
|
|
|
|
|
|
|
|
|
Roughly speaking, any way you want to get your changes to us is fine!
|
|
|
|
|
|
|
|
|
|
<subsection>Feedback</subsection>
|
|
|
|
|
|
|
|
|
|
@ -223,51 +198,3 @@ one of the following flavors:
|
|
|
|
|
|
|
|
|
|
If you don't hear back right away, feel free to send a follow-up message. And
|
|
|
|
|
in any case, feel free to continue the conversation, to make changes, etc.
|
|
|
|
|
|
|
|
|
|
<section>Versioning and Releases</section>
|
|
|
|
|
|
|
|
|
|
Typically, CAT-SOOP development is very "bursty," with most development
|
|
|
|
|
happening during the summer months and January (in between academic terms), and
|
|
|
|
|
relatively little development happening during the semesters.
|
|
|
|
|
|
|
|
|
|
In general, the goal is to release a new version of CAT-SOOP once every
|
|
|
|
|
semester. As MIT's semesters start in September and February, respectively,
|
|
|
|
|
this means a new major version just before the start of each semester.
|
|
|
|
|
Releases are versioned by date, with version `20YY.9` referring to the
|
|
|
|
|
September release, and `20YY.2` referring to the February release.
|
|
|
|
|
|
|
|
|
|
Beyond this, additional "minor" version numbers may also be used, usually for
|
|
|
|
|
bug fixes. In general, version `20YY.M.V` refers to the `V`<sup>th</sup>
|
|
|
|
|
release of version `20YY.M`. We start counting `V` from `0`, so the initial
|
|
|
|
|
release of each major version is `20YY.M.0`. Unlike major version bumps, these
|
|
|
|
|
minor versions will not happen on a fixed schedule, but, rather, will be
|
|
|
|
|
released as necessary, or as interesting new features are added.
|
|
|
|
|
|
|
|
|
|
Most major versions will only be supported for one semester (until the next
|
|
|
|
|
version's release) and may contain backwards-incompatible changes, but,
|
|
|
|
|
starting with `2019.9`, the September releases in odd-numbered years will be
|
|
|
|
|
tagged as **long-term support** (LTS) releases and will continue to be
|
|
|
|
|
supported for two full years. These versions will receive no
|
|
|
|
|
backwards-incompatible changes during that time (except in the case where such
|
|
|
|
|
a change is necessary for security reasons).
|
|
|
|
|
|
|
|
|
|
Each new release (including minor releases) will be accompanied by a post to
|
|
|
|
|
the community forum, which will include information about what changed from the
|
|
|
|
|
previous version, as well as an indication of steps that need to be taken when
|
|
|
|
|
upgrading.
|
|
|
|
|
|
|
|
|
|
<subsection>Repository Structure</subsection>
|
|
|
|
|
|
|
|
|
|
All development happens on the `dev` branch in the Git repository.
|
|
|
|
|
|
|
|
|
|
Each version of catsoop has a separate branch in the repository, named like
|
|
|
|
|
`v20YY.M` (for regular versions) or `v20YY.M-lts` (for LTS versions), where
|
|
|
|
|
bugfixes and other changes are backported from the `dev` branch. Generally,
|
|
|
|
|
new features and bugfixes only make their way into release branches by way of
|
|
|
|
|
backporting changes from `dev`; that is to say, changes should always happen on
|
|
|
|
|
`dev` first, except in rare cases.
|
|
|
|
|
|
|
|
|
|
Each release is tagged with a version number `v20YY.M.V`. Additionally, the
|
|
|
|
|
current release and the current LTS release are tagged with `current_release`
|
|
|
|
|
and `current_lts`, respectively. These tagged releases are also signed with
|
|
|
|
|
[Adam's PGP key](https://hz.mit.edu/hz_pubkey.asc).
|
|
|
|
|
|
