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.


I 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 catsoop-dev@mit.edu in roughly any format.


Table of Contents

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

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 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, 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.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:

$ 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

  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. To ensure consistency across the codebase, CAT-SOOP uses the black code formatting tool. Please run your changes through black.

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

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

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 to catsoop-dev@mit.edu, 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.

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, and, if you wish, add your name to the CONTRIBUTORS file.
  5. If your code resolves an issue tracked in the repository, feel free to close that issue using hive, and commit that change.

4.3) Sending

In general, all proposed changes should be sent via e-mail to catsoop-dev@mit.edu. Depending on the size and nature of your change, please use one of the following methods:

  1. For most changes, the preferred method is emailing one or more patches to the list. These can be formatted using git format-patch and attached to an e-mail. Or, if you prefer, you can use git send-email.

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

4.4) Feedback

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:

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