Gerrit/Advanced usage

This page describes the workflow for how MediaWiki core and extensions developers will use Git, git-review, and Gerrit after the migration on 3 March 2012.



The diagram on the right is an accurate description of what our Git workflow looks like. (Transcription is welcome!) To understand our Gerrit workflow, see these pages:


 * https://labsconsole.wikimedia.org/wiki/Help:Git#Review
 * http://wiki.openstack.org/GerritWorkflow
 * http://source.android.com/source/life-of-a-patch.html
 * http://blogs.gnome.org/markmc/2011/09/25/gerrit-patch-review-from-the-command-line/

Also useful (if you subtract away GitHub stuff):
 * http://wiki.openstack.org/GerritJenkinsGithub

This might change. If you'd like to help, we're seeking test subjects! Also, John Du Hart would like for us to consider using Phabricator instead; we will consider this in June 2012.

Easier submission of code
In the old workflow, developers had to send their patch through Bugzilla or email it, then have someone with proper access rights commit it. Extensions developers were prevented from committing to MediaWiki core.

With Git, everyone commits in their local repository. Then everyone is allowed to submit their code for review to Gerrit. There is no more distinction between core and extensions access rights. Since code does not automatically make it into the WMF repository, there's no danger of bad commits unless someone merges irresponsibly. Thus, for many of the Git repositories hosted by the WMF, only a small group of people needs the access rights to merge (apply) the code. See "Who can review?".

This workflow has proven successful for the WMF operation team. That model is also known as "gated trunk" - code needs review before merge - and will be the default model for WMF hosted git repository. Extensions can optionally choose to adopt a straight push model in which code is reviewed post-commit. This is much more like the Subversion model in use before 2012.

If you are wondering who is going to review your code, jump straight to "Who can review?"

Better branching
Git supports branching and merging far better, so we are encouraging people to use branches a lot. The big features of the MediaWiki dev landscape: release branches (19 so far) on core, master (the default branch on trunk). Example: https://gerrit.wikimedia.org/r/gitweb?p=mediawiki/extensions/CodeReview.git;a=summary. ("Heads" is gitweb's term for branches.) MediaWiki core & WMF-deployed extensions will be tagging releases just as we did in SVN, only they'll be git tags. Any other extension will make its own decisions.

With git-review, you can group branches as a "topic" to help with keeping feature development straight. We aim to encourage people -- if you are fixing bug n, make a "bug n" branch! Look in Gerrit at the top of changesets to see examples. git-review should detected the "bug XXX" in your commit summary and automatically creates a topic branch for you.


 * Tags vs branches: branches are for forking, to maintain a separate feature branch. This is like traditional branching.  Tags are more lightweight, designed to point to an individual commit.  You can delete a tag, but they are not mutable.  Designed for tagging releases.  "As of this commit, this was exactly release 1.2.3" -- useful if you aim to tell people to check out specific versions.

Gerrit and Git deal with merge conflicts pretty well. In cases of merge conflicts, the code reviewer gets a notice from gerrit that the merge couldn't go through, and the final merge step fails, but all the code review work will be untouched. To fix the issue, you will have to manually rebase your branch on top of the master branch and resubmit your change.

