Gerrit/Tutorial

'''This is a tutorial which explanations how to use Git and Gerrit for Wikimedia development. If you want to save time and are tech-savvy, use the very short how-to guide instead: Gerrit/Tutorial/tl;dr.'''

This tutorial explains how to:
 * set up and configure Git on your machine (to check out code repositories)
 * set up Gerrit access (for code review)
 * install git-review (to propose patches for code review)
 * submit a patch (changeset) for review
 * understand the MediaWiki code review process (commit, review, merge)

For power users, Gerrit/Advanced usage has additional documentation.

If you only want to play with Gerrit and do not want to write a patch for a "real" Wikimedia software project, use our Gerrit test instance instead.

What is Git?
Git is a free and open source distributed version control system. “Distributed” means that there is no central copy of the repository. With Git, once you’ve cloned the repository, you have a fully functioning copy of the source code, with all the branches and tagged releases at your disposal.

What is Gerrit?
Gerrit is a free, web-based collaborative code review tool that integrates with Git.

Setting up Git
These instructions explain how to install Git as a command-line (terminal window) tool. If you prefer a graphical user interface (GUI) instead of the command line, then check the list of clients maintained by the Git project. For alternate installation instructions see the official documentation.

Installation

 * Linux & UNIX:
 * Use the graphical software package management tool of your Linux distribution to install the  package.
 * If git has not been packaged by your distribution, then please ask in a support forum of your distribution.
 * Windows:
 * Install Git for Windows from https://gitforwindows.org/. This gives you Git, plus a shell called "Git Bash" that allows most of the command lines in these instructions to work on Windows.
 * If you want additional integration with the Windows shell, see Gerrit/TortoiseGit tutorial.


 * Mac OS X:
 * Install the Homebrew package manager and then run the command  – This is recommended, as it allows simple updating and easy installing of other packages.
 * As an alternative, you can install the stand-alone Git for Mac.

Configure Git
Now that you have Git installed, it’s time to configure your personal information. You should have to do this only once. You can also change your personal information at any time by running these commands again.

Git tracks who makes each commit by checking the user’s name and email. In addition, this info is used to associate your commits with your Gerrit account.

Enter the two commands below to set your username and email address. Replace the name and email address with your own: git config --global user.email "example@example.com" git config --global user.name "example"

To see your current configuration variables which control how Git behaves, use.

Set Up SSH Keys in Gerrit
We use an SSH key to establish a secure connection between your computer and Gerrit. To make sure whether you need to generate a brand new key, let's check if an SSH key already exists on your system. Run this command in a terminal: ls ~/.ssh The command will list the files that are in the (hidden)  directory. If the directory already exists on your system and if the output lists a file called, then you can go directly to.

Generate a new SSH key
To generate a new SSH key, enter the command below. We want the default settings so when asked to enter a file in which to save the key, just press enter. ssh-keygen -t rsa -C "your_email@youremail.com"

Enter a strong and unique passphrase and press the [Enter] key.


 * Why do passphrases matter?
 * Passwords aren’t very secure. If you use one that’s easy to remember, it’s easier to guess or brute-force. If you use one that’s random it’s hard to remember, so you might write the password down. Both are very bad. This is why you’re using ssh keys. But using an ssh key without a passphrase is basically the same as writing down that random password in a file on your computer. Anyone who gains access to your drive has gained access to every system you use that key with. That's why you also add a passphrase. To not enter a long passphrase every time you use the key, there’s a tool called . It can save your passphrase securely. If you use Mac OS X or Linux, then your keys can be saved in the system’s keychain to make your life even easier.

The  command will create 2 files in   directory:
 * : your private SSH key (for identification)
 * : your public SSH key

Copy your SSH Public key
Get the content of your public key file (e.g. ) to copy it to your clipboard:

