You can propose contributions by sending pull requests (PRs) through GitHub. Following these guidelines will help us merge your pull requests smoothly:
-
Your pull request is an opportunity to explain both what changes you'd like pulled in, but also why you'd like them added. Providing clarity on why you want changes makes it easier to accept, and provides valuable context to review.
-
Follow the commit guidelines found below.
-
We encourage you to open a pull request early, and mark it as "Work In Progress", by prefixing the PR title with "WIP". This allows feedback to start early, and helps create a better end product. Committers will wait until after you've removed the WIP prefix to merge your changes.
The first line describes the change made. It is written in the imperative mood, and should say what happens when the patch is applied. Keep it short and simple. The first line should be less than 70 characters, where reasonable, and should be written in sentence case preferably not ending in a period. Leave a blank line between the first line and the message body.
The body should be wrapped at 72 characters, where reasonable.
Include as much information in your commit as possible. You may want to include designs and rationale, examples and code, or issues and next steps. Prefer copying resources into the body of the commit over providing external links. Structure large commit messages with headers, references etc. Remember, however, that the commit message is always going to be rendered in plain text.
Use the commit footer to place commit metadata. The footer is the last block of contiguous text in the message. It is separated from the body by one or more blank lines, and as such cannot contain any blank lines. Lines in the footer are of the form:
Key: Value
When a commit has related issues or commits, explain the relation in the message
body. You should also leave an Issue tag in the footer. For example:
Correct race in frobnicator
This patch eliminates the race condition in issue #1234.
Fixes: #1234
Sign off on your commit in the footer. By doing this, you assert original
authorship of the commit and that you are permitted to contribute it. This can
be automatically added to your commit by passing -s to git commit, or by
manually adding the following line to the footer of the commit.
Signed-off-by: Full Name <email>
Remember, if a blank line is found anywhere after the Signed-off-by line, the
Signed-off-by: will be considered outside of the footer, and will fail the
automated Signed-off-by validation.
When appropriate, use the keywords described in the following help article to automatically close issues. https://help.github.com/articles/closing-issues-using-keywords/
Here is an example of a good commit:
Update and expand the commit guidelines
Elaborate on the style guidelines for commit messages. These new
style guidelines reflect the conversation found in #124.
The guidelines are changed to:
- Provide guidance on how to write a good first line.
- Elaborate on formatting requirements.
- Relax the advice on using issues for nontrivial commits.
- Move issue references from the first line to the message footer.
- Encourage contributors to put more information into the commit
message.
Closes: #124
Signed-off-by: Robert Young <[email protected]>
The first line is meaningful and imperative. The body contains enough information that the reader understands the why and how of the commit, and its relation to any issues. The issue is properly tagged and the commit is signed off.
The following is a bad commit:
FIX #124: Changing a couple random things in CONTRIBUTING.md.
Also, there are some bug fixes in the thread library.
The commit rolls unrelated changes together in a very bad way. There is not enough information for the commit message to be useful. The first line is not meaningful or imperative. The message is not formatted correctly, the issue is improperly referenced, and the commit is not signed off by the author.