Today I have a tip to share, especially to the destination of Mike, to whom I praised the power of git-bz during the Documentation Hackfest in Brno last month.
When you work on GNOME, whether to code, translate or write documentation, you have to deal with two common components of the infrastructure, the GIT repository to commit your code and bugzilla, the bug tracking application.
git-bz is a git submodule developed by Owen Taylor that glues git and bugzilla together to lower the overhead of managing patches in bugzilla (open a bug → attach a patch → commit a patch → close a bug).
Set up & Configuration
For this article I assume you already configured git and you have commit access on the GNOME repository, I assume also you use Firefox as default web browser.
To get git-bz, you can put the version downloaded here into a directory defined in your PATH. you can also clone the git-bz repository.
git clone git://git.fishsoup.net/git-bz
ln -s ~/bin/ git-bz/git-bz
Type git-bz in a console and check the command returns the usage message, to make sure the sub-module is found.
Now we need configure to set the default bugzilla tracker and the browser you use
git config --global bz.browser firefox3
git config --global bz.default-tracker gnome
git config --global bz-tracker.gnome.host bugzilla.gnome.org
I use firefox as main browser and specially to access bugzilla.gnome.org so I defined the value bz-browser to firefox3 (which also matches all later ersions), so git-bz will be able to use my browser cookie to post on bugzilla.gnome.org with my credentials. You can also define other browsers like chrome.
The second line defines a tracker short name that will be named “gnome”, and the following line define the hostname of the bugzilla tracker which is bugzilla.gnome.org
Getting Started
We’ll use a really simple example, let’s suppose you want to want to correct a typo in the gedit documentation. So first I need to clone the gedit repository
git clone git.gnome.org/gedit
cd gedit
Now I do the fix in the documentation and I commit it.
git commit -a -m 'Fix a typo in the documentation'
Now to have your bugfix reviewed in bugzilla, normally you would:
- create the formatted patch from the commit, with git format-am
- go to your browser and open a bug in bugzilla against the empathy component
- locate the patch file in the file system
- attach the patch to the bug report.
That’s not a tough job, but it requires a lot of manual operations that can be avoided. With git-bz, you can do all theses operations in one command
git bz file gedit/docs HEAD
it means “file a new bug, against the product gedit and the component docs and attach a patch which is in my latest commit“. Before creating the bug, you’ll be asked to enter a title and a summary to explain what is the defect.
If you check the commit history of your latest commit, you’ll see that git-bz rewrote the message to include the number of the tracker you have opened.
Once your patch is reviewed, the maintainer will ask you to commit your patch. Instead of doing a git push, and then closing the bug in bugzilla, you just have to do
git bz push
which will do the job for you. Simple isn’t it ?
Going further
Testing a patch
Imagine you want to test someone’s patch which is published on bugzilla, git-bz can retrieve it for you
git bz apply gnome:454353
“gnome” is the shorthand for the tracker defined earlier and 454353 is the tracker number. So the patch is now in your branch, so you can test it.
Attaching a patch to an existing bug tracker
Someone has reported a bug in bugzilla, and you want to fix it.
Work on a branch (master or a dedicated one)
Once you’ve made the bug fix, commit it with a message pointing to the bug number as follows (first line is the summary, the second line is the description)
Fix the bug that makes the program useless
Fix the bug 345543
Then do a
git bz attach HEAD
git-bz will pick automatically the bug reference in the commit log and will attach the patch to bugzilla.
More documentation
This post is just an introduction to git-bz and to have the full picture of the power of git-bz you can have a look to the page http://git.fishsoup.net/man/git-bz.html
Of course git-bz is not limited to GNOME bugzilla and should work with any bugzilla instance, with perhaps some tuning.
Have fun.