[MERGE] [1.0] [#175764] Improve bug tracker integration documentation

Aaron Bentley aaron.bentley at utoronto.ca
Fri Dec 14 16:26:41 GMT 2007


-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

bb:resubmit

Ian Clatworthy wrote:
> === modified file 'bzrlib/bugtracker.py'
> --- bzrlib/bugtracker.py	2007-11-27 19:27:40 +0000
> +++ bzrlib/bugtracker.py	2007-12-12 03:17:35 +0000
> @@ -39,6 +39,71 @@
>  """
>  
>  
> +_bugs_help = \
> +"""When making a commit, metadata about bugs fixed by that change can be
> +recorded by using the --fixes option. For each bug marked as fixed, an
> +entry is included in the 'bugs' revision property stating '<url> <status>'.

I've looked for documentation of the valid statuses and come up empty.
Would be nice to have some, one of these days.

> +In addition to Launchpad, Bazaar directly supports the generation of
> +URLs appropriate for Bugzilla and Trac. If your project uses a different
> +bug tracker, it is easy to add support for it by writing a plugin, say.

^^^ I think the first suggestion should be to use the bugtracker_foo_url
format, not writing a plugin.

> +bugzilla_<tracker_abbreviation>_url
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +If present, the location of the Bugzilla bug tracker referred to by
> +<tracker_abbreviation>.

Why would it not be present?

> This option can then be used together with ``bzr commit
> +--fixes`` to mark bugs in that tracker as being fixed by that commit. For
> +example::
> +
> +    bugzilla_squid_url = http://www.squid-cache.org/bugs
> +
> +would allow ``bzr commit --fixes squid:1234`` to mark Squid's bug 1234 as
> +fixed.

^^^ This bit is repeated for all three URL types.  Can't we unify this
something like:

After you have configured your bugtracker URL, you can use ``bzr commit
- --fixes mytracker:1234`` to mark bug 1234 in that tracker as being fixed
by that commit.


> === modified file 'bzrlib/help_topics.py'
> --- bzrlib/help_topics.py	2007-12-07 03:30:29 +0000
> +++ bzrlib/help_topics.py	2007-12-12 03:17:35 +0000
> @@ -600,8 +600,9 @@
>                          "Help on status flags")
>  def get_bugs_topic(topic):
>      from bzrlib import bugtracker
> -    return "Bug Trackers\n\n" + bugtracker.tracker_registry.help_topic(topic)
> -topic_registry.register('bugs', get_bugs_topic, 'Bug tracker support')
> +    return "Bug Tracker Settings\n\n" + \
> +        bugtracker.tracker_registry.help_topic(topic)

Using parentheses is preferred over line continuation markers, e.g.

    return ("Bug Tracker Settings\n\n" +
            bugtracker.tracker_registry.help_topic(topic))

> === modified file 'doc/en/user-guide/bug_trackers.txt'
> --- doc/en/user-guide/bug_trackers.txt	2007-12-04 18:11:51 +0000
> +++ doc/en/user-guide/bug_trackers.txt	2007-12-12 03:17:35 +0000
> @@ -2,95 +2,53 @@
>  ====================================
>  
>  Bazaar has a facility that allows you to associate a commit with a bug
> -in the project's bug tracker. Other tools can then use this information
> -to link between the commit and the bug, or to automatically mark the bug
> -closed in the branches that contain the commit.
> +in the project's bug tracker. Other tools (or hooks) can then use this
> +information to link between the commit and the bug, or to automatically

^^^ "link between" seems like an odd usage.  We usually "link x and y"
or "link x to y", or even "link x with y". Maybe "generate hyperlinks
between...", if that's the intent.

> +Of course, ``bzr uncommit`` can always be used to undo the last commit in
> +order to make it again with the correct options.

^^^ probably should mention that uncommit works best before the revision
becomes public.

Aaron
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.6 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iD8DBQFHYq7B0F+nu1YWqI0RAmzoAJ0dY0myix6cxRrZ3d9wT5Hm9ABk4wCcCNf8
dgRxPQQgp15FNp3FsJ2iMd4=
=DNqO
-----END PGP SIGNATURE-----



More information about the bazaar mailing list