One option is to open your public key file with your favorite text editor (Notepad, TextEdit, gedit, etc). In the file chooser dialog of your text editor, you may need to turn on “View hidden files” to find the file, because the  directory is hidden. Sometimes the “View hidden files” option is available by right-clicking in the file chooser dialog.

Other options are:
 * On Linux, run  and manually copy the output to the clipboard.
 * On Windows, you can open Git GUI, go to Help > Show Key, and then press "Copy To Clipboard" to copy your public key to your clipboard.
 * On Mac OS X, you can run  to copy the contents of the your public key file to your clipboard.

It’s important you copy your SSH Public key exactly as it is written, without adding any newlines or whitespace. Copy the full text, including the "ssh-rsa" prefix, the key itself, and the email address suffix.

Add SSH Public key to your Gerrit account

 * Create a Wikimedia developer account at wikitech.wikimedia.org if you do not yet have one. Your account's username and password will be the same for Gerrit.
 * Log into the web interface for Gerrit.
 * Click on your username in the top right corner, then choose "Settings".
 * Click "SSH Public Keys" in the menu on the left.
 * Paste your SSH Public Key into the corresponding field and click "Add".

Add SSH Private key to use with Git
Start the Git Bash command line.
 * Get ssh-agent running using
 * eval `ssh-agent`
 * Be sure to use the accent, not the single quote  . (You could copy and paste from this page if you cannot easily enter this special character.)


 * Add your private key to the agent. If you followed the steps above and your key has the default name, then the command is:
 * ssh-add .ssh/id_rsa


 * Connect to the Gerrit server via  to check if everything works as expected:
 * ssh -p 29418 @gerrit.wikimedia.org


 * Be paranoid and compare that the "RSA key fingerprint" is the same as the SSH fingerprint for gerrit.wikimedia.org:29418. If it is the same, answer "Yes" to "Are you sure you want to continue connecting?". Then enter the passphrase for your key.
 * Make sure that your  is the same name as in your Gerrit settings.
 * You should get a message "Welcome to Gerrit Code Review". The last line should show "Connection to gerrit.wikimedia.org closed."
 * If you run into problems, use  (the   will provide verbose output to help find problems) and read Gerrit/Troubleshooting.

An example Gerrit SSH connection success message looks like this:

Download code using Git
Let's practice downloading (also called "cloning") the Examples extension. Run the following on the Git Bash command line: git clone ssh://@gerrit.wikimedia.org:29418/mediawiki/extensions/examples (Substitute  by your Gerrit username. And make sure the URL begins with   and not  ).

This will copy the entire history and the code base of the "Examples" extension repository onto your machine. You will have a working directory of the extension's main branch (usually also called "git master"). If you enter the new directory (via the command ), you can look at the code and start editing it.

By default, Git will create a directory on your system which has the same name as the project in the URL you give it - basically whatever is after the last slash of the URL. If you want a different name, you can just put it at the end of the command, after the URL.

Obviously, just cloning the Examples extension will not give you a development environment setup or a running MediaWiki installation. (Running will require MediaWiki Core and placing the code you checked out in a location expected by your web server.)

You can download MediaWiki Core using Git, as well as the source code of any project repository hosted at gerrit.wikimedia.org.

For example, to clone the  repository or the repository of an extension which you are interested in: git clone ssh://@gerrit.wikimedia.org:29418/mediawiki/core.git git clone ssh://@gerrit.wikimedia.org:29418/mediawiki/extensions/.git (Substitute  by your Gerrit username and   by the extension name.)

You can also copy this git command from the top of the project's home page in Gerrit.

Even after executing these commands, you may experience later errors in installing the Vagrant virtual machine, for which these instructions must be followed to download the additional MediaWiki dependencies using composer, a PHP package management system, for MediaWiki versions ≥ 1.25.

Prepare to work with Gerrit
Gerrit requires that your commit message must have a "change ID". They look like  starting with an I (capital i)). Each time you amend a commit to improve an existing patch in Gerrit, this change ID stays the same, so Gerrit understands it as a new "patch set" to address the same code change.

