The Art of the Git/Gerrit Commit at Eclipse
With the adoption of Git and Gerrit, and the implementation of the new Contributor License Agreements (CLA) as part of our social coding efforts, contributing to Eclipse projects has never been easier. While it is easier, there are still important requirements that need to be met..
We’ve implemented some extensions to Git and Gerrit that check to make sure that commit records are structured as required, and reject those commits that are malformed.
Below is an example of a good commit record:
commit 862e6ff22ad56c10df6de3385ffa4c7d02363d1d Author: Joe Somebody <firstname.lastname@example.org> Date: Mon Jun 17 17:19:38 2013 -0700  Auto share multiple projects in single job When multiple projects are imported together, perform all the necessary auto shares in a single job rather than spawning a separate job for each project. Signed-off-by: Joe Somebody <email@example.com> Bug: https://bugs.eclipse.org/bugs/show_bug.cgi?id=410937 Also-by: Some Otherperson <firstname.lastname@example.org>
First and foremost, the author of a commit must either be a committer on the project accepting the commit, or must have a signed CLA. Even if you are an Eclipse committer on one project, you need to have a CLA to contribute to another.
For contributions from non-committers, the “Author” field on the commit must contain the same email address that was used to sign the CLA. It is case-sensitive. The same email address (also case-sensitive) must be used in the “Signed-off-by” field in the message footer.
The location of the Signed-off-by is important. It must appear in the footer of the message. The footer is last block of continuous lines of text in the comment (See Bug 412140). There can be no blank lines between the line containing the “Signed-off-by” field, and the end of the comment.
There is an evolving convention (not a requirement) to include a “Bug” field in the footer with a link to the bug report that corresponds to the commit (if any). There is another convention to include the bug id in square braces on the first line of the commit message. Projects can decide what convention they choose to follow; picking one (or both) of these, will make eventual automation easier (the IP Log generator will, for example, make a hyperlink).
I encourage you to include “Also-by” fields if a commit contains code authored by more than one individual. The primary author should go in the “Author” field, and each additional author should get their own “Also-by” entry. If it’s not clear who the primary author is, then I recommend a vigorous game of Rock/Paper/Sissors/Lizard/Spock to sort it out. We don’t currently do anything with the “Also-by” fields, but I do intend to extend the IP Log generator to consider these values.
The Gerrit plugin and Git hook will reject any commits that aren’t well formed and provide an explanation on the console like the following:
The contributor must "sign-off" on the contribution. Processing changes: refs: 1 Processing changes: refs: 1, done ---------- Reviewing commit: commit 8a557cb70698e70de77df056b022f197700d1761 1366109485 ----sp Authored by: Joe Somebody <email@example.com> The author is not a committer on the project. The author has a current Contributor License Agreement (CLA) on file. error: The author has not "signed-off" on the contribution. Please see http://wiki.eclipse.org/CLA
If you find yourself staring at a commit trying to consolidate the error message against what you see in your commit message, take a hard look at the commit id. Git and Gerrit look at all of the commits that you push and sometimes there’s an extra merge commit in the push that will mess you up. I’m thinking that it might make sense to just ignore merge commits since they don’t contain any IP. If you agree, please open a bug.
There’s more information regarding the handling of Git commits in the wiki.