Submit a Patch

We welcome and appreciate all patches, big and small!

If there is a major change or feature to Pro Custodibus 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 the mailing list (or submit it to the issue tracker) for discussion and feedback.

For everything else, please follow this process:

Develop Locally

Develop off the tip of the main branch from the official procustodibus-api, procustodibus-app, and procustodibus-agent Git repositories. See the Development page for instructions on how to set up a development environment for each component.

Test Locally

Run the make check task for the API and app components to run all linting and tests. Run the tox task for the agent to run all of its linting and tests.

See the Testing page for instructions on how to set up and test the components together in an integrated environment.

Test on a Real Environment

Optionally, deploy your changes to a live environment for further manual testing. See the Build On-Premises page for instructions on how to build a deployable package for each component.

Clean up Commits

Once you have your changes working to your satisfaction, 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 Pro Custodibus]

  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 the issue tracker and is not trivially reproduced, please include the bug details and reproduction steps in the commit message (see the File a Bug page for what details you should include). Or alternately, create a ticket for the bug in the 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 explain what the commit changes and why it was done that way).

Use this checklist to clean up your commits:

  • Rebase against the tip of main (or whatever branch 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 nice command-line tool that can help you browse through your changes)

  • Ensure your commit messages follow the above seven rules

  • Run make check (or tox) to ensure all linting and tests pass

Submit via Email

Send patches to the mailing list at ~arx10/procustodibus@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 the issue tracker at https://todo.sr.ht/~arx10/procustodibus. 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-procustodibus-patch.txt file in your home folder:

git format-patch -3 --stdout > ~/my-procustodibus-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 it doesn’t do anything special that you can’t simply enter into the ticket manually).

Contributor License Agreement

You must have a Contributor License Agreement (CLA) on file with Arcem Tene in order for your patches to be merged into the official Git repos. The CLA is based on the Harmony Contributor Agreement Templates. It allows Arcem Tene to use your patches in all of their current or future projects under any license they choose; while you retain full ownership of the patches, with the right to use them independently in any of your own current or future projects (under any license you choose).

If your employer owns the copyright to the patches, you must have an authorized representative of your employer agree to and sign the Entity CLA. Otherwise, agree to and sign the Individual CLA. (Both versions are nearly the same, differing mainly in the wording around the definition of “You”.)

Use your legal name when signing the CLA (eg “Robert Roberts Jr.”); separately list out the names or handles you may use when submitting contributions to Pro Custodibus (eg “Bob Roberts, broberts@example.org, https://todo.sr.ht/~bobr”). Send the signed CLA to community@arcemtene.com.