4. Gerrit Setup¶

Gerrit is a Git server that provides access control for hosted Git repositories and a web front-end for doing code review.

The Diamond Gerrit site can be found at gerrit.diamond.ac.uk with documentation including the Users Guide found here.

4.1. Developer Registration¶

Anonymous checkout is available for most repositories although not all as some are private and can be used if the goal is simply to download the code. However if you make changes that you want to contribute back to the community then you will need to register with the Diamond Gerrit instance. The steps to do so are given below. Note that you will need an ID to register with Diamond Gerrit. This can be obtained in two ways:

If you have an active Diamond Light Source FedID (userid), then use your existing FedID to register with our Gerrit.
If you do not have an active Diamond Light Source FedID (userid), then you will need to create an account on GitHub, and then use that GitHub account to register with our Gerrit.

NOTE: If you have previously registered with DLS Gerrit, but have forgotten your password…

The Gerrit administrator cannot recover your password for you. If you cannot recover the password yourself: DO NOT repeat DO NOT simply go and register a new account with Gerrit. Contact the Gerrit administrator, who will assist you to create a new Gerrit account that is linked to your old one.

Decide the full name and primary e-mail address you will use for committing changes

This is important because every Git commit uses this information, and its immutably baked into the commits you pass around.

Your full name should be in the form “Firstname Surname” (note the capitalisation).

If you will be committing code owned by your (direct or indirect) employer, your primary email address should be the one associated with that employment.

Configure git as follows

Option 1: from the command line

$ git config --global user.name "Jane Doe"
$ git config --global user.email janedoe@example.com
$ git config --list

Option 2: from within the Eclipse IDE

Window > Preferences > Team > Git > Configuration > User Settings
Add key=user.name value=Jane Doe
Add key=user.email value=janedoe@example.com

Generate an SSH keypair (if you don’t already have a suitable one)

SSH keys are used for authentication when cloning or pushing to repositories

If you don’t already have an SSH keypair, you will need to generate one

If you do already have an SSH keypair, you can either use that one, or generate an additional pair just for Gerrit use (recommended)

SSH keys are normally located:

On Linux machines, in ~/.ssh/. The default names are id_rsa (private key) and id_rsa.pub (public key).

On Windows machines, in C:\Users\%USERNAME%\.ssh\.

Generating an SSH keypair:

! Be careful: generating a new keypair might delete any existing one, so take care!

We recommend that you generate a new keypair, without a passphrase, that is used just for Gerrit (or Gerrit and GitHub)

You can generate a new keypair for use with Gerrit as follows:

ssh-keygen -t rsa -b 4096 -C "your_email@example.com"
Generating public/private rsa key pair.
Enter file in which to save the key (/home/you/.ssh/id_rsa): /home/you/.ssh/id_rsa-gerrit
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in /home/you/.ssh/id_rsa-gerrit.
Your public key has been saved in /home/you/.ssh/id_rsa-gerrit.pub.

There are also many instructions on the web about how to generate an SSH keypair, for example GitHub’s Generating SSH keys.

Alternatively, you can generate an SSH keypair from within Eclipse: Window Preferences > General > Network Connections > SSH2 (remember to save it)

Diamond Light Source users might want to look at the instructions on using a key pair to enable SSH between Diamond machines without entering your password (use the default SSH keypair, not your Gerrit-specific passphraseless one).

Never give your private key to anyone, and never upload it to any website. It’s called private for a reason!

(Optional) Register with GitHub

You only need to do this is you don’t have a Diamond Light Source FedID (userid)

DLS Gerrit can use external provider GitHub for authentication.

If you don’t already have one, register a GitHub username (it does not need to be the same as any other username you use elsewhere). Choose wisely!

Make a note of your GitHub username and password. If you forget them, you will be locked out of Gerrit and we cannot recover your access.

On GitHub under settings/profile, please fill in your full name in the form “Firstname Surname” (note the capitalisation)

Register and validate one or more email addresses. Include the primary e-mail address you selected in the first step, and any other addresses you choose.

