Home / Documentation / Contributing to CAT-SOOP / Hacker's Guide

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 code base and surrounding infrastructure, as well as the process for setting up a local testing copy and for contributing changes back to CAT-SOOP.

Table of Contents

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 git@catsoop.mit.edu: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 git@catsoop.mit.edu: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

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:

$ 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 http://localhost:6010.

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 git@catsoop.mit.edu: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, 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.

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

TODO

2.1) Anatomy of a Page Load

TODO

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

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

  5. Functions and dictionaries are preferable to classes.

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

  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.

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.

4.1) Licensing

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.

4.2) 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 python3 setup.py test and make sure that all tests pass (including new tests you've written).
  4. Add an appropriate entry to CHANGELOG.md, and, if you wish, add your name to the CONTRIBUTORS.md file.

4.3) Sending

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 catsoop-dev@mit.edu using git format-patch or git send-email.

4.4) Feedback

After you've sent your changes, you should receive a response (hopefully in a day or two) in one of the following flavors:

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

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 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 Vth release of version 20YY.M. 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, 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 LTS version will have a separate branch in the repository, named like lts-20YY.M, where bugfixes will be backported from the default branch.

Each new release (including minor releases) will be accompanied by an e-mail to catsoop-users@mit.edu. 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.