User:OrenBochman/Git

From Meta, a Wikimedia project coordination wiki
Jump to navigation Jump to search
Presa de decissions.png This is an assignment for Simone's adoption program. You are welcome to edit this page if you notice any errors or have any additional information to add, but as a courtesy, please notify OrenBochman if you make any major changes to avoid any possible confusion between him and his adoptee(s). Thanks!
Git-Gerrit lets us deploy your code faster and makes collaboration easier!

GIT[edit]

The tutorial will help you with:

  • step-by-step instructions and screenshots for getting Gerrit access
  • setting up Git on your machine
  • configuring Git
  • installing Git-review
  • submitting a patch
  • the MediaWiki code review process

How to Use this Tutorial[edit]

Prepare for Tutorial[edit]

You will need a Labs account. You will also need to download Git (already in Ubuntu core) and any optional packages you want to use.

What is Git?[edit]

Git is a distributed version control system (dvcs) written in C originally developed by Linus Torvalds and others to manage the Linux kernel. In the past couple of years, it has taken off as a very robust and well-supported code repository. “Distributed” means that there is no central copy of the repository. With Subversion, Wikimedia’s servers host the repository and users commit their changes to it. In contrast, 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.

Git is a free and open source distributed version control system designed to handle everything from small to very large projects with speed and efficiency. Git is easy to learn and has a tiny footprint with lightning fast performance. It outclasses SCM tools like Subversion, CVS, Perforce, and ClearCase with features like cheap local branching, convenient staging areas, and multiple workflows.

What is Gerrit?[edit]

Gerrit is a free, web-based collaborative code review tool that integrates with Git. It has been developed at Google by Shawn Pearce (co-author of Git, founder of JGit) for the development of the Android project.

Starting from a set of patches for Rietveld, it became a fork and evolved into a full blown project when ACL patches wouldn't be merged into Rietveld by its author, Guido van Rossum.

Originally written in Python like Rietveld, it is now written in Java (Java EE Java Servlet) with SQL since version 2.

Why did Wikimedia migrate from Subversion to Git[edit]

Three major reasons:

  1. To encourage participation: Since Git is distributed, it allows people to contribute with a much lower barrier to entry. Anyone will be able to clone the repository and make their own changes to keep track of them. And if you’ve got an account in our code review tool (Gerrit), you’ll be able to push changes for the wider community to review.
  2. To fix our technical process: Subversion has technical flaws that make life difficult for developers. Notably, the implementation of branching is not very easy to use, and makes it hard to use “feature branches”. Our community is very distributed, with many parallel efforts and needs to integrate many different feature efforts, so we’d like to use feature branches more. Git branches are very easy to work with and merge between, which should make things easier for our development community. (Several other large projects, such as Drupal and PostgreSQL, have made the same switch for similar reasons, and we’ve done our best to learn from their experiences.)
  3. To get improvements to users faster: With better branching and a more granular code review workflow that suits our needs better, plus our ongoing improvements to our automated testing infrastructure, we won’t have to wait months before deploying already-written features and bugfixes to Wikimedia sites.

Some quotes from our community[edit]

  • "I love git just because it allows me to commit locally (and offline)." – Guillaume Paumier
  • "[Y]ou can create commits locally and push them to the server later (great for working without wifi), you can tell it 'save my work so I can go do something else now' in one command, and it’ll allow us to review changes before they go into 'trunk' (master)…. without human intervention in merging things into trunk. Gerrit automates this process." – Roan Kattouw


Setting up Git[edit]

On Ubuntu you can install the Git command line tool via the following command:

 sudo apt-get install git-core

File:Screen Shot 2012-05-25 at 10.39.36 AM.png

Mac OS X[edit]

Git for the Mac platform

Windows[edit]

Git for the Windows platform

Optional packages:[edit]

IMPORTANT: Add the git directory to your path.

Linux and Unix[edit]

It is easiest to install Git on Linux using the preferred package manager of your Linux distribution.

Debian/Ubuntu

$ apt-get install git-core

Fedora

$ yum install git

Gentoo

$ emerge --ask --verbose dev-vcs/git

FreeBSD

$ cd /usr/ports/devel/git
$ make install

Solaris 11 Express

$ pkg install developer/versioning/git

OpenBSD

$ pkg_add git

For other Linux distributions please check your vendor documentation.