Optionally, add your SSH public key to your GitHub account.

Check that you can connect from the command line to GitHub by following the instructions at https://help.github.com/articles/testing-your-ssh-connection/ - but note:

If you see a warning that looks like The authenticity of host ‘github.com (IP ADDRESS)’ can’t be established, then don’t type “yes” to continue, until you have verified the fingerprint. Otherwise, you risk a ‘man-in-the-middle’ attack.

Register with the Diamond Light Source Gerrit system

THIS SECTION ONLY APPLIES TO NEW DLS GERRIT REGISTRATIONS. Do not follow this if you already have a DLS Gerrit account, or think that you might!

In your browser, go to DLS Gerrit (suggestion: bookmark the page).

In the top right-hand corner, click “Sign In”, and then select which method you are using to register:

If registering using a DLS FedID: “Generic CAS OAuth2 (gerrit-oauth-provider plugin)”

If registering using your GitHub id: “GitHub OAuth2 (gerrit-oauth-provider plugin)”

Add your details to your Gerrit profile, which can be found by clicking on “Anonymous Coward” (top right-hand corner) and then Settings, as follows:

Under Profile, specify a username.

Switch to Contact Information, set your Full Name in the form “Firstname Surname” (note the capitalisation), and Save Changes.

Under Contact Information, add and validate the e-mail address(es) you selected in the first step, and set your preferred email to your primary email address.

You should get an email asking you to validate your e-mail address.

If email verification fails when you click on the verification link, copy and paste the URL into your browser - this ensures the final ‘=’ is included in the URL (since Microsoft Outlook strips it).

Switch to SSH Public Keys, paste your SSH public key without any embedded line breaks (it’s in the file whose name ends in .pub). The key will be one line of text that starts with ssh-rsa and ends with == (optionally followed by a comment).

You can upload additional public keys if required (for example, if you use multiple machines with distinct keys).

Don’t attempt to register with the DLS GerritBeta system (registrations there are copied from the production Gerrit system).

Set your SSH configuration in DLS Gerrit, and test it

Update the file (or create, if necessary) ~/.ssh/config (Linux) or C:\Users\%USERNAME%\.ssh\config (Windows) by adding the following lines:

# Gerrit does not support password-based ssh connections
# Not all Eclipse versions support ecdsa-sha2-* or ssh-ed25519 host keys
# Your Gerrit username is probably different from your local workstation username
# Gerrit ssh listens on port 29418, not the default 22

Host gerrit.diamond.ac.uk gerritbeta.diamond.ac.uk
    PasswordAuthentication no
    HostKeyAlgorithms ssh-rsa
    ForwardX11 no
    User <username>                      <-- Set your GERRIT username here (and delete this comment) !!
    Port 29418
    IdentityFile ~/.ssh/id_rsa-gerrit    <-- Set the filename if you generated an SSH keypair specifically for Gerrit (and delete this comment), otherwise remove this line

Check that the file permissions on ~/.ssh/config (Linux) are correct: they must be 0600 (rw-------)

Add the key for the Gerrit server to your known_hosts file (this enables ssh to verify that it is connecting to the real Gerrit, and not an imposter)

# first see whether you have already have the keys for the Gerrit and GerritBeta server
grep gerrit ~/.ssh/known_hosts

# if not already added, run the following commands

ssh-keyscan -t rsa -p 29418 gerrit.diamond.ac.uk >> ~/.ssh/known_hosts
ssh-keyscan -t rsa -p 29418 gerritbeta.diamond.ac.uk >> ~/.ssh/known_hosts

Check that the keys match the known good public keys for these servers, listed below. If they do not then stop as it could indicate a man in the middle attack

grep gerrit ~/.ssh/known_hosts
# Compare output with keys below:

Gerrit key