There's a git add-on called git-review that adds a Change-ID line to your commits. Using git-review is recommended. It makes it easier to configure your Git clone, to submit a change or to fetch an existing one.

Installing git-review
For more details, please see Gerrit/git-review.


 * Linux & UNIX:
 * Use the graphical software package management tool of your Linux distribution to install the  package.
 * If git-review has not been packaged by your distribution, check Gerrit/git-review for other options such as installing git-review by using the pip Python package installer.
 * If you use FreeBSD, install git-review through ports.
 * Windows:
 * Please see Gerrit/git-review.
 * Mac OS X:
 * For OS X 10.11 El Capitan and later, follow Gerrit/git-review.
 * On versions prior to 10.11, use the pip Python package installer by following Gerrit/git-review.

Configuring git-review
Git's default remote host name is "origin". This name is also used by Wikimedia projects. We need to tell git-review to use that host. Replace  with the name next to 'Username' at https://gerrit.wikimedia.org/r/#/settings/.

Setting up git-review
After downloading ("cloning") a repository, you need to set it up for git-review. This will automatically happen the first time you try to submit a commit, but it's generally better to do it right after cloning. Make sure that you are in the directory of the project that you cloned (otherwise you will get an error "fatal: Not a git repository"). Then enter

Towards the end of the output, you should see something like this: Found origin Push URL: ssh://gerrit.wikimedia.org:29418/PROJECT Fetching commit hook from: scp://gerrit.wikimedia.org:29418/hooks/commit-msg 2019-02-19 12:40:16.712892 Running: scp -P29418 gerrit.wikimedia.org:hooks/commit-msg .git/hooks/commit-msg

This may ask you for your git username, if it's different from the shell username you're using.

How to submit a patch
Make sure that you cloned the code repository that you are interested in (see ).

Make sure that you are in the directory of the code repository (the command  tells you where exactly you are).

If you work on the  repository: You will have to probably clone   to your development server's   directory, which is set to   in most Apache web server installations. This can vary according to your web server software and version. Cloning directly to your  might not be permitted if you are a non-privileged user. You can create a directory inside your  and make it writeable by using the   command in Linux. Badly configured permissions can expose your development server to potential security risks.

Update master
Make sure that your master branch (the branch created when you initially cloned the repository) is up to date: git pull origin master

However, note that a few repositories use different terms (for example operations/puppet has a "production" instead of a "master" branch).

Create a branch
First, create a local branch for your new change. Give the branch a short but reasonably descriptive name (e.g.,  ,  , or  ). Keep in mind that other people will also use this name to identify your branch when they're reviewing your patch. git checkout -b BRANCHNAME origin/master

This will create a new branch (BRANCHNAME) from the latest 'master' and check it out for you.

Make your changes
Make changes to your local code. Use your preferred text editor and modify the file

Then check the changes you've made, within the file(s) and within the directory: git diff {{terminal|title=Example:|text= preilly@vumi:/mw/examples$ git diff diff --git a/Example/Example.body.php b/Example/Example.body.php index 29b3f2c..357b4de 100644 --- a/Example/Example.body.php +++ b/Example/Example.body.php @@ -14,4 +14,11 @@ class SpecialExample extends SpecialPage {

$wgOut->addWikiMsg( 'example-example' ); } + +      /** +        * Get version number of extension +       */ +       function getVersion { +              return '0.01'; +      } } preilly@vumi:/mw/examples$ }}

will display in unified diff format (a patch) the local changes that you have made since the last commit which are not yet "staged" (via ) for the next commit.

Stage your changes for a commit
helps you decide which of your changes should become part of your commit. It shows a list of the file(s) within the directory that you have changed: git status

Note the line "no changes added to commit" at the end.

Use  to make your changed file(s) become part of your next commit: git add Example/Example.body.php Any files you've changed that you have not passed to  will be ignored.

