Bugzilla Extension
This extension is currently being distributed along with Mercurial.
Author: Jim Hague, Vadim Gelfer
Contents
1. Overview
This hook extension adds comments on bugs in Bugzilla when changesets that refer to bugs by Bugzilla ID are seen. The comment is formatted using the Mercurial template mechanism.
The bug references can optionally include an update for Bugzilla of the hours spent working on the bug. Bugs can also be marked fixed.
This extension works with Bugzilla v3.4 and later. Marking bugs fixed may require Bugzilla 4.0 and later.
2. Configuration
To use this extension, enable it in the configuration file (hgrc) like this:
[extensions] hgext.bugzilla = [hooks] # run bugzilla hook on every change pulled or pushed in here incoming.bugzilla = python:hgext.bugzilla.hook
To configure the 'bugzilla' extension you add items to '[bugzilla]' section of hgrc.
You need to configure access to your Bugzilla instance, and the method used for updating Bugzilla, which can be either XMLRPC or XMLRPC+email.
Access via XMLRPC needs a Bugzilla username and password to be specified in the configuration. Comments are added under that username. Since the configuration must be readable by all Mercurial users, it is recommended that the rights of that user are restricted in Bugzilla to the minimum necessary to add comments. Marking bugs fixed requires Bugzilla 4.0 and later.
Access via XMLRPC/email uses XMLRPC to query Bugzilla, but sends email to the Bugzilla email interface to submit comments to bugs. The From: address in the email is set to the email address of the Mercurial user, so the comment appears to come from the Mercurial user. In the event that the Mercurial user email is not recognized by Bugzilla as a Bugzilla user, the email associated with the Bugzilla username used to log into Bugzilla is used instead as the source of the comment. Marking bugs fixed works on all supported Bugzilla versions.
A minimal configuration using XMLRPC looks like this:
[bugzilla] version=xmlrpc bzurl=http://bugzilla.example.com user=bugs # Username to use to log into Bugzilla, default 'bugs'. password=... # User password.
For full details of the available configuration settings, use the Mercurial help.
hg help bugzilla
2.1. Configuration with XMLRPC/email
[bugzilla] version=xmlrpc+email bzurl=http://bugzilla.example.com user=bugs # Username to use to log into Bugzilla, default 'bugs'. password=... # User password. bzemail=bugzilla@example.com # Address for emails to Bugzilla.
When using XMLRPC/email, you can specify mappings of Mercurial committers to Bugzilla users.
[bugzilla] usermap = filename # cfg file with "committer"="bugzilla user" info [usermap] committer_email = bugzilla_user_name
In addition, the Mercurial email settings must be configured. See the documentation in hgrc(5), sections [email] and [smtp].
2.2. Other common configuration settings
[bugzilla] regexp=... # Regular expression to match bug IDs for update in changeset commit message. fixregexp=... # Regular expression to match bug IDs to mark fixed in changeset commit message. fixstatus=RESOLVED # Bug status to use when marking bug fixed. fixresolution=FIXED # Bug resolution to use when marking bug fixed. style=... # Style file to use when formatting comments for Bugzilla. template=... # Template to use when formatting comments. Overrides style. strip=0 # Separator characters to strip from Mercurial repository path to get web root. baseurl=... # Web root for browsing Mercurial repository.
2.3. Example configuration settings
2.3.1. XMLRPC
XMLRPC example configuration. This uses the Bugzilla at http://my-project.org/bugzilla, logging in as user bugmail@my-project.org with password plugh. It is used with a collection of Mercurial repositories in /var/local/hg/repos/, with a web interface at http://my-project.org/hg.
[bugzilla]
bzurl=http://my-project.org/bugzilla
user=bugmail@my-project.org
password=plugh
version=xmlrpc
template=Changeset {node|short} in {root|basename}.
{hgweb}/{webroot}/rev/{node|short}\n
{desc}\n
strip=5
[web]
baseurl=http://my-project.org/hg
2.3.2. XMLRPC+email
XMLRPC+email example configuration. This uses the Bugzilla at http://my-project.org/bugzilla, logging in as user bugmail@my-project.org with password plugh. It is used with a collection of Mercurial repositories in /var/local/hg/repos/, with a web interface at http://my-project.org/hg. Bug comments are sent to the Bugzilla email address bugzilla@my-project.org.
[bugzilla]
bzurl=http://my-project.org/bugzilla
user=bugmail@my-project.org
password=plugh
version=xmlrpc+email
bzemail=bugzilla@my-project.org
template=Changeset {node|short} in {root|basename}.
{hgweb}/{webroot}/rev/{node|short}\n
{desc}\n
strip=5
[web]
baseurl=http://my-project.org/hg
[usermap]
user@emaildomain.com=user.name@bugzilladomain.com
3. Usage
This extension doesn't need user interaction to run.