[gerrit.diamond.ac.uk]:29418 ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEAzov01/2GDqxdQmBu2zE+dsw47W+Eo
gPmI4Zw5pUdETyTwZ0mJuHWv3etpv4lMvhWld4FoR7I8MeZNgzA6DXz7GpW2WQIinD5El7G5UBFp/zlfUwnTuW+NqEkfwj
XwfeTh2bUhk0T/DlovnIX3decTMnnobWTlEhS4BwKsr/fJO8caqioiJXXHp547eouCG+WIyOt+ayRjN3c2ZRyTnx9PU3u0
iZzS0w245H6kujVnlohvrghah4aU/MjXut6e39yWKNloCjvcdWFX/I42lcsgfXx5bykxPjlN15amfKm4MQAoAF9DIZFv9E
ThWR40vDisM1JA3+Eo7+1RX4haHM/Iw==

GerritBeta key

[gerritbeta.diamond.ac.uk]:29418 ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDsPsusNhg9DNQVFO92BY
0qlsPG7KmlFlIctH0J60XiR6nXUSqyW34XyltUg0Ui/SOVyw/OGk+x3QtD/0a9A8Gv8RZr+IipwtNUX6LHfN1ISL/0PL7
CA3FyaKNuy1Bh3q37VWjz1nKbHBXfxF6436kC6VZH/NQ9ufJTLBnmkkQG7EVUBWHn4FVXm53Yv0yJNrpbTIKFwJ+A6xT/
WaO1XAMrX0ryLBk1JVlr0xjWzN1ETi9EexMYGBax6cWfRwrSMWbwqqDYufal0YNZ73//TYVeSehNiNWhIBQes3DK9
3ZhZBmFTVvji/p/NZd5wwKp6E/Obt8yjTDrJG73mkcMM/Jh

Check that you can connect from the command line as your Gerrit username:

ssh -p 29418 gerrit.diamond.ac.uk
ssh -p 29418 <username>@gerrit.diamond.ac.uk  # use this method if you haven't set your username in the SSH config file

If you see a warning that looks like The authenticity of host ‘[gerritbeta.diamond.ac.uk]:29418 (IP ADDRESS)’ can’t be established, then don’t type “yes” to continue - this is a possible ‘man-in-the-middle attack’. Check that the contents of ~/.ssh/known_hosts were set correctly.

Request access to repositories

Notify a Gerrit administrator of your details, so that you can be given access to the appropriate repositories.

If you don’t do this, you won’t be able to check out the GDA or DAWN code base.

If you are new to GDA and DAWN development, ask to be added to the GDA-Collaborators and DAWN-Collaborators Gerrit groups

If you are a member of the Data Acquisition group, ask to be added to the GDA-Committers and DAWN-Collaborators Gerrit groups

If you are a member of the Scientific Software group, ask to be added to the DAWN-Committers and GDA-Collaborators Gerrit groups

Otherwise, ask to be added to the Gerrit groups GDA-Collaborators and DAWN-Collaborators

4.2. Standard Tasks¶

Pre-requisites for all changes

Concepts

Understand what a Gerrit Change is (it has a Change Number and and a Change-ID)

Understand what a Patch Set is

A Change consists of one or more Patch Sets

JIRA

(If applicable) Ensure there is an issue in DLS Jira for your change

The issue number should the first part of all commit message(s)

4.2.1. Connect a Repo¶

Workspaces provisioned in the standard way will already be configured as Gerrit repositories but this can be manually configured too: in the IDE go to “Git Repositories”:

Right click on origin and select “Gerrit Configuration”

Hit finish without changing anything

4.2.2. Uploading a new change for review¶