At any time you can always review the changes already staged by running. After you ran,   will not show the line "no changes added to commit" anymore.

You can also use  to see which changes are staged and will go into the next commit. The output will look the same as for the  command above.

Commit your staged changes
Once you are happy with the change list, you can add them to your local repository by using git commit

You will then be asked in your text editor to add a descriptive message for this commit message. Make sure that you follow the Commit message guidelines. This is what other people will see when you will later push that commit to another repository.

Normally, you do not manually add a Change-Id and it will be added in automatically once you exit the commit screen. Please see that you give the bug id correctly with the single spacing in between  as given in the above example.

Save the commit message and close your text editor. You will see a summary:

You can repeat this step over and over until you have a set of changes that you want to have pushed to the master branch. When you, you are committing to your local copy. This means you can commit as often as you like without potentially screwing things up for another developer on the project.

Prepare to push your commit to Gerrit
Before your changes can be merged into master and will become available to everybody who runs, they must get reviewed in Gerrit.

But first, it's a good idea to synchronize your changeset with any changes that may have occurred in master while you've been working ("rebasing"). From within the branch you've been working on, execute the following command: git pull --rebase origin master

This command will fetch new commits from the remote and then rebase your local commits on top of them. It will temporarily set aside the changes you've made in your branch, apply all of the changes that have happened in master to your working branch, then merge (recommit) 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.

Once you are satisfied with your changeset and you've rebased against master, you are ready to push your code to Gerrit for review. If you made several related commits, consider merging them into one single commit for review.

Push your commit to Gerrit
It is recommended to use  to submit patches for review. If you do not have installed  and do not want to do so, you can use the Gerrit patch uploader to submit your patch.

If you installed  and you ran   to set it up for this repository, the command to push changes to Gerrit is: git review -R The  option tells git-review not to perform a rebase before submitting the change to Gerrit.

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

Congratulations! Your patch is in Gerrit and hopefully will get reviewed soon!

View the Change / Next Steps




If you want to see your changed files in their context then click on the  link (you then will see).

In 2020, Gerrit's new web interface called "PolyGerrit" will become the default. You can use PolyGerrit via https://gerrit.wikimedia.org/r/?polygerrit=1 and the old interface via https://gerrit.wikimedia.org/r/?polygerrit=0

If your commit addresses a ticket in Phabricator, a comment will be automatically added in the Phabricator task if you followed the Commit message guidelines. If you did not, you could manually add a comment on that Phabricator ticket by linking to its changeset in Gerrit.

Gerrit's diff algorithm (jGit) is slightly different from git's default diff algorithm. The differences displayed by Gerrit might not look like the differences displayed by Git on your machine.

Other common situations
Also see Gerrit/Advanced usage if your situation is not covered here.

Squash several commits into one single commit via rebase
If you made several related commits to your local repository prior to wanting to submit for review, you should squash (merge) those commits into one single commit.

The  or   option allows you to change (rewrite) your commit history. For each commit, you can modify and change the commit message, add or remove files, or perform other modifications.

First you need to tell git how far back you want to pull. To get a list of all changes in your branch: git rebase -i origin/master

You can also limit the displayed list of recent changes. means pull the last three commits: git rebase -i HEAD~3

After you type this command, your text editor will display your commits in reverse order and a list of available commands:

Since we only want to send one commit to review, we will squash the last two commits into the first. Hence change all but the first "pick" to "squash": pick aa8cf1d Adding method customFilterFunctionGetRiskyCountryCodeScore to GatewayAdapter. squash 38828e2 Adding $wgDonationInterfaceCustomFiltersFunctionsRiskyCountries to donationinterface.php squash be33007 Fix a typo

When you finished picking and squashing and saved the file, another file will open in your text editor to allow you get to edit and merge your commit messages. Be careful to only keep one of the Change-Id lines and have it be at bottom of the message after one empty line.

