Gerrit/Advanced usage

This page describes the workflow for how MediaWiki core and extensions developers use git and gerrit. (To come: git-review docs here provided we use it.)



The diagram on the right is an accurate description of what our git workflow will look like. (Transcription is welcome!) To understand how our gerrit workflow will work, see these pages:


 * http://wiki.openstack.org/GerritWorkflow
 * http://source.android.com/source/life-of-a-patch.html

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

The gerrit review workflow might change; Roan & Chad are investigating using git-review, a tool that would help us better use git and gerrit together. If you'd like to try it out, we're seeking test subjects! Also, John Du Hart would like for us to consider using Phabricator instead.

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.

Clone the repository
Step 1 is to clone the repository in question that you're wanting to make a change on. Do this in your command line by typing (replacing mediawiki/core.git with mediawiki/extensions/FooBar.git 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 :)

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 so gerrit understands how to work with it.

Git-review
The easiest way to use gerrit is to install git-review. If you've done that, you can run: git review -a In your cloned copy to setup to work with gerrit. It will probably ask you for your username. The pre-commit hook will be automatically installed.

Manual setup
If installing git-review is not feasible for you, you'll need to download the commit-msg hook and place it in .git/hooks/ (should be in your cloned copy of the repository). You may also find it useful to 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 copy: git config alias.push-for-review "push origin HEAD:refs/for/master"

Commit a change
Make some changes in your working copy like you usually would, have fun! Commit them to your copy by doing a git commit -a (don't forget to git add any new files).

Push your change to gerrit
If you installed git review, 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

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