(Recommended) Fetch/Merge (Pull) to bring your workspace up-to-date
! Use a separate local branch for every change. Seriously. Make a new local branch off master (or some other branch)
- In the Git Repositories view, right-click on the repository and Switch to / New Branch …
- The Source: is master (or other branch as applicable), and the Branch name: can be anything (suggestion: use the Jira issue number to construct local-GDA-0000)
- De-select “Configure upstream for push and pull”
Make your changes (you are on your new local branch)
Of course, you’ll check that your changes actually compile, and that tests pass
In the Git Staging View, stage your changed file(s), making sure that you include all the required files (which will probably be all the changed files, since you are on a local branch specific to that change)
Enter a suitable commit message. At the bottom of the message, you should have “Change-Id: I0000000000000000000000000000000000000000”
Commit the change - this will be local only
(Recommended) Before pushing, synchronize your change with any changes that may have occurred in master while you’ve been working. Fetch new commits from the remote and then rebase your local commits on top of them. This temporarily sets aside changes you’ve made in your branch, applies all of the changes that have happened in master to your working branch, then merges (recommits) all of the changes you’ve made back into the branch. Doing this will help avoid future merge conflicts. Plus, it gives you an opportunity to test your changes against the latest code in master.
- Make sure you are on your local branch
- Right-click on the repository and Fetch from Upstream
- Right-click on the repository and Rebase ... against origin/master (or other branch as applicable)
In the Git Repositories view, right-click on the repository and Push to Gerrit... The Gerrit Branch: should be refs/for/master (or other branch as applicable).This submits the change to Gerrit, and the change will be assigned both a Change number and a Change-Id
(Recommended) Go to the Gerrit web interface page for the change you just added
- Select reviewer(s) to Add... (Gerrit will email the reviewers)
(Recommended) In the Git Repositories view, right-click on the repository and switch back to master (or other branch as applicable).

Submit your change and pull changes back into your working directory

Wait till your change has been reviewed. If the reviewer asks for changes, follow the procedure in “Amending a previously uploaded change” below. .. in the meantime, if you want to work on a separate change, use a different (new) local branch.
Eventually your change will be positively reviewed. It needs a Code-Review of +2, and a Verified of +1.
Go to the Gerrit web interface page for your change. Click Submit (if this is not visible, then the change has not yet been approved), or Abandon if you no longer want the change. After Submit, your change will be merged into master (or other branch as applicable) branch - check on the Gerrit web page that this was successful.
In your Eclipse workspace, make sure you are on master (or other branch as applicable), and Pull.
Delete your local-GDA-0000 branch as it’s no longer needed.

Push to gerrit from command line

From local feature branch:

git push origin HEAD:refs/for/[remote branch name, not local branch name]

4.2.3. Reviewing a change¶

Note: if reviewing a change that is a merge commit, the Gerrit web interface is fairly useless in showing you the details. In that case, you’ll need to pull that change down into an Eclipse workspace.

Browsing a change using the Gerrit web interface

For small changes, you can view the change directly in the Gerrit web interface. Remember to review the commit message as well as the code.

Browsing a change using Eclipse

For large changes, you can pull a copy of the change into an Eclipse workspace.

(Recommended) Use a separate workspace for reviewing code, to avoid getting mixed up with your own work, and have all beamlines checked out
(Recommended) First Fetch/Merge (Pull) to bring your workspace up-to-date
Switch to master (or other branch as applicable) on which the change is based
Pull the change to review into your workspace (this can automatically create a new local branch in your workspace)

In the Git Repositories view, right-click on the repository and Fetch from Gerrit ...

In the Change: box, hit Ctrl+Space to get a list of what changes and patch sets are available. Select the one to review.

When your review is complete, you can switch back to master (or other branch as applicable), and delete the local branch into which the change was pull

How to Review

Follow Best Practices - Reviewing Changes
Review comments are entered using the Gerrit web interface
Enter your review comments in the appropriate place - they can be

entered against a specific line in a file (in the diff viewer, click on the line number on the left side of the file text)

entered against a specific file (in the diff viewer, click on the yellow icon at the top of the file)

entered for the change as a whole (under Reply... on the main change page)

Voting, and sending your review comments back

When you are ready to finish your review and send your comment back to the developer:

Click Reply... on the main change page
Enter any additional comments in the text box

Enter your Code-Review vote as follows:


+2	fully understood, all correct, looks good
+1	looks good, don’t see anything wrong
0	optional comment, just a question
-1	feature is good, but there are issues that should be fixed
-2	veto, must not be merged