Your messages from your previous commits will automatically be placed in this message:

Remember to put your (updated) summary message in the commit. In this case the new summary message will be: (mingle-fr-2012-69) Adding a custom filter for risky countries.

''In regards to which Change-Id you want to use, squashing a commit into an existing commit (one that's already in Gerrit), you need to pick the Change-Id that belongs to the one you meant to submit a new patchset for (the surviving commit). If your commits are new and are not in Gerrit, it does not matter which Change-Id you choose.''

If all goes well, you should see a successful rebase message:

Afterwards, submit your patch for review: git review

You should see a message like this showing your git review went to Gerrit (in this example, to https://gerrit.wikimedia.org/r/7187 ):

Amending a change (your own or someone else's)
BEWARE:  performs a hard reset that destroys all local changes. Stash or commit changes you wish to preserve first.

Sometimes, you might need to amend a submitted change. You can amend your own changes as well as changes submitted by someone else, as long as the change hasn't been merged yet.

Rebase to bring your local branch up to date with the remote. It's best to make rebase updates a separate patch, so that your code reviewers have an easy time seeing what changes you've made. Assuming you are using Gerrit, you can do this by clicking the "Rebase Change" button when viewing your patch in Gerrit's web interface.

If you have git-review, hard reset and checkout the change with this command: git review -d

Note, if you already have the change in a branch on your local repository, you can just check it out instead: git checkout

For example: git review -d 9332

Or, if you already have the branch, git checkout review/preilly/2012/bug12345 Should accomplish the same thing.

Next, make some changes. vim Example/Example.body.php

the files as needed, then commit the change (ensuring you are amending the commit): git add Example/Example.body.php git commit --amend --all

NOTE: DO NOT use the  flag to specify a commit summary: that will override the previous summary and regenerate the Change-Id. Instead, use your text editor to change the commit summary (in the file  if needed, and keep the Change-Id line intact.

Push the change git review -R
 * The  is important here. It tells git-review to not rebase your change against master, which clutters diffs between patch set 1 and 2.

Push to a branch different than master
In the screenshots above, the commit was pushed to the master branch. The branch name only appeared as the topic of the commit in the Gerrit UI. If you really want to push to a different branch than master, you have to push via.

Editing via the web-interface
If you're logged in to Gerrit, you can also edit within the web-interface. This can be useful for making small patches, or for non-developers to contribute small fixes. Done!
 * 1) Go to https://gerrit.wikimedia.org/r/#/admin/projects/foo (e.g. https://gerrit.wikimedia.org/r/#/admin/projects/mediawiki/extensions/Echo )
 * 2) * (perhaps via the mw:Extension:Foo page, using the "code review" link in the infobox, and then the click the project name in the list of past patches, and then "General" in the toolbar.
 * 3) Click "Create Change"
 * 4) Set branch to "master" (if you don't want to use master branch you can use the other branches available for that project)
 * 5) Set the topic to something of your choosing (e.g. "copy-edit" - must be all-one-string) (optional)
 * 6) Write a description ("commit summary") in the big text field, with:
 * 7) a one-line summary (This will be the commit title. It should be self-explanatory giving full context for the change, like a good edit-summary. It should Not end with a fullstop.)
 * 8) a blank line
 * 9) a more detailed paragraph (optional, if desired)
 * 10) "Bug: Txxxx"  (Must be a capital "B" and with space after the colon)
 * 11) * See example
 * 12) Click "Create"
 * 13) Under "Files", click the "Edit" button
 * 14) Under "Files", click "Add"
 * 15) Type the folder/file path for the file you wish to edit (e.g. i18n/en.json) and click "Open"
 * 16) Find the line(s) you want to change, and change them.
 * 17) Click "Save"
 * 18) Click "Close"
 * 19) Click "Publish edit"
 * 20) Click the button "Start Review"

