Setting up user information
Please set up consistent user information before starting with your real
name and working\
email address on all your computers. For quick reference, here are the
git config --global user.name "Your Name Comes Here"
git config --global user.email email@example.com
Create a new branch starting from
master. Each branch should contain
logically related commits (for example the implementation of a single
feature), not a mixed bag of random changes.
If your change is depending on some other fix or feature that is not in
master yet, you may start from
next, but be aware that there is a
small risk that the branch will be rebased.
Committing the patch
- Make separate commits for separate changes. If you cannot describe
what the commit does in one sentence, it is probably a mix of
logically separate changes and should be separated into several
- Make sure that each commit can be compiled and that it works.
- Use the imperative mode in the commit message when describing what
you have done: use “change”, “add”, “fix”, not “changed”, “added”,
“fixed”. Use the present tense to describe the current
implementation: “feature X has an enormous potential for
improvements” rather than “feature X had an enormous potential…”
(While this writing style may seem awkward to begin with, you’ll
find that it is actually easier to read and write.)
- The first line of the commit message should describe concisely
what the commit does. Leave out the full stop. (This line will be
gitk or in
git log --oneline, so it should be
understandable by itself.)
- The second line in the commit message should be blank.
- The body of the commit message should primarily answer the
question why? rather than how?. That is, the most important is
why the change was made, what bug it corrected or why anyone would
want to use the new feature it implements. (Imagine yourself five
years in the future trying try to figure why anyone would ever want
this feature…) Technical details can also be useful, especially why
one design was chosen rather than another design (again, imagine
yourself investigating a bug and wondering why would anyone chose
this way to implement this feature…).
- Line break the commit message to lines no longer than
approximately 70 characters (otherwise they are difficult to read in
- Do not commit out-commented code or files that are no longer needed.
- Check for unnecessary whitespace before committing with
git diff --check.
Sending the patch
Use the “Pull request” button at GitHub.
Receiving your patch
When we receive your patch, we will do one of the following:
- If there are simple things that will need to be fixed (for example,
providing more information in the commit message instead of in the
email), we may ask you to do that.
- Otherwise, if your patch is not obviously wrong or inappropriate, we
will merge it to the
pu (“proposed updates”) branch.
- Otherwise, if it is obviously wrong or inappropriate, we will tell
you so. Reasons for immediate rejections include (but are not
- Blatantly breaking backward compatibility.
- Obviously unsafe coding practices or highly non-portable
- Mixing of many difference changes and/or unnecessary
re-indentation of code that is not changed. We will ask you to
separate the changes into separate commits and/or branches and not
change indentation of unchanged code.
You should not base any branches on
pu branch, as it will be
rewinded (rebuilt from scratch) frequently.
Patches will “cook” in the
pu branch until they graduate or are
The following may happen to a patch (one or more times):
- If build problems are found or there are many failing test cases not
found before it was been included in
pu, it may be removed from
pu until the problems have been fixed.
- Anyone can criticize, suggest improvements, or report that a patch
breaks existing applications. If the serious problems remain, and no
good way of fixing them can be found, the patch may be dropped.
- Patches with known issues that have been inactive for a long time
(several months) will be dropped.
This page is adapted from the similar page from the erlang/otp wiki,
but any errors are entirely ours.