Install & configure Git
Install Git on your computer.
 * Linux: see http://evgeny-goldin.com/wiki/Git#Linux
 * Windows: users can download msysgit (http://code.google.com/p/msysgit/) which includes a version of git and some nifty "Git Bash" tools that act like a basic UNIX shell.
 * Select the "OpenSSH" option in the installer to use ssh-agent.exe. It can instead be configured to work with plink/pageant as may be convenient (provided it doesn't cause any problems).
 * It may also be useful to install TortoiseGit as a complimentary, shell-integrated, GUI but code can only be pushed with the "git review" command via the command line or Git Bash.

Then do git config -l to check that you have a name and email address configured; if you don't, tell Git your username and e-mail address so gerrit can attach it to your accounts:

git config --global user.email "foo@example.com" git config --global user.name "mrfoo"

Get the right permissions
To clone our code repository properly, so as to easily submit a patch back to us, you need a login. We manage this via a unified LDAP login shared between Gerrit and Labsconsole.

Log in to https://labsconsole.wikimedia.org/, verify that you can log in, then log in at https://gerrit.wikimedia.org/ with the same username and password. Click Settings, go to SSH Public Keys, and paste in your public key (usually  on Linux) so our git repository will recognize you. (We aim to fix this soon by simply pulling the key from LDAP.)

If you have a few different email addresses or SSH keys, go into Gerrit's settings and add them to your account.


 * Teacher: give the user a login using these instructions.

Clone the repository
Now, to clone the code repository in question that you want to make a change on. For a list of all projects in Gerrit, please see the project list.

Create or move to the directory on your machine that you do your development in. If you're making one,  is a good name.

mkdir wikimedia-git-repos cd wikimedia-git-repos

Now, clone the respository.


 * If you're doing the examples tutorial with Sumana, use this:

git clone ssh://USERNAME@gerrit.wikimedia.org:29418/test/mediawiki/extensions/examples.git OPTIONAL-DESCRIPTIVE-NAME

Otherwise you type something like this (replacing  with   for an extension or any other part of the repository): git clone ssh://@gerrit.wikimedia.org:29418/mediawiki/core.git

Go have a sip of coffee while you wait for a minute :)

Once cloned, get commit notes which will nicely indicate the old SVN version numbers.

cd core && git fetch origin refs/notes/commits:refs/notes/commits

Prepare to work with gerrit
In order to properly work with gerrit, you need to have a pre-commit hook that adds a "change id" to your commit summary. That unique ID will let Gerrit track your commit. Since Git commit identification is based upon a sha1 of the commit id, whenever you amend a commit, the sha1 will change and gerrit would lost track of it!

Linux
Install git-review, a tool to simplify working with Gerrit repositories so you don't have to remember some pretty confusing commands. sudo apt-get install python-pip || sudo easy_install pip sudo pip install git-review If you do not have easy_install set up, try sudo apt-get install python-setuptools Then run: git review -s in your cloned copy to setup to work with Gerrit. It will probably ask you for your commit username. Then it will automatically install the pre-commit hook.

Gentoo users can ignore all that apt-get stuff and type: emerge dev-python/pip pip install git-review

Windows
@python c:\Python2x\Scripts\git-review %*
 * Install pip using these instructions :
 * Download and uncompress the latest pip version from here: http://pypi.python.org/pypi/pip#downloads
 * Download and install the latest easy installer for Windows: (download the .exe at the bottom of http://pypi.python.org/pypi/setuptools )
 * Go to the uncompressed pip directory and run python setup.py install.
 * Add your c:\Python2x\Scripts to the system path
 * Run pip install git-review
 * Create gitreview.bat in some PATH-accessible directory containing the following line (replacing "X" with the actual python version):
 * Make sure you can connect to gerrit properly via SSH.
 * Start Git Bash.
 * Get ssh-agent running if not done already via eval `ssh-agent`.
 * Add your key to the agent if not done so already via ssh-add path/to/key. Make sure the key is in OpenSSH format (.ppk keys can be exported to this format in PuTTyGen).
 * Run ssh @gerrit.wikimedia.org -p 29418. It should give a Gerrit welcome message and then abort.
 * In Git Bash, go to the directory of the fresh MediaWiki clone and run git-review. This should install a git hook called "commit-msg" under .git/hooks. Check that the file is there. From now on, commits will have a change-id appended to the summary, which Gerrit will need in order to accept any commits for review.
 * If the commit-msg file fails to download to .git/hooks, then run scp -P 29418 -v @gerrit.wikimedia.org:hooks/commit-msg .</tt> in that directory.

Mac OS X via Terminal
Mac OS X comes with Python (for now) but not the installation programs supported by git and git-review.


 * 1) Open Terminal and change to a directory you're comfortable downloading test Git packages to (such as Downloads or Sites)
 * 2) Download and install the OSX Installer for Git
 * 3) Install pip (Note: Already included in some older versions of Mac OS X):
 * 4) *sudo easy_install pip</tt>
 * 5) Install git-review:
 * 6) *sudo pip install git-review</tt>

Manual setup
If installing git-review is not feasible for you, you will use an alternate way to communicate with Gerrit.