The Verified vote is use by a CI (continuous integration) system such as Jenkins. For GDA Jenkins will post back +1 or -1 depending on the result of the build and unit tests.
Click Post to finish the review and submit your comments.
If the Change has enough votes, then a Submit button will be displayed, which merges the change into the main repository. Do NOT Submit! The Submit should be done by the developer who is responsible for the Change, and not by the final reviewer.

4.2.4. Amending a previously uploaded (but not submitted) change¶

! This is the procedure for amending a change that has not yet been Submitted and merged (for example, a reviewer has asked you to make some changes). If you want to make amendments to a change that has previously been approved and merged by Gerrit, then that is a new change (so use the procedure above)!

Switch back to the local branch you created for this change.
Make your changes (you are on your local branch)
Of course, you’ll check that your changes actually compile, and that tests pass
In the Git Staging View, stage your changed file(s)
Click Amend Previous Commit to populate the commit message, with, crucially, the same Change-Id as previously
Commit the change locally
In the Git Repositories view, right-click on the repository and Push to Gerrit.... The Gerrit Branch: should be refs/for/master (or other branch as applicable) This submits the amendment to Gerrit, and links it with existing Change number and Change-Id
Go to the Gerrit web interface page for the change you just added
- Reply to every comment that you have addressed (the word Done may be sufficient).
(Recommended) In the Git Repositories view, right-click on the repository and switch back to the master branch

4.2.5. Reverting a previously uploaded and submitted change¶

! This is the procedure for completely reverting a change that has previously been approved and merged by Gerrit. If you want to undo just part of the change, then you will need to do that as a new change (so use the procedure above)!

You don’t need to do anything in your Eclipse workspace.
Go to the Gerrit web interface page for “Merged” changes.
Select (click on) the entry for the change that you wish to revert (it does not have to be your change).
Click Revert. This does not immediately revert the change, but instead it creates a new Gerrit Change which effectively reverts the earlier change.
Go to the Gerrit web interface page for “Open” changes. You will see a new entry for the Revert which you just did. This needs to be reviewed like any other change!
(Recommended) Go to the Gerrit web interface page for the change you just added
- Click Edit Message and add another line to the commit message (above the Change-Id:) with a comment about why the change is being reverted
- Select reviewer(s) to Add... (Gerrit will email the reviewers)

4.2.6. Merging from a release branch into master¶

The basic idea is to merge the release branch into the master branch, and push this merge commit to Gerrit (from stackoverflow git - What’s the best practice of merging commits in maintenance branch to master in Gerrit).

With merge commits, git can do a better job of showing you how the branches relate. It has more meta data so future merges are easier.
The one downside to merge commits is that they aren’t displayed that well in Gerrit currently, and generally developers have to look through the merge commit locally using git tools to truly understand what is going on.

Doing the merge from the Eclipse IDE

(Recommended) Do the merge in a new, clean workspace. Fetch/Merge (Pull) to bring your workspace up-to-date.
! Use a separate local branch for the merge. Seriously!

Make a new local branch off master (or some other branch - the branch you are merging into)

In the Git Repositories view, right-click on the repository and Switch to / New Branch ...

The Source: is master (or other branch as applicable), and the Branch name: can be anything (suggestion: local-merge-from-x.xx)

De-select “Configure upstream for push and pull”

In the Git Repositories view, right-click on the repository and Merge ...

Merge from Remote Tracking