Now that you have Git set up and your SSH keys entered into Gerrit, it’s time to configure your personal info.

Configure Git[edit]

Now that you have Git on your system, you’ll want to do a few things to customize your Git environment. You should have to do these things only once; they’ll stick around between upgrades. You can also change them at any time by running through the commands again.

Git comes with a tool called git config that lets you get and set configuration variables that control all aspects of how Git looks and operates.

git config -l

File:Git config -l.png

Set your username and email[edit]

Git tracks who makes each commit by checking the user’s name and email. In addition, we use this info to associate your commits with your gerrit account. To set these, enter the code below, replacing the name and email with your own.

 git config --global user.email "preilly@wikimedia.org"
 git config --global user.name "preilly"

File:Git config email and username.png

Download MediaWiki example extension using Git[edit]

You can currently download MediaWiki core using Git, as well as any extension currently installed on the Wikimedia Foundation server cluster. By July 2013, all extensions will either be available using Git or move to alternate version control hosts.

The first step is to clone the MediaWiki repository.

In order to collaborate with us, or if you want to get a copy of the MediaWiki repository so you can look at or use the code, you will clone it. You simply run the following on your command line:

git clone https://gerrit.wikimedia.org/r/p/test/mediawiki/extensions/examples.git

Git clone.png

This will copy the entire history of the MediaWiki repository so you have it locally and it will give you a working directory of the main branch so you can look at the code or start editing it. If you change into the new directory, you can see the .git subdirectory - that is where all the project data is.

By default, Git will create a directory that is 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 something different, you can just put it at the end of the command, after the URL. So, in this example you will have a core directory.

File:Ls -al.png

Prepare to work with gerrit[edit]

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 have lost track of it.

Installing git-review[edit]

First, install the release version of git-review using python package installer pip:

$ sudo apt-get install python-pip

On OpenSuse, install via YaST python-setuptools, then run

$ easy_install pip

File:Apt-get install python-pip.png

$ sudo pip install git-review

File:Pip install git-review.png

Note: if you don't have apt-get but have python installed, you can use this:

$ sudo easy_install pip
$ sudo pip install git-review pip

Setting up git-review[edit]

After cloning a repository, you need to set up for using 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.

 $ git review -s

Which should give you this: File:Git review -s.png

If you see the authenticity of host gerrit.wikimedia.org can't be established... Don’t worry, this is supposed to happen. Type “yes”.

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

Internally, this does the following:

  • checks whether accessing the remote repository works
  • if it doesn't, asks for a username and tries again
  • creates a remote called 'gerrit' that points to gerrit
  • installs the commit-msg hook

How to submit a patch[edit]

The main avenue for submitting changes to MediaWiki is to first join the MediaWiki development community so you can submit changes to Gerrit, our code review tool. Getting developer access is relatively easy.

Update master[edit]

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

git pull origin master

File:Git pull origin master.png

Create a branch[edit]

First, create a local branch for your new change. Give the branch a short but reasonably descriptive name.

git checkout -b BRANCHNAME master

File:Git checkout -b 2012-bug12345 master.png

This will create a new branch (BRANCHNAME) from 'master' and check it out for you. This is equivalent to doing

git branch BRANCHNAME master
git checkout BRANCHNAME

Use a descriptive branch name. If you are working on a bug, include its id, for example "2012/bug12345".

Make and commit your change[edit]

Usual way[edit]

Modify your local code in some fashion.

vim Example/Example.body.php

File:Vim Example.png

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

git diff

Git diff.png

Without any extra arguments, a simple git diff will display in unified diff format (a patch) what code or content you've changed in your project since the last commit that are not yet staged for the next commit snapshot.

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

git status

Git status.png

You run git status to see if anything has been modified and/or staged since your last commit so you can decide if you want to commit a new snapshot and what will be recorded in it.

This will show all modified files. To prepare submitting a file, you should add your changes to the index (the staging area between your working copy and your local repository), which is done by using the git add command. (Note that git add newly stages files. But git -a stages any files previously committed.)

git add Example/Example.body.php

File:Git status 2.png

You run git add on a file when you want to include whatever changes you've made to it in your next commit snapshot. Anything you've changed that is not added will not be included - this means you can craft your snapshots with a bit more precision.

While doing so you can always review the change already added to the staging area by invoking git status and look at the diff with

