CAT-SOOP Hacker's Guide
Table of Contents
- 1) Getting Set Up
- 2) Brief Overview of Codebase
- 3) Rules to Write/Commit By
- 4) Sending Changes Upstream
- 5) Versioning and Releases
1) Getting Set Up
If you intend to make changes that you will eventually push upstream, a good first step is to make yourself an account on the CAT-SOOP Gitea Instance, which is the main hub for CAT-SOOP development and discussion. You should also add an SSH public key to your account.
You may also want to make an account on the forum, though that is less necessary.
1.1) Cloning the Repository
After you have set up an account on the Gitea instance and added an SSH key, you should "fork" the main repository by navigating to it and clicking the "fork" button. This will create a copy of the repository associated with your username.
Then you can clone that repository:
$ git clone firstname.lastname@example.org:catsoop/catsoop
You may also want to add your fork as a secondary remote, so that you can push to it, with a command like the following:
$ git remote add mine email@example.com:USERNAME/catsoop
1.2) Installing CAT-SOOP
The recommended setup for CAT-SOOP involves setting up a development environment inside of a Python virtualenv, which can be created with the following command (assuming virtualenv is installed):
$ python3 -m virtualenv -p `which python3` ENV_PATH
ENV_PATH is the location on disk where you want to create your new
virtual environment. Then, you can activate the virtual environment so that
pip3 refer to the virtual environment, rather than to your
system-wide Python installation:
$ source ENV_PATH/bin/activate
Once you have activated the virtual environment, you can install CAT-SOOP by navigating to your clone of the repository and running:
$ python3 setup.py develop
Once it has been installed, you should configure it:
$ catsoop configure
and then you can start the server with:
$ catsoop start
and navigate your browser to
In order for this page to be interesting, you will want to put a course in the
CAT-SOOP data root (default:
~/.local/share/catsoop). You may wish to clone
the sample course if you do not already have another course to work with, using
the following command:
$ git clone firstname.lastname@example.org:catsoop/sample_course ~/.local/share/catsoop/courses/sample_course
(if you want, you can also fork the
sample_course repository and clone your own copy)
1.3) Making a First Change
As a test to make sure everything is set up, make a small change. For example,
print('HOORAY!') to the top of the
main function in
catsoop/scripts/start_catsoop.py. After doing so,
HOORAY! should be
printed to the terminal alongside all the usual output when running
1.4) Next Steps
Section 2 provides an overview of the codebase, which you may wish to read as a starting point. Additionally, issues in hive that are labeled as "beginner-friendly" might be other good opportunities to jump into the codebase. You can view these issues here, or by manually searching for them from the catsoop issue tracker.
2) Brief Overview of Codebase
2.1) Anatomy of a Page Load
3) Rules to Write/Commit By
User-facing APIs should be as generic and robust as possible.
In most cases, if a sacrifice needs to be made, efficiency should be the first thing to go. Flexibility and ease of use should be given top priority.
All substantial new public-facing functions should have docstrings. These docstrings should be formatted using CAT-SOOP Markdown, as the API Documentation is automatically generated from them. In cases of adding new functionality or changing existing functionality, the documentation should also be updated.
Substantial new functionality should have associated unit 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.
Functions and dictionaries are preferable to classes.
To ensure consistency across the codebase, CAT-SOOP uses the black code formatting tool. Please run your changes through
Logically separate changes should have separate commits in the repository.
Commit messages should be as descriptive as possible. Where it makes sense to do so, it is fine to squash/strip/rebase commits to make the history cleaner. That is, if you use multiple small commits when working locally, these should ideally be broken down into logical commits with descriptive commit messages before they are merged into CAT-SOOP proper.
4) Sending Changes Upstream
Once you've made some changes, we'd appreciate you sending them our way so that we can include them in CAT-SOOP (if you're comfortable doing so)! This section provides some guidance on doing just that.
CAT-SOOP (including its documentation) is available under the terms of the GNU Affero General Public License, version 3+. By sending your contributions as described below, you are licensing them to us under those same terms, and you are asserting that you have the right to license your contributions under those terms.
Before sending your changes, please:
- Make sure that new features are documented/tested as described above.
blackon the entire codebase, and make sure that no files change.
python3 setup.py testand make sure that all tests pass (including new tests you've written).
- Add an appropriate entry to
CHANGELOG.md, and, if you wish, add your name to the
We prefer using Gitea's "pull request" feature for managing contributed changes to catsoop. 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.
Alternatively, if you prefer it, feel free to send patches via e-mail to
git format-patch or
After you've sent your changes, you should receive a response (hopefully in a day or two) in one of the following flavors:
- Thanks! We'll add these to CAT-SOOP!
- Thanks! I'm hosed right now but will take a detailed look when I get a chance.
- Thanks! Here are some questions / thoughts / suggested changes.
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.
5) Versioning and Releases
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,
the goal is to release a new major version just before the start of each
semester. These releases will be versioned by date, with version
referring to the September release, and
20YY.2 referring to the February
Beyond this, additional "minor" version numbers may also be used, usually for
bug fixes. In general, version
20YY.M.V refers to the
release of version
V starts 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,
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 LTS version will have a
separate branch in the repository, named like
lts-20YY.M, where bugfixes
will be backported from the
Each new release (including minor releases) will be accompanied by an e-mail to
email@example.com. These e-mails will include information about what
changed from the previous version, as well as an indication of steps that need
to be taken when upgrading.