For Merge options, select No commit (prepare merge commit, but don't commit yet)

Fix up any conflicts as you normally would

Of course, you’ll check that the merge actually compiles, and that tests pass (wink)
In the Git Staging View, edit the commit message if required. At the bottom of the message, you should have “Change-Id: I0000000000000000000000000000000000000000”
Commit the change - this will be local only
In the Git Repositories view, right-click on the repository and Push to Gerrit.... The Gerrit Branch: should be refs/for/master (or other branch as applicable). This submits the change to Gerrit, and the change will be assigned both a Change number and a Change-Id
(Recommended) Go to the Gerrit web interface page for the change you just added

Select reviewer(s) to Add... (Gerrit will email the reviewers)

Note: Gerrit it clever here and helps you understand the merge:

If the merge went through with no conflicts no files will be shown in Gerrit, only a commit message.

If there were conflicts Gerrit lists the files containing conflicts. In the base version it will show where the conflict occurred and which commits conflicted. In the patch set it will show how you resolved the conflict.

(Recommended) In the Git Repositories view, right-click on the repository and switch back to master (or other branch as applicable)
Eventually your change will be positively reviewed. It needs a Code-Review of +2, and a Verified of +1.
Go to the Gerrit web interface page for your change.
Click Submit (if this is not visible, then the change has not yet been approved), or Abandon if you no longer want the change. After Submit, your change will be merged into master (or other branch as applicable) branch - check on the Gerrit web page that this was successful.
In your Eclipse workspace, make sure you are on master (or other branch as applicable), and Pull. Delete your local-merge-from-x.xx branch as it’s no longer needed.

4.2.7. Migrating a commit that was made to the wrong place¶

Background: A commit was made to the old copy of a repository, after it had been moved to Gerrit (this won’t happen again, since we now block updates to the pre-move copy of repositories).

This is the procedure that was followed to migrate the commit to Gerrit. The basic idea is to export the changes from the old repository as a patch, and then apply them to the new repository for submission to Gerrit.

Export the change from the old repository as a patch file

TMPDIR=/tmp/oldrepo
rm -rf ${TMPDIR}/
mkdir -pv ${TMPDIR}/
 
repo_name=gda-dls-beamlines-xas
old_repo_origin=ssh://dascgitolite@dasc-git.diamond.ac.uk/gda/${repo_name}.git
old_repo_location=${TMPDIR}/${repo_name}.git
git clone ${old_repo_origin} ${old_repo_location}
cd ${old_repo_location}
 
commit_to_move_branch=gda-8.40
commit_to_move_sha1=f5c6782054911036f9edd93f37affa4680a35d47
git checkout ${commit_to_move_branch}
git format-patch -1 ${commit_to_move_sha1}

From the Eclipse IDE, set up a new local branch in the new repository, ready to have the patch applied. This is described in the first part of the instructions “Committing a new change” above.

Apply the patch file to the new repository

## MAKE SURE THE NEW REPOSITORY IS ON A SUITABLE LOCAL BRANCH
new_repo_location=/scratch/SSD/ws/gda840_git/gda-dls-beamlines-xas.git
cd ${new_repo_location}
ls -la ${old_repo_location}/*.patch
git apply ${old_repo_location}/*.patch

From the Eclipse IDE, Refresh the Git Repositories view, and then all projects. Switch to the Git Staging view; stage/commit/push to Gerrit using the standard procedure. This is described in the second part of the instructions “Committing a new change” above.

Note: the above procedure was repeated with

repo_name=gda-xas-core
 
commit_to_move_branch=gda-8.40
commit_to_move_sha1_first=a5347c04
commit_to_move_sha1_last=dc3a8ea2
git checkout ${commit_to_move_branch}
git format-patch ${commit_to_move_sha1_first}^..${commit_to_move_sha1_last}
 
new_repo_location=/scratch/SSD/ws/gda840_git/gda-xas-core.git

Then each patch file was processed in order, with a separate stage/commit/push to Gerrit.

4.2.8. Gerrit + Github¶

If you are committing changes to dawnsci.git or daq-eclipse.git or Malcolm (on GitHub), it’s polite to check first that your changes don’t break anything in GDA.

You can , if you want, request Jenkins to test your change before your pull request is accepted into master. This is a good idea if you haven’t tested you change locally in a clean workspace.

You need to push your changes to a named branch.

If your change is to dawnsci.git, your new branch is probably on the fork at DawnScience/dawnsci (if you are an Eclipse committer, it might be at eclipse/dawnsci).

If your change is to daq-eclipse.git, your new branch is probably at DiamondLightSource/daq-eclipse.

To run the test job against your change(s), all you need to do is go to the Jenkins Gerrit test job at GDA.master-junit.tests-gerrit and hit “Build with parameters”.

This job will fetch your change(s), compile GDA, and run the unit tests. Despite the name, it works for both Gerrit and non-Gerrit repositories.

If you want to test a branch that is on DawnScience/dawnsci (rather than eclipse/dawnsci), select (check) the “materialize_dawnsci_from_DawnScience” box.

Scroll down to List of changes to test (non-Gerrit), and set

repo_1_name = daq-eclipse (or dawnsci)
repo_1_head = < your branch name>
repo_1_action (leave blank)

If you have changes from more than one repository, click “Show/Hide more” and add the details

Then scroll down to the bottom and hit the “Build” button.

Remember to check the result!

4.3. Using Work in Progress (WIP)¶

Gerrit provides the ability to store changes as WIP (think email drafts). This might be a useful place to put changes from the beamline as a reminder, and you can then improve them later before submitting into the main Gerrit review system.

WIP changes can be turned into regular changes, by using the “Start Review” action.

You can convert any change to WIP using the More -> WIP option.

You can also set Gerrit to mark new changes as WIP automatically when you push them by using Settings > Preferences > Set new changes to "work in progress" by default

Pushing WIP changes from Eclipse

Commit your change as usual (in a Gerrit repository)
When you go to push it to Gerrit select refs/for and chose the branch the change is heading for. Then add %wip to the end of the branch name e.g.

You can then go to the Gerrit web interface and see your WIP change.
You can fetch the change down into any other workspace using the standard Gerrit fetch system.

Pushing to WIP from command line

git push origin HEAD:refs/for/master%wip

Sub branch as appropriate e.g. refs/for/gda-9.8

Running Builds and Tests against WIP

Unlike normal changes, uploading a WIP change (or a new patchset for an existing WIP change) does not trigger the automatic Jenkins verification job.
You can manually trigger a Jenkins verification job for a Gerrit draft using the Jenkins Gerrit Job GDA.master-junit.tests-gerrit or DawnDiamond.master-junit.tests-gerrit (or the equivalent for other branches) and hit “Build with parameters”:

Just enter the single Gerrit change ID as change_1 and then click Build

After the job has finished a verified status will be posted onto the change in Gerrit to inform you whether the build and tests passed or failed. (This behaviour can be changed by setting gerrit_verified_option on the job parameters page)

Posting comments/adding reviewers to a WIP change

If you would like to keep your change as work in progress (WIP) but want to add comments or add reviewers in preparation for review you can do so using the following procedure:

Make comments as usual and save them (they will be drafts, visible only to you at this point)
Click the blue ‘START REVIEW’ button at the top of the change (just above the commit message) - don’t worry this won’t remove WIP straight away
The following dialogue will appear:

There is also the option to add reviewers/leave a note (even set code-review score)
Then the important part here is to click the ‘SAVE’ button at the bottom left which will maintain the WIP status but publish the draft comment(s)

4.4. Using Topics for multi-repository changes¶

*If you want to link a set of otherwise unrelated changes across multiple repositories, you do it by giving all the changes the same Topic. Every Gerrit change has a Topic (distinct from the change number and Change-Id), which is an arbitrary string field (by default the Topic is not set).

Do not use topics to link a series of changes within the same repository (e.g. where the changes are to be applied one after the other). This case is handled using standard Gerrit changes, with each change having a different Change-Id, and each change commit having the previous one as a parent.
If you upload a change with a Topic, then the Jenkins Verification job is not automatically triggered.
When you have uploaded all the related changes across the various repositories (and given all the changes the same Topic), then you can manually trigger a Jenkins verification job for all the changes, taken together.
To trigger the Jenkins verification job, go to the Jenkins Gerrit Manual Job GDA.master-junit.tests-gerrit and hit “Build with parameters”:

Enter the Gerrit Topic as topic_1 and then click Build.

All the related changes will be checked out and Verified (or not!) in a single Jenkins Verification job.

After the job has finished a verified status will be posted onto all the changes, to inform you whether the build and tests passed or failed. (This behavior can be changed by setting gerrit_verified_option on the job parameters page)

The best way to set the Topic for a change is when you upload it (otherwise, the normal Jenkins Verification job is automatically triggered, which you probably don’t want). Here’s how you do it from within Eclipse (the same method can be used from the command line):

After a change has been uploaded, you can also use the Gerrit web interface to edit (add/change/delete) the Topic:

You only need to specify the Topic for a change the first time you push it to Gerrit. Pushing another patch-set won’t remove or change the Topic, unless done explicitly.
Remember that all changes with the same value for Topic are linked, so be careful to ensure that

all changes with the same Topic are for the same GDA release

a good choice for Topic is the Jira ticket as a prefix, followed by some suitable string

(if you have a another set of changes for the same ticket that need to be linked, use a different Topic)

! to reiterate, choose a value for Topic that selects exactly the changes you want linked, no more and no less, and chose a value that is unlikely to be reused later on by someone else

avoid embedded blanks in the Topic string

When all of a topic’s changes have been approved (by a reviewer) and verified (by Jenkins), you will be able to submit them.

A good way to see an overview of a topic’s changes (indicating whether they have been merged or not) is to view one of the changes in the Gerrit web interface, and click the topic name, which will search for all changes related to that topic.

You can also search for a topic using the search syntax “topic:TOPICNAME”, or go straight to the search page for a particular topic: http://gerrit.diamond.ac.uk/#/q/topic:TOPICNAME.

Gerrit 2.12 includes experimental support for submitting all changes related to a topic simultaneously (known as “Submit Whole Topic”). See New Change Submission Workflows in the Gerrit 2.12 release notes.

Pushing multiple repos from the command line

When you make a significant refactor across multiple repos you will often want to push all those changes with a single topic this can be acheived using frog.py. Before doing this ensure only the changes you want are in the workspace

frog.py git push origin HEAD:refs/for/master -o topic="some-topic-name-here"

or to do it as WIP

frog.py git push origin HEAD:refs/for/master -o topic="some-topic-name-here" -o wip

4.5. FAQs about the Diamond Gerrit Configuration¶

These FAQs describe the current DLS Gerrit configuration. Many of these are local configuration options, and could be changed.

If you think the current policy is wrong (either globally, or just for your repository), please open a Jira ticket with the label GBA_TBD, so the policy can be discussed.

Q1: Can I push an urgent change directly to the repository, bypassing Gerrit?

A1: No.

Previously, you could push changes directly to branches matching the pattern ^refs/heads/gda-(8\.40|8\.41|8\.42), bypassing review. This was optional; you could also push changes for those branches to the review queue.

The current rule is that for changes to any branch (including master), you must push to the review queue. Gerrit is configured to enforce this. You can, of course, make and locally commit anything you want, you just can’t push it directly to the central repository.

Q2: Can I review and submit my own changes?

A2: Yes. No.

Previously, we said that changes should normally be reviewed by someone else, but Gerrit would not stop you approving and submitting your own changes (to be used sparingly).

The current rule is that you can review your own changes, but the “submit” action cannot be done until the change has been reviewed by someone other than the commit author. Gerrit is configured to enforce this.

Q3: Can I use Internet Explorer 9 with Gerrit? It displays “Loading Gerrit Code Review ...” and hangs.

A3: DLS Windows laptops have IE 9 installed. Installing a modern browser (e.g. IE 11+, Chrome, FireFox) is the best solution.

Alternatively, turn off compatibility mode for the Gerrit website. Press F12, and on the developer toolbar set “Browser Mode: IE9” and “Document Mode: IE9 Standards”.

Note: This workaround does not appear to be sticky; i.e. if you start a new browsing session, you will need to turn off compatibility mode for the Gerrit website again.