For steps 1-6 there is also an alternative way:
 * 1) Go to https://gerrit.wikimedia.org/r/#/projects/foo,dashboards/default (e.g. https://gerrit.wikimedia.org/r/#/projects/mediawiki/extensions/Echo,dashboards/default )
 * 2) Click the topmost patch under "Merged Changes" of the chosen branch (e.g. master)
 * 3) Click "Follow-Up"
 * 4) Write a description ("commit summary") in the big text field similarly as in the step 5 above
 * 5) Click "Follow-Up"
 * 6) Change the topic to something of your choosing (e.g. "copy-edit" - must be all-one-string) (optional)

If you need to change the commit summary, you can use these steps:
 * 1) Under "File Path", click "Commit Message"
 * 2) On top of the right panel, click the "Edit" button
 * 3) Make changes to the commit summary.
 * 4) Click "Save"
 * 5) Click "Close"
 * 6) Click "Publish edit"

How code is reviewed in Gerrit
Code review is an essential part of our contribution workflow. The principle is basic: any patch must be reviewed by others before being merged.

This means that your code will need reviewers. Check our advice for getting reviews.

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 extension author who wants it for their extension. The one exception is localisation and internationalisation commits, which will be able to be pushed without review.

Who can review? Gerrit project owners
After creating a Gerrit account, anyone can comment on commits and signal their criticisms and approvals. Anyone can give a nonbinding "+1" to any commit. 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. 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".

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 (Get an account!). If you don't know, try logging in at https://wikitech.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/#/c/23939/ ), go to that. Otherwise, use the search box and try searching.  You can search by author ("Owner"), Gerrit project, branch, changesets you've starred, etc. The Gerrit search documentation covers all of the different search operators you can use.
 * The changeset has a few important fields, links and buttons:
 * Assignee. An optional field to make a single person responsible for handling reviewing the changeset. This should only be set if the assignee has agreed.
 * Reviewers. 'jenkins-bot' is the autoreviewer that auto-verifies anything that passes the Jenkins tests. It will report a red or green mark depending on whether the build passes.
 * The Add" button on the right of Reviewers:'''. Manually pings someone to request their review. It'll show up in their Gerrit dashboard.
 * Files: Open All. Opens the diff (each file in a separate browser tab). You can double-click on a line and then press C to comment on that line, then save a draft comment! Then, click the green "Up to change" arrow to go back to the changeset, and click "Reply…" to publish your comment.
 * Reply… ("Add comment"). Publish your thoughts on the commit, including an overall comment and/or inline comments you added (see above).
 * If, upon code review, you approve, use "+1" under "Reply…"; otherwise, use "-1" to disapprove. These numbers are nonbinding, won't cause merges or rejections, and have no formal effect on the code review.
 * Abandon (you'll see this if you wrote this diff). This action removes the diff from the list to review, but leaves it in Gerrit for archival purposes.

Comparing patch sets
Every time you amend your commit and submit it for review, a new patch set is created. You can compare the different patch sets like this:
 * Under Files, select either Open All or choose a specific file listed to open that file.
 * On the left side under Patch Set, Base is preselected. On the right of the screen under Patch Set, the latest patch set is preselected. Adjust the selected patch sets to your needs.

Formally reviewing and merging or rejecting code
If you are one of the Gerrit project owners, you'll also see:
 * Abandon button
 * under Reply, additional Code-Review options to +2 (approve) or -2 (veto) a diff, and a Post button (publish your comment and merge diff into the branch, in 1 step)
 * Submit 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/plugins/gitiles/test/mediawiki/extensions/examples/.

If you merged a commit that references a task in Phabricator and that commit is supposed to fix that task completely, please go to that task and change its status to "Resolved" (via the Add Action… 🡒 Change Status dropdown). Also reference the merge ID if gerritbot has not already posted it in that task.

Troubleshooting
For problems and how to solve them, see Gerrit/Troubleshooting.