First, you need to download a pre-commit hook script and place it in the right directory in your cloned copy of the repository. The script is available from https://gerrit.wikimedia.org/r/tools/hooks/commit-msg and must be placed in the repository sub directory .git/hooks/</tt>

1) With a browser:

Download the script from the repo using "Save As ..." then browse to wikimedia-git-repos/examples/.git/hooks/</tt>. Voilà!

2) With wget:

Change to the repository directory (for example,  wget  -P .git/hooks https://gerrit.wikimedia.org/r/tools/hooks/commit-msg

3) With curl: curl https://gerrit.wikimedia.org/r/tools/hooks/commit-msg > .git/hooks/commit-msg

You also need to ensure the hook is executable. In Linux you do this with: chmod u+x .git/hooks/commit-msg

When ever you commit a change locally, the hook script will generate a unique Change-Id for you.

Next, add an alias to simplify the command to push changes to Gerrit for review. You can do this by executing the following from your repository clone (for example, within ):

git config alias.push-for-review "push origin HEAD:refs/for/master"

(The refs/for/</tt> is Gerrit magic and must not be omitted. However, you may adapt master</tt> to point to the remote branch that you want to commit to. E.g.: When trying to push to the remote branch Foo</tt> use refs/for/Foo</tt>.)

Commit a change
First, create a branch for your new change. Give the branch a short but reasonably descriptive name. git checkout -b BRANCHNAME master

Change the code in the examples directory in some way; have fun! Commit them to your branch by doing: git commit -a -m "COMMIT MESSAGE HERE"

(don't forget to git add</tt> any new files).

Tip: Using git commit -a -m "Commit message here"</tt> is nice because you can write the commit message right there in the command. But you can also do git commit -a</tt> for longer commit messages, and then it'll open a text editor for you to write the commit summary in.

''Please mention the bug numbers of Bugzilla bugs that the commit addresses. There's no autolinking from Gerrit to Bugzilla yet, but we'll work on it! For now, when referring to a Git diff, please paste changeset "Change ID"s, or the changeset number in the Gerrit changeset URL, into the BZ comment. Both are globally unique.''

Then check the changes you've made, within the file(s) and within the directory: git diff git status

Push your change to Gerrit
If you installed, the command to push changes to Gerrit is very simple: git review

If you had to install the hook manually, you can push your changes by doing: git push-for-review

Upon success, you'll get a confirmation and a link to the changeset in Gerrit.

If your commit addresses a bug in Bugzilla, please comment on that bug to note that the commit is in the merge queue, and link to its changeset in Gerrit.

Note: Some extensions do not require review, in which case you can just git push origin master</tt> to push your changes past Gerrit straight into the repository.

SSH
If you get the error Permission denied (publickey). fatal: The remote end hung up unexpectedly Then you're not logged in to your ssh key right now. Solution: do  to make it prompt you for the passphrase for your key and add it to the active keychain. Then you can check what's in your keychain with. Then try pushing for review again.

The fingerprint of the Gerrit server is

dc:e9:68:7b:99:1b:27:d0:f9:fd:ce:6a:2e:bf:92:e1

so you can say yes when it asks you to add that fingerprint to the known hosts file.

Keep in mind that gerrit listens on port 29418 and if for some reason you forgot to specify port number, you might be hitting "normal" SSH daemon listening on port 22 (this one has RSA key fingerprint b5:e9:dc:b2:dd:6e:70:f7:18:8a:dc:a3:5d:ab:99:4d).

To check whether SSH connectivity and public key authentication work you can use: $ ssh -p 29418 username@gerrit.wikimedia.org

****   Welcome to Gerrit Code Review    ****

Hi username, you have successfully connected over SSH.

Unfortunately, interactive shells are disabled. To clone a hosted Git repository, use:

git clone ssh://username@gerrit.wikimedia.org:29418/REPOSITORY_NAME.git

Connection to gerrit.wikimedia.org closed.

"[remote rejected] master -> master" and "failed to push some refs"
If you forget to add HEAD:refs/for/master</tt> as an alias, you will receive something along the lines of:

$ git push Counting objects: 5, done. Delta compression using up to 8 threads. Compressing objects: 100% (3/3), done. Writing objects: 100% (3/3), 709 bytes, done. Total 3 (delta 1), reused 0 (delta 0) remote: Resolving deltas:  0% (0/1) To ssh://username@gerrit.wikimedia.org:29418/test/mediawiki/extensions/examples ! [remote rejected] master -> master (prohibited by Gerrit) error: failed to push some refs to 'ssh://username@gerrit.wikimedia.org:29418/test/mediawiki/extensions/examples'

This means you tried to commit to branch "master" instead of submitting your changes for review.

Email doesn't match
TODO: help people understand how to granularly config their email and name settings in Git and/or Gerrit per-repo to make gerrit accept their changes remote: ERROR: committer email address (email) remote: ERROR: does not match your user account. Fix: add your secondary email address in Gerrit, and make sure you click the confirmation link in the email Gerrit sends you. Then try pushing again.

Working tree is dirty
Note: if upon doing 'git review' you receive a message "Working tree is dirty" try doing 'git add' for the file(s) changed (or created), then 'git commit', and then 'git review'. This was seen on OSX with an older git client.

missing Change-Id
Note: if upon doing 'git review' you receive a message about 'missing Change-Id', then your /.git/hooks/commit-msg is probably incorrect. it should look something like:

CHANGE_ID_AFTER="Bug|Issue" MSG="$1"

add_ChangeId { clean_message=`sed -e ' /^diff --git a\/.*/{ s/// q               } /^Signed-off-by:/d /^#/d ' "$MSG" | git stripspace` if test -z "$clean_message" then return fi
 * 1) Check for, and add if missing, a unique Change-Id

Don't push
If you attempt to do 'git push' after doing 'git commit' you may receive a response 'Everything up-to-date'. You have not pushed to the branch. You have to do 'git review' to move your changes to gerrit, and only from gerrit will the branch be updated. This seems to be a side effect of checking out master as a branch as of February 2012.

In some projects (e.g. test/) it is possible to do 'git push' instead of 'git review' and have the push succeed. It is probably better not to do that, as it confuses those who find your changes later and don't know where they came from.

How we review code
The things we look for in code won't change, but the workflow is different than it was before the Git switch.

Review before merge
It's important to us to have a review-before-merge workflow, for MediaWiki core and also for any extension we deploy. We will also offer that option to any extensions author who wants it for their extension. (The default is to use the current model we've been using with Subversion -- pushed and automatically merged.) For this decision we will defer to whoever is considered the primary author on the extension.

