comparison hgext/bugzilla.py @ 7504:d8cd79fbed3c

Revise Bugzilla module comments into extension help.

Revise the comments detailing module usage at the start of the Bugzilla
extension into extension help text.

Expand the detail given on extension settings, in an attempt to permit
the user to configure successfully without having to study the extension
code. Show a sample configuration as well.

7503:09508f8e2fa4

#
# Copyright 2006 Vadim Gelfer <[e-mail]>
#
# This software may be used and distributed according to the terms
# of the GNU General Public License, incorporated herein by reference.
#
# hook extension to update comments of bugzilla bugs when changesets
# that refer to bugs by id are seen.  this hook does not change bug
# status, only comments.
#
# to configure, add items to '[bugzilla]' section of hgrc.
#
# to use, configure bugzilla extension and enable like this:
#
#   [extensions]
#   hgext.bugzilla =
#
#   [hooks]
#   # run bugzilla hook on every change pulled or pushed in here
#   incoming.bugzilla = python:hgext.bugzilla.hook
#
# config items:
#
# section name is 'bugzilla'.
#  [bugzilla]
#
# REQUIRED:
#   host = bugzilla # mysql server where bugzilla database lives
#   password = **   # user's password
#   version = 2.16  # version of bugzilla installed
#
# OPTIONAL:
#   bzuser = ...    # fallback bugzilla user name to record comments with
#   db = bugs       # database to connect to
#   notify = ...    # command to run to get bugzilla to send mail
#   regexp = ...    # regexp to match bug ids (must contain one "()" group)
#   strip = 0       # number of slashes to strip for url paths
#   style = ...     # style file to use when formatting comments
#   template = ...  # template to use when formatting comments
#   timeout = 5     # database connection timeout (seconds)
#   user = bugs     # user to connect to database as
#   [web]
#   baseurl = http://hgserver/... # root of hg web site for browsing commits
#
# if hg committer names are not same as bugzilla user names, use
# "usermap" feature to map from committer email to bugzilla user name.
# usermap can be in hgrc or separate config file.
#
#   [bugzilla]
#   usermap = filename # cfg file with "committer"="bugzilla user" info
#   [usermap]
#   committer_email = bugzilla_user_name

from mercurial.i18n import _
from mercurial.node import short
from mercurial import cmdutil, templater, util
import re, time

7504:d8cd79fbed3c

#
# Copyright 2006 Vadim Gelfer <[e-mail]>
#
# This software may be used and distributed according to the terms
# of the GNU General Public License, incorporated herein by reference.

'''Bugzilla integration

This hook extension adds comments on bugs in Bugzilla when changesets
that refer to bugs by Bugzilla ID are seen. The hook does not change bug
status.

The hook updates the Bugzilla database directly. Only Bugzilla installations
using MySQL are supported.

The hook relies on a Bugzilla script to send bug change notification emails.
That script changes between Bugzilla versions; the 'processmail' script used
prior to 2.18 is replaced in 2.18 and subsequent versions by
'config/sendbugmail.pl'. Note that these will be run by Mercurial as the user
pushing the change; you will need to ensure the Bugzilla install file
permissions are set appropriately.

Configuring the extension:

    [bugzilla]
    host       Hostname of the MySQL server holding the Bugzilla database.
    db         Name of the Bugzilla database in MySQL. Default 'bugs'.
    user       Username to use to access MySQL server. Default 'bugs'.
    password   Password to use to access MySQL server.
    timeout    Database connection timeout (seconds). Default 5.
    version    Bugzilla version. Specify '3.0' for Bugzilla versions from
               3.0 onwards, and '2.16' for versions prior to 3.0.
    bzuser     Fallback Bugzilla user name to record comments with, if
               changeset committer cannot be found as a Bugzilla user.
    notify     The command to run to get Bugzilla to send bug change
               notification emails. Substitutes one string parameter,
               the bug ID. Default 'cd /var/www/html/bugzilla && '
                                   './processmail %s [e-mail]'.
    regexp     Regular expression to match bug IDs in changeset commit message.
               Must contain one "()" group. The default expression matches
               'Bug 1234', 'Bug no. 1234', 'Bug number 1234',
               'Bugs 1234,5678', 'Bug 1234 and 5678' and variations thereof.
               Matching is case insensitive.
    style      The style file to use when formatting comments.
    template   Template to use when formatting comments. Overrides
               style if specified. In addition to the usual Mercurial
               keywords, the extension specifies:
                   {bug}       The Bugzilla bug ID.
                   {root}      The full pathname of the Mercurial repository.
                   {webroot}   Stripped pathname of the Mercurial repository.
                   {hgweb}     Base URL for browsing Mercurial repositories.
               Default 'changeset {node|short} in repo {root} refers '
                       'to bug {bug}.\\ndetails:\\n\\t{desc|tabindent}'
    strip      The number of slashes to strip from the front of {root}
               to produce {webroot}. Default 0.
    usermap    Path of file containing Mercurial committer ID to Bugzilla user
               ID mappings. If specified, the file should contain one mapping
               per line, "committer"="Bugzilla user". See also the
               [usermap] section.

    [usermap]
    Any entries in this section specify mappings of Mercurial committer ID
    to Bugzilla user ID. See also [bugzilla].usermap.
    "committer"="Bugzilla user"

    [web]
    baseurl    Base URL for browsing Mercurial repositories. Reference from
               templates as {hgweb}.

Activating the extension:

    [extensions]
    hgext.bugzilla =

    [hooks]
    # run bugzilla hook on every change pulled or pushed in here
    incoming.bugzilla = python:hgext.bugzilla.hook

Example configuration:

This example configuration is for a collection of Mercurial repositories
in /var/local/hg/repos/ used with a local Bugzilla 3.2 installation in
/opt/bugzilla-3.2.

    [bugzilla]
    host=localhost
    password=XYZZY
    version=3.0
    bzuser=[e-mail]
    notify=cd /opt/bugzilla-3.2 && perl -T contrib/sendbugmail.pl %%s [e-mail]
    template=Changeset {node|short} in {root|basename}.\\n{hgweb}/{webroot}/rev/{node|short}\\n\\n{desc}\\n
    strip=5

    [web]
    baseurl=http://dev.domain.com/hg

    [usermap]
    [e-mail]=[e-mail]

Commits add a comment to the Bugzilla bug record of the form:

    Changeset 3b16791d6642 in repository-name.
    http://dev.domain.com/hg/repository-name/rev/3b16791d6642

    Changeset commit comment. Bug 1234.
'''

from mercurial.i18n import _
from mercurial.node import short
from mercurial import cmdutil, templater, util
import re, time