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 <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.

About these ads
This entry was posted in Community, Eclipse 101. Bookmark the permalink.

3 Responses to The Art of the Git/Gerrit Commit at Eclipse

  1. BJ Hargrave says:

    Merge commits can contain changed files. A merge commit is just a commit with more than one parent commit.

  2. Pingback: Mylyn, EGit, and Your Commit Message | Eclipse Hints, Tips, and Random Musings

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s