Contribution Guidelines

Thanks for considering contributing! My projects all follow the guidelines outlined in this document.

TL;DR

If you just want to fix a typo or another very small thing, just create a PR.

Documentation

As the author of a tool or library, we are blind to many of the problems that users may encounter. As an external person, you have the power to spot this! Feel free to open an issue or to send a PR with proposed changes to the documentation.

Code

Pull Request

• It is advisable, but not mandatory, to create an issue to discuss the feature you want to add, so that you can make sure it has good chances to be merged. This also avoids having multiple persons working on the same thing.
  • Similarly, feel free to create a draft PR with your changes before they are completed. This is useful to point to a particular part of the code during discussions.
• Try to create one pull request per high level feature or bug fix. Then if necessary try to stage your changes by crafting multiple commits: if your commits follow a progression on your changes, it’ll be easier to review.
• New features need to be covered by adding new unit tests, where applicable. Similarly, bug fixes need to be accompanied by a regression test where applicable, to ensure that the bug does not come back. Reviewers and maintainers are in charge of enforcing this.

I Don’t Want to Use GitHub

That’s fine, feel free to send your contributions by email¹ to the address listed on the Contact page.

If you are contributing this way, please use the -s or --signoff with each commit, so that a Signed-off-by trailer is added to each of your commits. Or manually add a Signed-off-by trailer at the end of your commits, like this:

Signed-off-by: Put Your Name Here <[email protected]>

This signifies your agreement with the DCO below.

I Don’t Know What to Do

If you don’t know what to do, but still want to help, that’s great! Look for issues labeled good-first-issue or help-wanted. You can also contact me, and tell me about your interests and skills.

Dependencies

As much as possible, I limit the number of dependencies used in my projects. Please avoid introducing new dependencies in your PRs if possible. The fewer dependencies, the better. The dependencies actually included should be relatively popular and from trusted authors, as I can’t audit any of them.

Delegating Trust

In light of the XZ-backdoor and many other supply-chain attacks, I can’t give commit permissions lightly.

As a result I don’t delegate commit rights unless:

1. I’ve known someone in person for years, and
2. they have established a track-record of contributions.

It may mean that a project goes abandoned or doesn’t improve as quickly. Or that it is overtaken by a fork that gets more attention. That’s fine. It’s the tradeoff I make. I would rather a fork succeed than letting a nefarious actor inherit the trust I’ve built.

Hobby Project: Take It Slow

My projects are hobby projects. They are done during my, and contributor’s, free time. It may mean that your comments or PR may go unanswered for days or weeks. I value comments, PRs and otherwise constructive interactions. It’s part of the joy of working on Open-Source software for me. But I may not have bandwidth to review some changes in a timely manner. I’m not a full-time Open-Source maintainer. Yet at least. That’s life.

Equally, as a contributor, please feel free to say that you don’t have time or energy anymore. You can do that even in the middle of a PR. Someone else can always pick it up.

We are here to have fun developing software. We don’t owe anything² to consumer of our software. After all, our Open-Source licenses disclaim as much.

Code of Conduct

To foster a welcoming environment, we also follow and enforce a code of conduct.

Meaning of “Signed-off-by” Lines in Commit Messages

When Signed-off-by trailers are used, it means that the committer agrees to the representations from the Developer Certificate of Origin (DCO), reproduced below:

Developer's Certificate of Origin 1.1

By making a contribution to this project, I certify that:

(a) The contribution was created in whole or in part by me and I
    have the right to submit it under the open source license
    indicated in the file; or

(b) The contribution is based upon previous work that, to the best
    of my knowledge, is covered under an appropriate open source
    license and I have the right under that license to submit that
    work with modifications, whether created in whole or in part
    by me, under the same open source license (unless I am
    permitted to submit under a different license), as indicated
    in the file; or

(c) The contribution was provided directly to me by some other
    person who certified (a), (b) or (c) and I have not modified
    it.

(d) I understand and agree that this project and the contribution
    are public and that a record of the contribution (including all
    personal information I submit with it, including my sign-off) is
    maintained indefinitely and may be redistributed consistent with
    this project or the open source license(s) involved.

This is the DCO used by the Linux kernel and Git projects.

When a Signed-off-by trailer is not present, we are relying on any provisions of the project’s license. In addition, if the contribution was submitted through GitHub, the GitHub Terms of Service apply, in particular Section D.6 (archived version).

6. Contributions Under Repository License

Whenever you add Content to a repository containing notice of a license, you license that Content under the same terms, and you agree that you have the right to license that Content under those terms. If you have a separate agreement to license that Content under different terms, such as a contributor license agreement, that agreement will supersede.

[…]

See Also

The other Open-Source documents.