Submit a Patch

We welcome and appreciate all patches, big and small!

Overview

The official Furem Cape Git repository is https://git.sr.ht/~arx10/furemcape. Development is done on the master branch, with major releases branched from it.

Our development mailing list is ~arx10/furemcape-dev@lists.sr.ht. It’s archived at https://lists.sr.ht/~arx10/furemcape-dev. You can subscribe to it by sending an email to ~arx10/furemcape-dev+subscribe@lists.sr.ht (the subject line and body are ignored). For more info about lists.sr.ht (aka mailing lists at sourcehut), see the lists.sr.ht docs.

Our issue tracker is https://todo.sr.ht/~arx10/furemcape. You can post new tickets or comment on existing tickets anonymously. If you register for a sourcehut account, you can also subscribe to all Furem Cape ticket updates (by clicking the “enable notifications” button on the tracker home page), or subscribe to updates for specific tickets only (by clicking the “enable notifications” button on each ticket’s page).

If there is a major change or feature to Furem Cape that you want to tackle, before you sink a bunch of time into it, please write up a design document for the change and send it to our development list (or submit it to our issue tracker) for discussion and feedback.

For everything else, please follow this process:

Development Process

Develop Locally

Clone the official git repository at https://git.sr.ht/~arx10/furemcape. The source code is broken up into a number of sub-projects, like administrator, analyzer, etc (see the Design page for details). Most of the source code is Python, written in the standard style, enforced by flake8 linting.

Linting, testing, building docs, etc are all intended to be run within Docker containers. The Docker containers are described in docker-compose-dev.yml, and are orchestrated via the top-level Makefile. Each sub-project includes its own tasks.mk file, containing tasks that are included in the top-level Makefile. Run make or make help to see the list of all available Make tasks.

Run the following to lint the entire project:

make lint

This may take a while, so to lint just the sub-project you’re working on, run make lint.[sub-project]; for example, to lint just the analyzer subproject, run this:

make lint.analyzer

Test Locally

Run the following to run all the project tests (including end-to-end tests) in Docker containers:

make test

To test just the sub-project you’re working on, run make test.[sub-project]; for example, to test just the analyzer subproject, run this:

make test.analyzer

To run the tests of a sub-project automatically, every time you save a change to a (Python) file in the sub-project, run make watch.[sub-project]; for example to run the analyzer sub-project tests every time you make a change in the analyzer sub-project, run this:

make watch.analyzer

The databases used by the tests are in Docker containers, and are cleaned out between test runs. If you have some sample data you want to test, you can use the dev cluster of Docker containers to load your sample data and run some ad-hoc tests with them. The dev cluster includes hitdb and issuedb databases that are not automatically cleaned, so it provides an ideal environment for ad-hoc testing. Run the following command to open up a shell with the dev cluster:

make shell

The working directory for that shell is mapped to the working directory of your local Furem Cape source code, so you could, for example, run the analyzer script within it by running the following command in the shell:

make shell
analyzer/bin/analyzer.py --help

The ports for the hitdb and issuedb databases in the dev cluster are also mapped to ports on your local machine, so if you have a PostgreSQL client installed on your local machine, you can use it to connect to the hitdb or issuedb databases from the dev cluster and load data into them, or otherwise inspect them or play around with them. The hitdb database is mapped to port 5775, so you could run the following command to access it:

psql -h localhost -p 5775 hitdb hitdb
hitdb=> select * from hit limit 10;

The issuedb database is mapped to port 5776, so you could run the following command to access it:

psql -h localhost -p 5776 issuedb issuedb
issuedb=> select * from issue limit 10;

Test on a Real Environment

To deploy your changes to an existing, live Furem Cape install, commit your changes to a working branch in Git, and generate a tarball from the source with the git archive command:

git archive --output ~/furemcape.tar.gz HEAD

Copy that tarball to the server you want to try it on, and follow the instructions on the Upgrade page to deploy it.

Clean up Commits

Once you have your changes working, clean up your code into one or more Git commits that represent logical changes to the existing codebase. Commit messages should follow the seven rules from How to Write a Git Commit Message:

  1. Separate subject from body with a blank line

  2. Limit the subject line to 50 characters

  3. Capitalize the subject line [optional for Furem Cape, but recommended]

  4. Do not end the subject line with a period

  5. Use the imperative mood in the subject line

  6. Wrap the body at 72 characters

  7. Use the body to explain what and why (not how)

If the patch fixes a bug that is not in our issue tracker and is not trivially reproduced, please include the bug details and reproduction steps in the commit message (see the Bugs page for what details you should include). Or alternately, create a ticket for the bug in our issue tracker, and then just include a link to the ticket in the commit message in place of the full bug details (but still please include enough “what and why” information in the commit message to understand what the commit changes and why it was done that way).

Commit messages should also include a Signed-off-by line at the end of the body (see the Sign Off section).

Following is a checklist for cleaning up your commits:

  • Update or create any documentation in the docs sub-project relevant to your changes

  • Rebase against the tip of master (or to whichever release the patch applies) from the official repo

  • Review the diffs of all commits to ensure unwanted/unnecessary/unrelated changes are not included (Tig is a delightful command-line tool that can help you browse through your changes)

  • Ensure your commit messages follow the above seven rules, and include a Signed-off-by line

  • Run make check to ensure all linting and tests pass

Sign Off

All patches submitted to the Furem Cape project must include a Signed-off-by line to certify that you are submitting it in accordance with the terms of the Developer Certificate of Origin (DCO). This certifies that you are either the author of the submitted content, or have the right to submit it under the open source license used by Furem Cape (the MIT License).

The Signed-off-by line must include your real name (the name with which you sign legal documents), and the email address you used to submit the patch, like so:

Signed-off-by: Alice X Developer <alice@example.com>

You can add a Signed-off-by line automatically to commit messages by including the --signoff option with the git commit command; or you can just add your Signed-off-by line manually to the bottom of each commit message.

If you forget to sign-off on a patch, you can just reply to the patch email thread with a message like “I certify the preceding patches in this thread were contributed in accordance with the DCO”, followed by your Signed-off-by line (or if you submitted the patch by tracker, add a comment like “I certify the preceding patches in this ticket were contributed in accordance with the DCO”, followed by your Signed-off-by line). Alternately (or if there might be some confusion as to which content you’re referring), you can just resubmit the full patch with your Signed-off-by line included.

Submit via Email

Send patches to our development list at ~arx10/furemcape-dev@lists.sr.ht. You don’t need to introduce yourself or subscribe, just send the patch – all contributions are appreciated!

The easiest way to send a patch is with the git send-email command. The Git Send-Email site provides a nice tutorial for how to configure Git and use the git send-email command. You can also send patches manually to the list with an email client that supports plain-text content.

Or Submit via Tracker

If submitting a patch via email seems too daunting or unfamiliar, you can instead create a ticket for the patch in our issue tracker at https://todo.sr.ht/~arx10/furemcape. Generate the patches to submit with the git format-patch command; for example, the following would export the last 3 commits from your working branch to the my-furemcape-patch.txt file in your home folder:

git format-patch -3 --stdout > ~/my-furemcape-patch.txt

Open up that file in a text editor, and copy and paste its contents into the ticket’s description. See the Git Format-Patch manual page for more options with the git format-patch command.

Alternately (or if the patch is really big), if you’ve pushed a branch with the patch to a publicly-accessible repository (like on GitHub, GitLab, sourcehut, etc), you can just include a link to that repository and branch information in the ticket instead of the full patch content. The git request-pull command produces nicely formatted output for this purpose (but doesn’t do anything special that you can’t just as easily enter into the ticket manually).