CAT-SOOP Hacker's Guide
NoteI should say also that the guidelines here about contributing are largely based on my personal preferences. If you find something below unwieldy but still want to contribute, feel free to send changes to
email@example.com roughly any format.
Table of Contents
- 1) Getting Set Up
- 1.1) Cloning the Repository
- 1.2) Installing CAT-SOOP
- 1.3) Other Infrastructure
- 1.4) Making a First Change
- 1.5) Next Steps
- 2) Brief Overview of Codebase
- 3) Rules to Write/Commit By
- 4) Sending Changes Upstream
- 5) Versioning and Releases
1) Getting Set Up
1.1) Cloning the Repository
The first step is to clone the CAT-SOOP source repository:
$ git clone git://catsoop.org/catsoop.git
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
one of the two following commands:
$ git clone git://catsoop.org/sample_course.git ~/.local/share/catsoop/courses/sample_course
1.3) Other Infrastructure
CAT-SOOP's issues are tracked in the Gitea instance. You may with to create an account there in order to submit issues or participate in discussion.
1.4) 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.5) 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 on the web
here, or by running the following
command from within the CAT-SOOP repository after installing
$ hive ls label:beginner-friendly
Or, you can look at other things that have been explicitly marked as relevant for the upcoming release:
$ hive ls target:2019.9
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.
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, please send 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 to
firstname.lastname@example.org, you are licensing them
to us under those same terms, and you are agreeing 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, and, if you wish, add your name to the
- If your code resolves an issue tracked in the repository, feel free to close
that issue using
hive, and commit that change.
In general, all proposed changes should be sent via e-mail to
email@example.com. Depending on the size and nature of your change, please
use one of the following methods:
For most changes, the preferred method is emailing one or more patches to the list. These can be formatted using
git format-patchand attached to an e-mail. Or, if you prefer, you can use
For large changes (touching a lot of files and/or a lot of lines in a single file), the preferred method is to send a reference to a publicly-accessible clone of the repository containing your changes.
After you've sent your changes, you should get an e-mail 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 submit updated patches, 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
firstname.lastname@example.org. 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.