Gerrit/Tutorial

Right now Git/Workflow is a better tutorial - this page is to develop a good hourlong step-by-step tutorial for the Berlin Hackathon 2012.

What is Git?
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.

Why did Wikimedia engineering move from Subversion to Git
Three major reasons: 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. 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.)

Some quotes from our community:

“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

And finally, 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.

Setting up Git
On Ubuntu you can install the Git command line tool via the following command: sudo apt-get install git-core For other Linux distributions please check your vendor documentation.

A windows version of Git can be found on the msysgit Project site.

The URL to this webpage is http://code.google.com/p/msysgit/.

Configure Git
git config -l Check that you have a name and email address configured; if you don't, tell Git your username and e-mail address so gerrit can attach it to your accounts: git config --global user.email "preilly@wikimedia.org" git config --global user.name "preilly"

Download MediaWiki core using Git
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.

Enter in the following on your command line: git clone https://gerrit.wikimedia.org/r/p/mediawiki/core.git



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

Installing git-review
First, install the release version of git-review using python package installer : $ sudo apt-get install python-pip $ sudo pip install git-review





Note: if you don't have  but have   installed, you can use this: $ sudo easy_install pip $ sudo pip install git-review pip


 * submitting a patch
 * commenting on a patch in Gerrit
 * merging a patch in Gerrit

Setting up git-review
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 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
The main avenue for submitting changes to MediaWiki is to first get Developer access so you can submit changes to Gerrit, our code review tool. Getting developer access is easy.

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

Create a branch
First, create a local branch for your new change. Give the branch a short but reasonably descriptive name. git checkout -b BRANCHNAME master 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".

Usual way
Change the code in the examples directory in some way; have fun! Review the changes you have made by using git status, it will show all modified files. To prepare submitting file, you should add your change to the index (the staging area between your working copy and your local repositroy), that is done by using the git add command.

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.

Once you are happy with the change list, you can add them to your local repository by using git commit. You will then be prompted with your favorite editor to add descriptive message for this commit. This is what other people will see when you will later push that commit to another repository.

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

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 LOCALLY. 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:

$ git add $ git status $ git diff --cached $ git commit
 * 1) Add change:
 * 1) Verify list of files added to the staging area
 * 1) Review diff of changes staged:
 * 1) repeat till happy

Prepare to push your change set to Gerrit
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, excute the following command: git pull origin master git rebase master

git pull will update the code in your local copy of the master branch. 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
If you installed, 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

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

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.

Collaborating

 * Gerrit project ownership - brief mention that there is a commit/abandon and how they can qualify for the permissions to do this.
 * something got tagged - what does that mean?
 * branching
 * local branch, making, working & pushing
 * remote branch & git-review to that remote branch
 * | Git Review
 * quick overview/invitation to building your review skills


 * Code Review process
 * | Old SVN Code Review article

Troubleshooting

 * cherrypick changes between branches
 * amending (rebase vs multiple commit)
 * | Managing Conflicts in Gerrit Repo (Merge or Rebase)
 * | Rebasing, empty commits, empty cherry picks
 * squashing work from a branch into a commit and pushing it
 * resolve merge conflicts

Deployment
If we have time to discuss.

Collection of Helpful Git/Gerrit Resource (please add to and incorporate these articles)
Old SVN download article
 * Localization: are these incorporated yet?
 * Is this bug fix incorporated in all MW Git/Gerrit documentation?
 * Git_notes_-_NOLA_Hackathon_2011.oga
 * Git_notes_-_NOLA_Hackathon_2011.pdf
 * Git Notes from NOLA hackathon - good distillation; only inaccuracies are around submits and Git review tool.