Gerrit/Tutorial/tl;dr

This short TLDR-style guide is aimed developers that have some experience with Git, and want to get started with Gerrit for MediaWiki development. For a tutorial with detailed explanations, read Gerrit/Tutorial instead.

Prerequisites

1. Install Git and git-review .
2. Create a new SSH key to use with Wikimedia Gerrit:
   • Run the following from your terminal, substituting your email address:

     ssh-keygen -t ed25519 -C "your_email@example.com"

   • At the "Enter a file in which to save the key" prompt, you can press Enter to accept the default if this is your first SSH key. Otherwise, customize it to something like /Users/YOUR_NAME/.ssh/id_wikimedia_gerrit
   • At the "Enter passphrase:" prompt, choose a strong passphrase. You will typically have to the first time on a given day when pulling or sending change requests.
3. Create a Wikimedia developer account. Then, log in on gerrit.wikimedia.org and add your public key to your account. The public key is the content of /Users/you/.ssh/id_wikimedia_gerrit.pub
4. Configure Git to set your email address, name, and SSH username.

Get the code

Clone the repository using the command in the repository browser (e.g. https://gerrit.wikimedia.org/g/mediawiki/core). You can find these on the list, or from the extension infobox on mediawiki.org. The most commonly cloned repositories are:

MediaWiki core: git clone https://gerrit.wikimedia.org/r/mediawiki/core.git mediawiki

MediaWiki extensions: git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/<extension>.git

MediaWiki skins: git clone https://gerrit.wikimedia.org/r/mediawiki/skins/<skin>.git

Write your patch

Start your branch from the latest production branch:

mediawiki$ git checkout master
mediawiki$ git pull
mediawiki$ git checkout -b meaningful-branch-name

NOTE

In some cases, the production branch may be called "production" or "main" and require a modified checkout command such as:

mediawiki$ git checkout production

mediawiki$ git checkout main

Now you can edit the code to make and test your changes. Once you are satisfied and the code is operational ready:

• git commit --all When working with Gerrit, do this only once per branch. To fix mistakes, use git commit --amend.
• git show Review your patch to confirm what you are submitting to us. Press "q" to quit.
• git review This pushes to Gerrit and creates a change request. If you receive an error and have previously installed the older "gerrit-tools" program, install "git-review" instead.

You are encouraged to invite one or two maintainers as reviewers on your change. After creating the change request, the git review will have printed the URL for you change request. You can also find your changes through your Gerrit dashboard. On the change page, under "Reviewers", click the "Add Reviewer" pencil button. Write a reviewer name in the input box. If you don't know who to invite for reviewing, check the maintainers list for the component you've modified, or ask on IRC (#mediawiki ^connect).

Update your patch

If a reviewer asks you to make changes, amend your commit as follows:

• git review -d change_ID e.g. 1234 in https://gerrit.wikimedia.org/r/1234. This downloads and checks out the change request from Gerrit.
• Edit the source files to make your changes.
• git commit --all --amend You can run this as many times as you like. When editing the commit message, leave the "Change-Id" line intact.
• git review This updates your change request in Gerrit, with a new patch set version reflecting your change, and automatically notifies the subscribed reviewers.

See also

• Try to follow our Commit message guidelines
• See also Getting reviews