EMF Compare/Gerrit

Configuring the repository

This guide outlines a number of command line instructions. They can be followed on either linux or windows, use a console (linux) or msysgit (windows).

Creating a User Account

• You need an Eclipse user account. You already have one if you are an Eclipse commiter or have a Bugzilla account. Otherwise, use this form.
• You should now be able to logon to the Gerrit Web UI (top-right corner of the page) using the email address you registered with your Eclipse (and/or Bugzilla) account and your Eclipse password.

Update repository information

Your user name and email should match the information you've provided to Eclipse. From the command line, use the following (change any <bold> text to your own info) :

$ cd <path/to/repository>
$ git config --local user.name "<Full Name>"
$ git config --local user.email "<your.mail@yourmail.com>"

Intellectual Property through CLA

The contribution process has changed, instead of the usual "three questions", we need you to sign a Contributor License Agreement (CLA). Please go to [1] , then to the CLA tab once you're logged in and follow the instructions. Please have a look at Contributing via Git for the details.

Once you have signed the CLA once, you'll never have to do it again (well, it does need to be renewed every three years), gerrit will automatically check for your credentials when you push a review.

By signing the CLA you are essentially stating that:

• You have authored 100% of the content you are contributing
• You have the rights to donate the content to Eclipse
• You contribute the content under the EPL

If you don't agree the above restrictions, you wouldn't be able to contribute to any Eclipse project.

SSH

• Your username is what is displayed in Gerrit.
• You need to upload your public SSH key here. Follow the instructions below if you do not know how.

Generating and uploading SSH keys

First of all, please follow the guide on Github up to Step 4.

For windows machines, use Puttygen to generate your SSH keys. These keys should be saved to your .ssh folder under /Users/<username>/.ssh, with names "id_rsa" for the private one, "id_rsa.pub" for the public.

You now have a public SSH key, you need to upload it to gerrit.

First, use the following command :

$ clip < ~/.ssh/id_rsa.pub

This will copy your full SSH key in the clipboard. In windows machines, use any text editor like Notepad++ to open the public key, select the text and copy it to your clipboard.

Then, in the settings of Gerrit, click "Add Key".

Do not enter anything manually, simply right-click the text field that appears and select "Paste". Click the Add button without changing the pasted text.

Adding a new remote

Using the command line or msysgit, use the following (change any bold text to your own info, remember that your username is displayed here) :

$ cd <path/to/repository>
$ git config remote.review.url ssh://<username>@git.eclipse.org:29418/emfcompare/org.eclipse.emf.compare.git
$ git config remote.review.push HEAD:refs/for/master

This will allow you to push review requests on the Gerrit of EMF Compare using only :

$ git push review

Note that your commit messages will need to contain a Change-Id for the review. See the section on Change-Ids below.

Requesting a Review

Use a single commit

In order to submit a patch for review on Gerrit, you will need to make sure that the change you wish reviewed is contained in a single commit. When you start working on a patch for EMF Compare, please make sure to always amend the commit that will be pushed for review instead of creating new ones. This is done through:

git commit -a

If you had already started working on that change and have an history of commits related to it, you will need to squash them together as a single one. This can be done through an interactive rebase, using git rebase -i. Let's suppose that you have two commits that relate to the same change and should be reviewed as one:

$ git rebase -i HEAD~2

pick ******* first commit
squash ******* second commit

[detached HEAD *******] squashed commit
 1 files changed, 4 insertions(+), 0 deletions(-)
Successfully rebased and updated refs/heads/master.

Your history will then look like this:

$ git log
commit xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Author: J. Git <j.git@example.com>
Date:   Fri Mar 08 11:33:52 2013 +0100

    squashed commit

This commit contains the merged changes from both of those you previously had, and can be pushed for review.

About Git Commit Messages

Your commit message must follow the proper guidelines, as follows (from the Git WikiBook):

Short (70 chars or less) summary of changes (does NOT end with a full stop)

More detailed explanatory text, if necessary.  Wrap it to about 70
characters or so.  In some contexts, the first line is treated as the
subject of an email and the rest of the text as the body.  The blank
line separating the summary from the body is critical (unless you omit
the body entirely); tools like rebase can get confused if you run the
two together.

Write your commit message in the present tense: "Fix bug" and not "Fixed
bug."  This convention matches up with commit messages generated by
commands like git merge and git revert.

Further paragraphs come after blank lines.

- Bullet points are okay, too

- Typically a hyphen or asterisk is used for the bullet, preceded by a
  single space, with blank lines in between, but conventions vary here

- Use a hanging indent

If your commit relates to an Eclipse bug, please add its number in both the header and suffix of your commit message as shown in the examples below.

In a Nutshell

• First line is a summary that must fit in 70 characters. It is separated from the comment body with a blank line.
• Paragraphs may be used to explain the change in detail, they are separated by a blank line. Each line should be wrapped at 70 characters.
• The footer is separated from the body with a blank line. It contains all additional info:
  • Bug: xxxxxx - If the commit is related to a bugzilla, it is the first item of the footer.
  • Change-Id: ... - A Gerrit Change-Id footer is required for all changes pushed to Gerrit (to enable pushing new patchsets for the same change), see below for more on this.

Examples

Short commit (title line is self-explanatory or it is linked to a bugzilla that explains it all) :

[400221] Make mergers extensible

Bug: 400221
Change-Id: I41bb9ab74001e0c94ecb26ffec88cecf599a67be

Reveal the selection when possible

Complex commit (title line is only a summary, with more detailed explanations about what has been done in the comment "body") :

Resource attachment completion.

We now detect resource attachment changes not only for root matches, but
also for cross references. This allows us to detect a wider range of
potential changes, notably the control/uncontrol case.

The implementation is functional for control/uncontrol changes, as well
as addition/deletion of roots in a resource.

Gerrit Change-Id

A Change-Id is required for all changes pushed to gerrit. Any commit that you try and push for review will be rejected if the footer does not hold an entry for this. Basically, when you try and push a review to gerrit with no Change-Id, this is the kind of output you will see:

$ git push review
Enter passphrase for key '******':
remote: Resolving deltas: 100% (1/1)
remote: Processing changes: refs: 1, done
remote: ERROR: missing Change-Id in commit message
remote: Suggestion for commit message:
remote: Example commit - Change-Id
remote:
remote: Change-Id: Ixxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
 ! [remote rejected] HEAD -> refs/for/master (missing Change-Id in commit message)

All you have to do from there is to add the proposed identified as a footer of your commit message. For that, you can use

git commit --amend

and change only the message, copy/pasting the "Change-Id" line as a footer.

You can automatically generate the Change-Id using EGit. Right-click the project for which you have changes and use Team > Commit. In the popup, tick all three buttons on the top-right side: the first will allow you to modify the previous commit (if you have already made the commit containing your patch), the second will add the mandatory "Signed-off-by" footer element that should contain the credentials, the third and last one will generate a Change-Id for gerrit (all you will see is a bunch of zeros, this is normal, the commit will actually have a proper id once done).

PENDING this can be done automatically though the use of the commit-msg git hook, needs instructions.