#pragma section-numbers 2

= Bugzilla Extension =
'''This extension is currently being distributed along with Mercurial.'''

''Author: Jim Hague, Vadim Gelfer''

<<TableOfContents>>

== 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.

== 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
}}}

=== 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]`.

=== 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.
}}}

=== Example configuration settings ===

==== 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
}}}

==== 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
}}}

== Usage ==

This extension doesn't need user interaction to run.
----
CategoryBundledExtension CategoryBugtrackingExtensions