git diff --cached

.

File:Git diff --cached.png

The git diff --cached command will show you what contents have been staged. That is, this will show you the changes that will currently go into the next commit snapshot.

Once you are happy with the change list, you can add them to your local repository by using

git commit

.

File:Git commit vim.png

Now that you have staged the content you want to snapshot with the git add command, you run git commit to actually record the snapshot.

You will then be prompted with your favorite editor to add a descriptive message for this commit. This is what other people will see when you will later push that commit to another repository.

Git commit.png

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. One of the cool things about git is that when you git commit, 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, unlike in SVN where you would want to be very careful that the changes you commit would not cause things to break.

Hence the workflow is something like:

# Add change:
$ git add <some file>
# Verify list of files added to the staging area
$ git status
# Review diff of changes staged:
$ git diff --cached
# repeat until you are happy with your changes
$ git commit
<edit commit message>

Prepare to push your change set to Gerrit[edit]

Before your changes can be merged into master, they must undergo review in Gerrit.

But first, it's a good idea to synchronize your change set with any changes that may have occurred in master while you've been working. From within the branch you've been working on, execute the following command:

git pull origin master
git rebase master

File:Git pull origin master 2.png

git pull will update the code in your local copy of the master branch.

File:Git rebase master.png

Then, git rebase will temporarily set aside the changes you've made in your branch, apply all of the changes that have happend in master to your working branch, then merge 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 change set and you've rebased against master, you are ready to push your code to Gerrit for review.

Push your change set to Gerrit[edit]

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

git review -R

File:Git review -R.png

Upon success, you'll get a confirmation and a link to the changeset in Gerrit. New patchset: preilly; "Added get version method to extension" [test/mediawiki/extensions/examples] (master) - https://gerrit.wikimedia.org/r/9332

You can view this change in the Gerrit Web UI:

800x600px

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.

Amending a change[edit]

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.

If you have git-review, checkout the change like this:

git review -d <change number>

For example:

git review -d 9332

File:Git review -d 9332.png

Make changes.

vim Example/Example.body.php

File:Vim example.body file.png

git add the files as needed, then commit the change (ensuring you are amending the commit):

git add Example/Example.body.php
git commit --amend

File:Vim git commit amend.png

NOTE: DO NOT use the -m 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 if needed, and keep the Change-Id line intact.

Push the change

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

File:Git commit amend.png File:Git review -R 2.png

New patchset: preilly; "Added get version method to extension" [test/mediawiki/extensions/examples] (master) - https://gerrit.wikimedia.org/r/9332

800x600px

git review complains about multiple commits[edit]

If git review asks you if you really want to submit multiple commits, and lists a bunch of unrelated commits from different branches, try either of this:

git fetch --all
git remote update

Both commands do exactly the same thing, they fetch objects from all remote repositories set. So just pick the command you remember easily and forget about the other one.

File:Git remote update.png

How we review code[edit]

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[edit]

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[edit]

Who has the ability to do code review?

We use gerrit to manage code review. Anyone can ask for a Gerrit account (Get an account!). Within Gerrit, 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. (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". To learn about becoming a Gerrit project owner, see Git/Gerrit project ownership.

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

How to comment on, review, and merge code in Gerrit[edit]

File:Chrome publish comment 9332.png
A sample changeset, with annotations
File:Chrome diff 9332.png
Side-by-side diff

Anyone can comment on code in Gerrit.

Viewing and commenting on code[edit]

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,8939 ), 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 Gerrit search documentation covers all of the different search operators you can use.
  • The changeset has a few important fields, links and buttons:
  • Reviewers. 'jenkins-bot' 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.
  • 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. 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.

Comparing patch sets[edit]

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:

  • Select the older patch set in the "Old Version History" list.
  • Expand the newer patch set details by clicking the arrow near it.
  • Click Side-by-Side. Note that in Gerrit 2.3 this only works if you open the diff in the same tab, so don't open it in a new tab.

Formally reviewing and merging or rejecting code[edit]

If you are one of the Gerrit project owners, you'll also see:

File:Chrome review 9332.png
A Gerrit review screen with approval and veto options
  • 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.

See also[edit]

Also useful are these pages: Git/References

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[dead link?] instead; we will consider this in June 2012 (see also: Phabricator).

Discussion[edit]

Any questions or would you like to take the test?