DevOps Zone is brought to you in partnership with:

Wayne Beaton is employed by The Eclipse Foundation where he works as an evangelist, spreading the word and helping folks adopt Eclipse technologies. Wayne has extensive experience in object-oriented software development and is a strong proponent of refactoring, unit testing, and agile development methodologies. He is also the editor-in-chief of Eclipse Corner, PMC Lead for the Technology Project, Project Lead for the Examples Project, and an advisor for osbootcamp. In 1982, he received the prestigious Chief Scouts Award from then-Governor General Edward Schreyer. In 1984 his team was selected to represent beautiful British Columbia in the Kinsmen Voyageur Relay. In his spare time, he writes down meaningless accomplishments from his youth in a lame attempt to impress the reader. Wayne is a DZone MVB and is not an employee of DZone and has posted 76 posts at DZone. You can read more from them at their website. View Full User Profile

The Art of the Git/Gerrit Commit at Eclipse

11.12.2013
| 9154 views |
  • submit to reddit

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 <somebody@someplace.net>
Date:   Mon Jun 17 17:19:38 2013 -0700

    [410937] 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 <somebody@someplace.net>‌
    Bug: https://bugs.eclipse.org/bugs/show_bug.cgi?id=410937
    Also-by: Some Otherperson <otherperson@someplace.net>

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 <somebody@someplace.net>

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.

Published at DZone with permission of Wayne Beaton, author and DZone MVB. (source)

(Note: Opinions expressed in this article and its replies are the opinions of their respective authors and not those of DZone, Inc.)