← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to doc/en/user-guide/bug_trackers.txt

  • Committer: Patch Queue Manager
  • Date: 2016-04-21 04:10:52 UTC
  • mfrom: (6616.1.1 fix-en-user-guide)
  • Revision ID: pqm@pqm.ubuntu.com-20160421041052-clcye7ns1qcl2n7w
(richard-wilbur) Ensure build of English use guide always uses English text
 even when user's locale specifies a different language. (Jelmer Vernooij)

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/en/user-guide/bug_trackers.txt
1
 
============
2
 
Bug Trackers
 
1
Bug trackers
3
2
============
4
3
 
5
4
Bazaar has a facility that allows you to associate a commit with a bug
6
 
in the project's bug tracker. Other tools can then use this information
7
 
to link between the commit and the bug, or to automatically mark the bug
8
 
closed in the branches that contain the commit.
9
 
 
10
 
Associating Commits and Bugs
11
 
============================
12
 
 
13
 
When you make a commit you can assiociate it with a bug by using the
 
5
in the project's bug tracker. Other tools (or hooks) can then use this
 
6
information to generate hyperlinks between the commit and the bug, or to
 
7
automatically mark the bug closed in the branches that contain the commit.
 
8
 
 
9
Associating commits and bugs
 
10
----------------------------
 
11
 
 
12
When you make a commit, you can associate it with a bug by using the
14
13
``--fixes`` option of ``commit``. For example::
15
14
 
16
 
    $ bzr commit --fixes 12345 -m 'Properly close the connection on errors'
17
 
 
18
 
This will set a revision property on the revision that is committed
19
 
which contains the URI at which more information on the bug can be found.
20
 
Bazaar itself does no more than this, but once the information is recorded
21
 
other tools can make use of it.
22
 
 
23
 
Configuration of the Bug Tracker
24
 
================================
25
 
 
26
 
As each project has it's own bug tracker, and there are many different
27
 
bug tracking systems you must first do some configuration before you
28
 
can use this system.
29
 
 
30
 
Bazaar currently implements support for projects that use Bugzilla or
31
 
Trac to manage their bugs. If your project uses a different system it
32
 
is easy to add support for the system, perhaps through a plugin.
33
 
 
34
 
If you do use Bugzilla or Trac then you only need to set a configuration
35
 
variable which contains the base URL of the bug tracker. These options
36
 
can go into ``bazaar.conf``, ``branch.conf`` or into a branch-specific
37
 
configuration section in ``locations.conf``.
38
 
 
39
 
You can set up these values for each of the projects you work on in
40
 
``bazaar.conf``, as you specify a short name for each so that you
41
 
can specify which you mean at commit time.
42
 
 
43
 
bugzilla_<tracker_abbreviation>_url
44
 
-----------------------------------
45
 
If present, the location of the Bugzilla bug tracker referred to by
46
 
<tracker_abbreviation>. This option can then be used together with ``bzr commit
47
 
--fixes`` to mark bugs in that tracker as being fixed by that commit. For
48
 
example::
49
 
 
50
 
    bugzilla_squid_url = http://www.squid-cache.org/bugs
51
 
 
52
 
would allow ``bzr commit --fixes squid:1234`` to mark Squid's bug 1234 as
53
 
fixed.
54
 
 
55
 
trac_<tracker_abbrevation>_url
56
 
------------------------------
57
 
If present, the location of the Trac instance referred to by
58
 
<tracker_abbreviation>. This option can then be used together with ``bzr commit
59
 
--fixes`` to mark bugs in that tracker as being fixed by that commit. For
60
 
example::
61
 
 
62
 
    trac_twisted_url = http://www.twistedmatrix.com/trac
63
 
 
64
 
would allow ``bzr commit --fixes twisted:1234`` to mark Twisted's bug 1234 as
65
 
fixed.
66
 
 
67
 
Limitations of the system
68
 
=========================
 
15
    $ bzr commit --fixes lp:12345 -m "Properly close the connection"
 
16
 
 
17
This records metadata in Bazaar linking the commit with bug 12345 in
 
18
Launchpad. If you use a different bug tracker, it can be given its own
 
19
tracker code (instead of ``lp``) and used instead. For details on how
 
20
to configure this for Bugzilla, Trac, Roundup and other bug/issue trackers,
 
21
refer to `Bug Tracker Settings`_ in the Bazaar User Reference.
 
22
 
 
23
.. _Bug Tracker Settings: ../user-reference/index.html#bug-tracker-settings
 
24
 
 
25
Metadata recording vs bug tracker updating
 
26
------------------------------------------
 
27
 
 
28
Recording metadata about bugs fixed at commit time is only
 
29
one of the features needed for complete bug tracker integration.
 
30
As Bazaar is a distributed VCS, users may be offline while committing
 
31
so accessing the bug tracker itself at that time may not be possible.
 
32
Instead, it is recommended that a hook be installed to update
 
33
the bug tracker when changes are pushed to a central location
 
34
appropriate for your project's workflow.
 
35
 
 
36
Note: This second processing stage is part of the integration provided
 
37
by Launchpad when it scans external or hosted branches.
 
38
 
 
39
Making corrections
 
40
------------------
69
41
 
70
42
This method of associating revisions and bugs does have some limitations. The
71
43
first is that the association can only be made at commit time. This means that
72
44
if you forget to make the association when you commit, or the bug is reported
73
 
after you fix it you cannot go back and add the link later.
 
45
after you fix it, you generally cannot go back and add the link later.
74
46
 
75
47
Related to this is the fact that the association is immutable. If a bug is
76
 
marked as fixed by one commit, but that revision does not fully solve the
77
 
bug, or there is a later regression you cannot go back and remove the link.
78
 
 
 
48
marked as fixed by one commit but that revision does not fully solve the
 
49
bug, or there is a later regression, you cannot go back and remove the link.
 
50
 
 
51
Of course, ``bzr uncommit`` can always be used to undo the last commit in
 
52
order to make it again with the correct options. This is commonly done
 
53
to correct a bad commit message and it equally applies to correcting
 
54
metadata recorded (via ``--fixes`` for example) on the last commit.
 
55
 
 
56
Note: ``uncommit`` is best done before incorrect revisions become public.