In Mercurial, how can I tie a bunch of commits to a single issue in our bugtracker?

We currently use svn and, through the user of hooks, are able to ensure that every commit message is prefixed by a bug-number (which ties those commits to a problem report in our Bugzilla issue tracker.)

We wish to move to mercurial with all of its distributed goodness. But one of the benefits of hg is that developers wouldn't necessarily need to to be online to commit changes, so we don't want hook scripts validating bug numbers against our central Bugzilla resource.

I may be coming at this from an svn perspective too much, but what I think I want is for developers to be able to specify a bug number at the time when the developer decides to push their change to a central testing repo. The key requirement here is that we want to be able to tie back commits to a Bugzilla bug, but we don't want to give developers a complex and manual workflow (which the Attic extension, for example, seems to impose.)

Any ideas?

Solution 1:

The important thing to remember is that changesets are (nearly) immutable, which means that it's too late to add a bug number when the developers are running hg push. The push command is only moving changesets around, not changing them.

However, hg push is of course a good time to go and update Bugzilla since the developers are online when pushing to the central repository. So you could ask the developers to install a hook like

[hooks]
pre-push.bugzilla = pick-bug-number.sh

The pick-bug-number.sh script should first check that the developers are pushing to your central repository (and not, say, to some other repository on their laptop) and then ask them for a bug number. When the developer enters the bug number, the script can look at hg outgoing and associate the outgoing changesets with the bug in Bugzilla.

That is one way of associating changesets with an external issue tracker. There wont be anything in the changesets that tie them to a Bugzilla bug — it's only Bugzilla that knows that changesets belong to what bugs.

Another way would be to embed the bug numbers into the changesets themselves. This can be done with named branches in Mercurial. Have your developers run

$ hg branch bug-123

before starting work on bug number 123. The following commits will then contain the "bug-123" label inside them. When pushing to the server, it's easy to parse the pushed changesets (in a changegroup hook) and update Bugzilla.

You can also ask the developers to put the bug number into the commit message, just like with Subversion. There wont be any online validation, but they can follow pretty much the same workflow as in Subversion. Validating the commit message is best done by configuring ui.editor. Make it a custom script that will ask for a bug number, put that into a commit message template and then start and editor to let the developers enter the commit message.

Using commit messages is better than using named branches if you plan to have thousands of bug numbers. Mercurial itself scales fairly well with the number of named branches, but many tools expect to be able to show all branches in a single drop-down menu. That works fine when you have 10 or 20 of them, but fails when you have 5,000 of them. It's really more of a UI thing, but it might come back and bite you long after you've started this system.