git contribution submission

Thanks for your interest in contributing to my projects! This document describes the patch submission process, my expectations for submissions, and contains information to know before getting started.

License

Unless otherwise specified, the content hosted here is released in the public domain; specificly, according to the language of the Unlicense. Some projects even make this explicit by including a copy of the text in their source trees.

In general, by contributing, you agree that the contribution is made available to me, and to the public, under the terms of the applicable license. If in doubt, check with a file named UNLICENSE, LICENSE, or COPYING in the project source tree.

Developer Certificate of Origin

You can add a Signed-off-by trailer automatically while creating commits, applying patches, or rebasing commits.

$ git commit -s
$ git am -s
$ git rebase --signoff

Code Style

There are no global, hard-and-fast rules on code style. However, patches may not be accepted if they are much different than their surrounding context. Beyond that, keep the following preferences in mind:

Commit Messages

Commit message style guide for Git

The first line of a commit message serves as a summary. When displayed
on the web, it's often styled as a heading, and in emails, it's
typically used as the subject. As such, you should capitalize it and
omit any trailing punctuation. Aim for about 50 characters, give or
take, otherwise it may be painfully truncated in some contexts. Write
it, along with the rest of your message, in the imperative tense: "Fix
bug" and not "Fixed bug" or "Fixes bug". Consistent wording makes it
easier to mentally process a list of commits.

Oftentimes a subject by itself is sufficient. When it's not, add a
blank line (this is important) followed by one or more paragraphs hard
wrapped to 72 characters. Git is strongly opinionated that the author
is responsible for line breaks; if you omit them, command line tooling
will show it as one extremely long unwrapped line. Fortunately, most
text editors are capable of automating this.

Select your submission method

Patches via email

Unless more specific advice is given by the project, send patches directly to me: m@lfurio.us and include the project name in the [PATCH] subject prefix, since the address is not a dedicated list for any specific project.

It is recommended to include a cover-letter when sending multiple commits, though this is not required. Keep in mind that the cover-letter contents do not get recorded in the commit history.

The -v option should be used when sending a follow-up edit for a previous patch -- eg: -v2, -v3, -v4, etc...

$ git send-email --to=m@lfurio.us [-v<n>] origin/master \
--subject-prefix='PATCH <project_name>'

# to include cover-letter, add:
--cover-letter --annotate

Pull request via email

This method will require you to push your commits to a publicly-accessible git repository, along with an annotated tag associated with your pull request. Your tag should have a descriptive name which I prefer to begin with the word 'pull'. For example, pull-new-feature-x.

It is strongly preferred that your tag be signed by a PGP key whose name and email match the address you are sending the request from. However, your request may not be rejected for this reason alone.

Please write a descriptive message in the body of the git tag, following the same style for commit messages. This message will be recorded in the git commit history (via the merge commit) and should summarize the changes introduced by your branch.

Once everything is pushed, generate your request to send using git-request-pull. Giving it the correct 'start' revision is important, so that the generated log and diffstat are accurate. Remember to use your tag name for 'end' instead of master or HEAD.

Copy the output text into an email message. Unless more specific advice is given by the project, send PRs directly to me: m@lfurio.us and include the project name in the [GIT PULL] subject prefix, since the address is not a dedicated list for any specific project. The full subject line should look like [GIT PULL <project_name>] ##Your PR subject here##.