Submitting a patch to Mediawiki on Gerrit

I remember when I first submitted a patch to Mediawiki on Gerrit. It was a +12 -4 line patch and it probably took me at least half a day to figure everything out and get my change up! There is a tutorial on mediawiki.org but it is far too wordy and over complicated. In this post I try to explain things as basically as possible. Enjoy!

Git

In order to be able to submit a patch to Gerrit you need to have Git installed!

If your on a linux system you can install this using your package manager, eg. “apt-get install git”. If you are on another system such as Windows you can just use a build from git-scm. Basically just get git from https://git-scm.com/downloads!

Once you have downloaded Git you need to configure it!

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

Gerrit

Next you need to create an account for Gerrit. To do this navigate to gerrit.wikimedia.org, and click on the Register link in the top right. This will then take you to wikitech.wikimedia.org where you must create your account!

Once you have created an account and logged in you must add an SSH key. Go to your settings (again in the top right) and navigate to “SSH Public Keys“.

To generate a key do the following on your machine:

ssh-keygen -t rsa -C "example@example.com"

You should then be able to get your key from “~/.ssh/id_rsa.pub” (or the location you chose) and then add it to Gerrit.

Getting the code

Now that you have git and you have added your SSH key to gerrit you can use ssh to clone the code repository onto your local machine. Again you can read docs for this on the git-scm website.

git clone ssh://<USERNAME>@gerrit.wikimedia.org:29418/mediawiki/core

When logged in you can see the command at https://gerrit.wikimedia.org/r/#/admin/projects/mediawiki/core

Making a commit

Now you have the code cloned locally you can go ahead and change the files!

Once you have made your changes you should be able to review them using the follow command:

git diff

You can then add ALL changed files to a commit by doing the following:

git commit -a

A text editor should then load where you should enter a commit message, for example:

Fixing issue with unset new article flag

Some extra description can go here, but you
should try and keep your lines short!
A bug number can be linked at the bottom of
the commit as shown.

Bug: T12345

Once you have saved the text you will have make your commit! Now to try and push it as a change set to Gerrit (although it’s your first time so this will fail)!

You should get a message saying that you are missing a Change-Id in the commit message footer! This lovely message also contains the command that you need to run in order to fix the issue!

gitdir=$(git rev-parse --git-dir); scp -p -P 29418 <username>@gerrit.wikimedia.org:hooks/commit-msg ${gitdir}/hooks/

This created a hook file in your .git directory for this repo that will automatically add the Change-Id in the future! To get the Change-Id in your current commit message run:

git commit -a --amend --no-edit

And now you are ready to actually push your commit for review!

git push origin HEAD:refs/publish/master

You change should now be on Gerrit!

Your master branch is now 1 commit ahead of where master actually is, so to clean up and reset your local repo to the same state as the remote just run:

git reset --hard origin/master

You can always get back to your commit by using the hash of the commit with the “git checkout” command. Or you can copy the remote checkout command from the Gerrit UI, it looks something like the below:

git fetch https://gerrit.wikimedia.org/r/mediawiki/core refs/changes/74/257074/1 && git checkout FETCH_HEAD

Amending your change

If people comment on your commit on Gerrit you many want to change it, fixing the issues that people have pointed out.

To do this checkout your change again as described above, either using the hash locally the fetch & checkout command you can copy from the Gerrit UI.

git checkout d50ca328033702ced91947e60939e3550ca0212a
//OR
git fetch https://gerrit.wikimedia.org/r/mediawiki/core refs/changes/74/257074/1 && git checkout FETCH_HEAD

Make your changes to the files.

Amend the commit (you can add –no-edit if you do not want to edit the commit message):

git commit -a --amend

And push the patch again!

git push origin HEAD:refs/publish/master

Notes

This post covers the bare necessities for submitting a patch to Gerrit and responding to comments. There are many things it does not cover such as Git, re-basing, drafts, cherry-picks, merge resolution etc.

Also I should point out that Gerrit is going to be disappearing very soon in favour of Diffuision so there may have been little point in me writing this, but someone asked!

If you do not want to use git-review to contribute to Wikimedia or Gerrit projects then the most important thing to raw from this post is the under advertised “git push HEAD:refs/publish/master” command!