diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000000..c66757d142 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,132 @@ + + +## Submitting a contribution to OpenJ9 OpenJDK JDK9 extensions + +You can propose contributions by sending pull requests (PRs) through GitHub. +Following these guidelines will help us merge your pull requests smoothly: + +1. 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. + +2. Follow the commit guidelines found below. + +3. 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. + +## Commit Guidelines + +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 +``` + +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/ + +### Example commits + +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 +``` + +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. + +### Other resources for writing good commits + +- http://chris.beams.io/posts/git-commit/ +- https://alistapart.com/article/the-art-of-the-commit +- https://wiki.openstack.org/wiki/GitCommitMessages +- http://ablogaboutcode.com/2011/03/23/proper-git-commit-messages-and-an-elegant-git-history