Submit a Patch¶
We welcome and appreciate all patches, big and small!
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 ~email@example.com. It’s archived at https://lists.sr.ht/~arx10/furemcape-dev. You can subscribe to it by sending an email to ~firstname.lastname@example.org (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:
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
analyzer, etc (see the Design page for details). Most of the source code is Python, written in the standard style, enforced by
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
make help to see the list of all available Make tasks.
Run the following to lint the entire project:
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:
Run the following to run all the project tests (including end-to-end tests) in Docker containers:
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:
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:
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
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
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
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
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;
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:
Separate subject from body with a blank line
Limit the subject line to 50 characters
Capitalize the subject line [optional for Furem Cape, but recommended]
Do not end the subject line with a period
Use the imperative mood in the subject line
Wrap the body at 72 characters
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
docssub-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
make checkto ensure all linting and tests pass
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).
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 <email@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 ~firstname.lastname@example.org. 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).