Skip to content

Latest commit

 

History

History
79 lines (60 loc) · 4.05 KB

CONTRIBUTING.md

File metadata and controls

79 lines (60 loc) · 4.05 KB
Raw

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, the Apache License 2.0 LICENSE

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 DCO

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.

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 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)
    • 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:

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.