The one exception is i18n commits, which will be able to be pushed without review.

Who can review? Gerrit project owners
Who has the ability to do code review?

We use gerrit to manage code review. Anyone can ask for a Gerrit account. Within Gerrit, anyone can comment on commits and signal their criticisms and approvals. Anyone can give a nonbinding "+1" to any commit (this is like "inspection" and "signoff" in the old Subversion code review interface). However, for any given repository ("Gerrit project"), only a small group of people will have the ability to approve code within Gerrit and merge it into the repository. (Within gerrit, this superapproval is a "+2" even though that's a misleading name, because two +1 approvals DO NOT add up to a +2.) These people are "Gerrit project owners".

Even within a Gerrit project, we can also specify particular branches that only specific people can pull into.

To make a new Project Owner:
 * Create a group
 * Give it ownership of a Project
 * Anyone in that group can now add more owners via https://gerrit.wikimedia.org/r/#admin,projects
 * Click Groups
 * As long as you are a member of the group, you can edit the group
 * example: https://gerrit.wikimedia.org/r/#admin,project,mediawiki,access

MediaWiki core
We are maintaining a "WMF" branch of mediawiki/core.git. We use submodules for deployed extensions, and can pull from master as regularly as we want for deployments. At the start of the migration to git, the project owners of this branch are going to be the people who have the ability to deploy code to Wikimedia Foundation servers. See this list in Gerrit and look for the lists of people under the headings "admins::mortals" or "admins::roots". Once we have the groups properly set up, gerrit will offer a list of the "Gerrit project owners" for this branch. Every member of the Wikimedia Foundation operations (systems administration) team will also be in the Gerrit project owners group insofar as they have code review rights globally, but in practice will rarely review code. We may add some existing code reviewers to this Gerrit project owners group; we will figure out that final group by 7 March 2012.

At the start of the migration, we anticipate that this list of Gerrit project owners for the WMF branch will also be the list of Gerrit project owners for the master branch. However, eventually, we will add to the list of Gerrit project owners for master, using as criteria the number and quality of developers' previous commits and code reviews.

No procedure has yet been defined for adding and removing people from the Gerrit project owners groups. There will be a procedure by 7 March 2012.

MediaWiki extensions that the Wikimedia Foundation deploys
Same procedure as for MediaWiki core, and the same Gerrit project owner groups.

Other MediaWiki extensions
Every extension author can choose between two choices here: the gated-trunk/push-for-review model, and a straight push model. For any given extension, we will honor the wishes of the person/s listed as the main author on the extension's mediawiki.org page.


 * The gated-trunk/push-for-review is the model that we are using for MediaWiki core, as mentioned above. A gerrit project owners group (plus the above mentioned gerrit project owners group for MediaWiki core) will be able to "+2" (approve and merge) changes to their extensions.  The extension author(s) will be able to define a Gerrit project owners group and add others to it.


 * The straight push model is similar to how we did things in Subversion; anyone can suggest a change and submit a pull request, and it will automatically be approved and merged.

We could define groups to make this easier for batches of extensions (e.g. SMW developers). Chad will offer your community a choice. Please let Chad what you would like.

Other Gerrit projects
Same procedure as for "other MediaWiki extensions" above.

How to comment on, review, and merge code in Gerrit
Anyone can comment on code in Gerrit.

Viewing and commenting on code

 * Make sure you have a https://gerrit.wikimedia.org login. If you don't know, try logging in at https://labsconsole.wikimedia.org; the username and password should be the same.  If you can't, ask in  for someone to help.
 * Log in to Gerrit. If you know the changeset you want to look at (URL will look like https://gerrit.wikimedia.org/r/#change,2713 ), go to that. Otherwise, use the search box and try searching.  There is no fulltext search in Gerrit, but you can search by author ("Owner"), Gerrit project, branch, changesets you've starred, etc.
 * The changeset has a few important fields, links and buttons:
 * Reviewers. 'gerrit2' is the autoreviewer that auto-verifies anything that passes the Jenkins tests. If it passes, you see a green checkmark. If it fails, a red X.  A changeset needs a green checkmark before anyone can merge it. (In the future, the autoreviewer proxy usernames will change to be more indicative, "jenkins" or "lint".)
 * Add reviewer (manually ping someone to request their review. It'll show up in their Gerrit stream)
 * Side-by-side diff button:
 * Opens the diff in a new tab. You can double-click on a line and comment on that line, then save a draft comment! Then, click "Up to change" to go back to the changeset.
 * Abandon Change button (you'll see this if you wrote this diff. This action removes the diff from the merge queue, but leaves it in Gerrit for archival purposes)
 * Review button:
 * On this page you can leave an overall comment, view inline comments from the diff that are still in draft form and awaiting publication, and signal your thoughts on the commit. You can signal approval with a "+1" and disapproval with a "-1".  These numbers are nonbinding, won't cause merges or rejections, and have no formal effect on the code review.  To publish your draft inline comments plus your comments on the diff as a whole, click Publish.

Formally reviewing and merging or rejecting code
If you are one of the Gerrit project owners, you'll also see:
 * Abandon Change button
 * on the Review page, additional Code Review options to +2 (approve) or -2 (veto) a diff, and a Publish And Submit button (publish your comment and merge diff into the branch, in 1 step)
 * Submit Patch Set 1 button (merge -- only useful if you or someone else has already given a +2 approval to the diff, but not merged it)

And once you've merged something into the example Gerrit project you'll see it in https://gerrit.wikimedia.org/r/gitweb?p=test/mediawiki/extensions/examples.git;a=summary.

If you merge a commit that references a Bugzilla bug, please go to that bug and mark it RESOLVED: FIXED and reference the merge ID.


 * ''Teacher: for this section, add the participant to the project owner group for the  Gerrit project at https://gerrit.wikimedia.org/r/#admin,group,17 . Add the "Member" by email or wiki username.

How to create a repository ("Gerrit project")
See "Request a new Git repository". There's a form to fill out. It should get processed very quickly (within a couple of days).