Contributing

Contributions are welcome!

Contributions can be bug reports, feature requests, testing and documentation in addition to code. Please see the github guide on Collaborating on projects using issues and pull requests for details.

Contributions to this project are accepted on an "inbound=outbound" basis. That means that you agree that your contributions are made under the same license as the license for this project (found in the in the LICENSES directory).

To make this understanding explicit -- and for you to assert that you have the right to make the contribution -- commits must be signed off indicating acceptance of the Developer Certificate of Origin 1.1. A nice explanation of the DCO has been provided by Karl Fogel in his excellent book Producing Open Source Software. An explanation of the "sign-off" procedure is given by Linus Torvalds in Linux.

Code of Conduct

Please note that this project is released with a Contributor Code of Conduct (adopted from the Contributor Covenant v2.0).

By participating in this project you agree to abide by the Contributor Code of Conduct (please read the full text so that you can understand what actions will and will not be tolerated).

AI-Assisted Project Contributions

You may use AI assistance for contributing to this project in accordance with these principles of accountability and transparency.

Accountability

When you submit a contribution, you represent that you are the author and that you are fully accountable for the entirety of the contribution.
You are responsible for your contribution, including vouching for the quality, license compliance, and utility of your submission.
Using AI assistance in your contribution does not relieve you of the responsibility to ensure that your contribution meets project standards; your contributions must be modular, reviewable, and clearly explainable.

Transparency

You must disclose the use of AI tools when a significant part of the contribution is generated without changes.
You should disclose the use of AI tools where it might be helpful to the maintainer reviewing your contribution.
Using AI tools to correct grammar and spelling does not require disclosure.
Make your disclosure in your commit message as a trailer; e.g. Assisted-by: ChatGPTv5
Use the tag "AI" on pull requests that were primarily generated or guided by AI tools

Scope and Cadence

Prefer one concern per PR. Bug fixes, refactors, and documentation updates belong in separate PRs even when they touch the same file.
For mechanical changes that span many files or services (e.g. pattern sweeps), split into per-target PRs and open no more than two per week so review stays tractable.
Before a large or cross-cutting change, open an issue or discussion first to align on scope.

Contribution Workflow

This is an overview of the contribution workflow:

Fork the repository on Github
Create a topic branch from where you want to base your work (usually from the master branch)
Check the formatting rules from existing code (no trailing whitespace, mostly default indentation)
Ensure any new code is well-tested, and if possible, any issue fixed is covered by one or more new tests
Make commits to your branch using the following guidelines:
- Start with a subject line (beginning with a capital, ending without a period, no more than 50 characters)
- The second line should be blank
- The body starts on the third line and may reference existing issues (e.g. Closes #1)
- Use the imperative mood in the subject line: "Add x", "Fix y", "Support z", "Remove x"
- Wrap the body at 72 characters
- Use the body to explain what and why vs. how
- Finish the commit message with the sign off: Signed-off-by: Your Name <me@e.mail>
Push your code to your fork of the repository
Make a Pull Request

Emacs

Are you an Emacs user? If so you can use magit-commit-popup (from magit) to add these commit options for you:

-s Add Signed-off-by line (--signoff)
=S Sign using gpg (--gpg-sign="0xCAFED00D") -- this is extra credit

Did you know that Emacs can delete trailing whitespace without you every having to think about it? Just add this to your Emacs configuration:

(add-hook 'before-save-hook 'delete-trailing-whitespace)

Verified commits with GPG

Verifying commits is not essential for contributions to this project, but for those motivated to add additional security it is important to know that Github now supports GPG signature verification.

Using GPG is a complex subject. Here are some pointers for further information:

OpenPGP Best Practices
Debian Keysigning HOWTO
If you create a new key please ensure that the RSA key length is at least 4096 bits and configured for SHA-2
If you use caff (from signing-party) to sign and distribute signatures please verify that the separate caff configuration is accurate.

You can export your GPG public key to a file for use with Github as follows (assuming your GPG key id is 0xCAFED00D):

gpg --output 0xCAFED00D.asc --armor --export-options export-clean,export-minimal --export 0xCAFED00D

Simply paste the contents of that file in the SSH and GPG keys section of your Github settings.

6.3 KiB Raw Blame History