~bzr-pqm/bzr/bzr.dev

3416.1.1 by Ian Clatworthy
new structure and initial content for closing chapters
1
Bug trackers
2
============
2601.1.1 by James Westby
Split out bug tracker configuration in to its own file.
3
4
Bazaar has a facility that allows you to associate a commit with a bug
3053.8.1 by Ian Clatworthy
Improve bug tracker integration documentation (Ian Clatworthy)
5
in the project's bug tracker. Other tools (or hooks) can then use this
3154.1.1 by Ian Clatworthy
Minor tweaks to bug tracker integration documentation
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.
2601.1.1 by James Westby
Split out bug tracker configuration in to its own file.
8
2977.1.1 by Ian Clatworthy
First cut at new look User Guide including chapters 1 and 2
9
Associating commits and bugs
10
----------------------------
2601.1.1 by James Westby
Split out bug tracker configuration in to its own file.
11
3053.8.1 by Ian Clatworthy
Improve bug tracker integration documentation (Ian Clatworthy)
12
When you make a commit, you can associate it with a bug by using the
2601.1.1 by James Westby
Split out bug tracker configuration in to its own file.
13
``--fixes`` option of ``commit``. For example::
14
3053.8.1 by Ian Clatworthy
Improve bug tracker integration documentation (Ian Clatworthy)
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
3423.1.3 by Ian Clatworthy
incorporate feedback from Neil Martinsen-Burrell
20
to configure this for Bugzilla, Trac, Roundup and other bug/issue trackers,
21
refer to `Bug Tracker Settings`_ in the Bazaar User Reference.
3053.8.1 by Ian Clatworthy
Improve bug tracker integration documentation (Ian Clatworthy)
22
4634.164.2 by Alexander Belchenko
change links to user-reference/bzr_man.html to user-reference/index.html everywhere in the User Guide.
23
.. _Bug Tracker Settings: ../user-reference/index.html#bug-tracker-settings
3053.8.1 by Ian Clatworthy
Improve bug tracker integration documentation (Ian Clatworthy)
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
3154.1.1 by Ian Clatworthy
Minor tweaks to bug tracker integration documentation
37
by Launchpad when it scans external or hosted branches.
3053.8.1 by Ian Clatworthy
Improve bug tracker integration documentation (Ian Clatworthy)
38
39
Making corrections
40
------------------
2601.1.1 by James Westby
Split out bug tracker configuration in to its own file.
41
42
This method of associating revisions and bugs does have some limitations. The
43
first is that the association can only be made at commit time. This means that
44
if you forget to make the association when you commit, or the bug is reported
3053.8.1 by Ian Clatworthy
Improve bug tracker integration documentation (Ian Clatworthy)
45
after you fix it, you generally cannot go back and add the link later.
2601.1.1 by James Westby
Split out bug tracker configuration in to its own file.
46
47
Related to this is the fact that the association is immutable. If a bug is
3053.8.1 by Ian Clatworthy
Improve bug tracker integration documentation (Ian Clatworthy)
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.
2601.1.1 by James Westby
Split out bug tracker configuration in to its own file.
50
3053.8.1 by Ian Clatworthy
Improve bug tracker integration documentation (Ian Clatworthy)
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.
3154.1.1 by Ian Clatworthy
Minor tweaks to bug tracker integration documentation
55
56
Note: ``uncommit`` is best done before incorrect revisions become public.