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 (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.

1) Getting Set Up

1.1) Cloning the Repository

CAT-SOOP's source code is hosted on a local, self-hosted Forgejo instance at https://catsoop.org/git (why not github?). Forgejo uses a similar workflow to other modern source forges. While we do accept patches via e-mail to catsoop-dev@mit.edu, the preferred method for contributing to catsoop is outlined below.

The first step is to create a 'fork' of the catsoop repository by going to https://catsoop.org/git/catsoop/catsoop, logging in (after creating an account account), creating a 'fork' of the main repository by clicking on the "Fork" button in the upper-right corner of the page, adding an SSH key to your account, and then cloning your fork of the repository, which will look something like:

git clone git@catsoop.org:YOUR_USERNAME/catsoop

1.2) Installing CAT-SOOP for Development

The recommended setup for CAT-SOOP involves setting up a development environment inside of a Python "virtual environment," which can be created with the following command (assuming virtualenv is installed):

python3 -m virtualenv -p `which python3` ENV_PATH

where 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 python3 and 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:

make develop

This will install catsoop in such a way that making changes to the source code only require restarting the server, without the need to first reinstall.

Once catsoop has been installed, you should configure it:

catsoop configure

and then you can start the server with:

catsoop start

and navigate your browser to http://localhost:7667 (or a different endpoint if you specified one).

In order for the installation 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 https://catsoop.org/catsoop/sample_course ~/.local/share/catsoop/courses/sample_course

(or you could similarly fork the sample_course repository if you want to make changes to it)

1.3) Making a First Change

As a test to make sure everything is set up, make a small change. For example, try adding 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 catsoop start.

Note as you continue to work that some changes will take effect automatically even as a catsoop process is running, but some may require killing the catsoop process and restarting it.

1.4) Next Steps

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, or by manually searching for them from the catsoop issue tracker. Feel free to reach out if you need help!

2) Rules to Write/Commit By

  1. User-facing APIs should be as generic and robust as possible.

  2. 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.

  3. All substantial new public-facing functions should have docstrings. These docstrings should be formatted using CAT-SOOP Markdown since the API Documentation is automatically generated from them. In cases of adding new functionality or changing existing functionality, the website (in the website directory in the repo) should also be updated where appropriate.

  4. 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.

  5. Unless there is a really good reason for doing it, please avoid using classes (functions and dictionaries are generally preferable).

  6. To ensure consistency across the codebase, CAT-SOOP uses the black code formatting tool. Please run your changes through black before submitting them.

  7. Logically separate changes should have separate commits in the repository.

  8. 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.

3) 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.

3.1) Generative AI Policy

CAT-SOOP doesn't accept code or documentation that was written (in whole or in part) by generative AI tools. Please do not submit pull requests that were generated by LLM's or the like.

3.2) Licensing

CAT-SOOP (including its documentation) is licensed 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.

Unless you specify otherwise, by sending us your contributions as described below, you are also asserting that it is OK for us to attribute those changes under the general heading of "The CAT-SOOP Developers" in the copyright notice.

3.3) Checklist

Before sending your changes, please:

  1. Make sure that new features are documented/tested as described above.
  2. Run black on the entire codebase, and make sure that no files change.
  3. Run make test and make sure that all tests pass (including any new tests you've written).
  4. Add an appropriate entry to CHANGELOG, and, if you wish, add your name to the CONTRIBUTORS file.

3.4) Preparing and Sending Patches

Roughly speaking, any way you want to get your changes to us is fine! But our preferred method is via a pull request on the Forgejo instance. Codeberg (which also runs on Forgejo) has some instructions for making pull requests at https://docs.codeberg.org/collaborating/pull-requests-and-git-flow/.

If it's easier for you, though, we also accept patches over e-mail to catsoop-dev@mit.edu (see https://git-send-email.io/ for information on how this works).

3.5) Feedback

After you've sent your changes, you should receive a response shortly thereafter (hopefully within a day or two). That response will usually come in one of the following flavors:

  1. Thanks! We'll add these to CAT-SOOP!
  2. Thanks! We're hosed right now but will take a detailed look when we get a chance.
  3. 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.

4) Versioning and Releases

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.

For a while, catsoop used date-based versioning, with each version number corresponding to the year and month in which that version was released. This had the unfortunate effect that the version numbers themselves conveyed nothing about how different the versions were from one another, so we have moved back to a scheme like MAJOR.MINOR.PATCH. With each new release:

  • If the release includes backwards-incompatible changes (either to the specification language or to the logs), the MAJOR version number will be incremented.
  • If the release includes backwards-compatible new features, the MINOR version number will be incremented.
  • For bugfixes and other small changes, the PATCH version number will be incremented.

Most major versions are supported only until the next major version is released. But every odd-numbered major version will be a "long-term support" (LTS) release; those releases will continue to receive backwards-compatible bugfixes for at least two years.

4.1) Repository Structure

All development happens on the main branch in the Git repository.

Generally, we don't make new branches there, except in the case where we need to go back and backport something to an LTS version after the default branch already includes backwards-incompatible changes, in which case we'll make a new branch for the LTS version (which will be closed once it's no longer supported).

Each release is tagged with a version number vX.Y.Z.