If you are using a bug tracker in your project, you can link Bazaar commits to bug reports. When a commit is linked to a bug report, you will be able to:
- See the bug report's URL in the output of
bzr log - Have a clickable hyperlink to the bug report when viewing the revision history using Bazaar Explorer
- Depending upon the bug tracker, you may be able to see the details of the linked commits on the bug report's page
In order to link commits to bugs, you must do two things:
- Edit the branch configuration to set the bug tracker.
- Specify the bug ID using the
--fixesflag when committing revisions.
Depending upon the bug tracker, the configuration is slightly different. Here, we will demonstrate how to link to bugs on Launchpad, Bugzilla, Redmine, and Trac. If you use a different bug tracker, then these examples may help you figure out the right steps.
When viewing the revision history by using bzr log, linked bugs appear as follows:
$ bzr log --short --limit 1 9 mike 2012-10-17 fixes bug: https://launchpad.net/bugs/1067609 added c++ impl
Notice the fixes bug line with the URL of the bug report on Launchpad. This revision was committed by using the --fixes lp:1067609 option. Linked bug reports are shown only in the short and long formats of the log command, not in the single-line format.
When viewing the revision history using Bazaar Explorer, the revisions associated with bug reports are highlighted with the bug's ID, and the bug's URL is shown in the commit's details. You can click on the highlighted label of the linked bug to open the bug report in a browser:
Bug trackers can be configured globally or per branch. A bug tracker configuration in Bazaar typically has two important pieces of information:
- A short ID to identify the bug tracker
- The parameterized URL of the tracker
The tracker ID is used when linking to a bug report with the --fixes flag of the commit command. For example:
$ bzr commit -m 'added c++ impl' --fixes lp:1067609 Committing to: /sandbox/integration/mike/ added hello.cpp Committed revision 9.
The parameter --fixes is in the format TRACKERID:BUGID;in this case, the tracker ID is lp, which Bazaar automatically associates with Launchpad. The bug ID is, of course, the ID of the bug in the bug tracking system; in this case on Launchpad.
The general format of a bug tracker configuration looks similar to the following:
bugtracker_TRACKERID_url = URL/{id}Here:
TRACKERIDis your choice of a short name to identify the bug trackerURLis the URL template of bug report pages{id}is what Bazaar will substitute with the bug's ID when constructing the bug's URL to display in the revision history
For example:
bugtracker_redmine1_url = http://example.com/redmine/issues/{id}This configuration identifies a bug tracker named redmine1, so that if you create a commit as follows:
$ bzr commit -m 'test commit' --fixes redmine1:123
Then the bug report's link will be shown in the revision history as follows:
$ bzr log -l1 -S 10 Janos Gyerik 2012-10-17 fixes bug: http://example.com/redmine/issues/123 test commit
Bug tracker configurations can be added at different places:
~/.bazaar/bazaar.conf: This is the global configuration file, add your change in the[DEFAULT]section.bzr/branch/branch.conf: This is the configuration file of the branch~/.bazaar/locations.conf: This is the global configuration file of repository locations
To test a bug tracker configuration, try to do a test commit in a test branch by using the new tracker ID. The commit operation will fail if there is a problem in the configuration. For example:
$ bzr commit -m 'test commit' --fixes myNonExistent:123 bzr: ERROR: Unrecognized bug myNonExistent:123. Commit refused.
Bazaar has additional support for famous public bug trackers in order to simplify the configuration:
|
URL |
Tracker ID |
Example |
|---|---|---|
|
|
| |
|
|
| |
|
|
|
You can use these trackers without any additional configuration.
In projects hosted on Launchpad you can use the lp tracker without any additional configuration.
Using Launchpad has some additional benefits. For example, after you push a branch containing references to bugs on Launchpad, the referenced bug report pages will have a new section titled Related branches, where the branches will be listed. Similarly, on the branch details page, links to the bug reports will be added automatically in the Related bugs section.
You can also manually link branches to bugs, by using the Link a bug report link in the Related bugs section. Linking branches to bug reports is very convenient because the branch details page will show all the linked bugs with their statuses and importance.
Bazaar has additional support for Bugzilla in order to simplify the configuration:
bugzilla_TRACKER_url = URL
That is, you don't need the {id} parameter. The URL should be the base URL of the project in Bugzilla. For example:
bugzilla_mybugz_url = http://example.com/
In this way, the bug report URLs will be generated in the following format:
http://example.com/show_bug.cgi?id=123
Bazaar provides additional support for Trac in order to simplify the configuration:
trac_TRACKER_url = URL
That is, you don't need the {id} parameter. The URL should be the base URL of the project environment in Trac. For example:
trac_mytrac_url = http://example.com/trac
In this way, the bug report URLs will be generated in the following format:
http://example.com/trac/ticket/123
To link to other bug trackers, you must use the format with the generic prefix bugtracker_ as the configuration name, and the {id} parameter in the URL. For example:
bugtracker_redmine1_url = http://example.com/redmine/issues/{id}See bzr help bugs for more details.
In this section, we focused mainly on linking Bazaar commits to bug trackers, so that you can easily open bug reports from Bazaar Explorer, or by using the links in the output of bzr log.
Depending upon the bug tracker, sometimes the reverse is also possible, and the bug tracker can link back to Bazaar branches, showing details about the commits related to bugs, similar to what Launchpad does.
One such example is bugzilla-vcs, an extension of Bugzilla that provides integration with Bazaar and other version control systems. For more details, see their project website:
https://code.google.com/p/bugzilla-vcs/
Other bug trackers may also have the extension to provide a similar functionality.