2376.4.4
by jml at canonical
Beginnings of generic bug-tracker plugin system. |
1 |
# Copyright (C) 2007 Canonical Ltd
|
2 |
#
|
|
3 |
# This program is free software; you can redistribute it and/or modify
|
|
4 |
# it under the terms of the GNU General Public License as published by
|
|
5 |
# the Free Software Foundation; either version 2 of the License, or
|
|
6 |
# (at your option) any later version.
|
|
7 |
#
|
|
8 |
# This program is distributed in the hope that it will be useful,
|
|
9 |
# but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
10 |
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
11 |
# GNU General Public License for more details.
|
|
12 |
#
|
|
13 |
# You should have received a copy of the GNU General Public License
|
|
14 |
# along with this program; if not, write to the Free Software
|
|
4183.7.1
by Sabin Iacob
update FSF mailing address |
15 |
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
|
2376.4.4
by jml at canonical
Beginnings of generic bug-tracker plugin system. |
16 |
|
2376.4.36
by Jonathan Lange
Provide really basic help topic for our bug tracker support. |
17 |
from bzrlib import registry, help_topics |
2376.4.6
by jml at canonical
Basic docstrings for bugtracker.py |
18 |
from bzrlib.lazy_import import lazy_import |
19 |
lazy_import(globals(), """ |
|
2376.4.17
by Jonathan Lange
Use urlutils.join instead of ugly, buggy, string mashing |
20 |
from bzrlib import errors, urlutils
|
2376.4.6
by jml at canonical
Basic docstrings for bugtracker.py |
21 |
""") |
2376.4.4
by jml at canonical
Beginnings of generic bug-tracker plugin system. |
22 |
|
23 |
||
2376.4.7
by jml at canonical
- Add docstrings to tests. |
24 |
"""Provides a shorthand for referring to bugs on a variety of bug trackers.
|
25 |
||
26 |
'commit --fixes' stores references to bugs as a <bug_url> -> <bug_status>
|
|
27 |
mapping in the properties for that revision.
|
|
28 |
||
29 |
However, it's inconvenient to type out full URLs for bugs on the command line,
|
|
30 |
particularly given that many users will be using only a single bug tracker per
|
|
31 |
branch.
|
|
32 |
||
33 |
Thus, this module provides a registry of types of bug tracker (e.g. Launchpad,
|
|
2376.4.23
by Jonathan Lange
Change 'tag' to 'abbreviated_tracker_name' |
34 |
Trac). Given an abbreviated name (e.g. 'lp', 'twisted') and a branch with
|
2376.4.7
by jml at canonical
- Add docstrings to tests. |
35 |
configuration information, these tracker types can return an instance capable
|
36 |
of converting bug IDs into URLs.
|
|
37 |
"""
|
|
38 |
||
39 |
||
3053.8.1
by Ian Clatworthy
Improve bug tracker integration documentation (Ian Clatworthy) |
40 |
_bugs_help = \ |
41 |
"""When making a commit, metadata about bugs fixed by that change can be
|
|
4927.2.6
by Ian Clatworthy
Nicer formatting of bug tracking topic |
42 |
recorded by using the ``--fixes`` option. For each bug marked as fixed, an
|
3053.8.1
by Ian Clatworthy
Improve bug tracker integration documentation (Ian Clatworthy) |
43 |
entry is included in the 'bugs' revision property stating '<url> <status>'.
|
3154.1.1
by Ian Clatworthy
Minor tweaks to bug tracker integration documentation |
44 |
(The only ``status`` value currently supported is ``fixed.``)
|
3535.10.2
by James Westby
Flesh out the bugs help topic and explain the simple things first. |
45 |
|
4927.2.6
by Ian Clatworthy
Nicer formatting of bug tracking topic |
46 |
The ``--fixes`` option allows you to specify a bug tracker and a bug identifier
|
47 |
rather than a full URL. This looks like::
|
|
3535.10.2
by James Westby
Flesh out the bugs help topic and explain the simple things first. |
48 |
|
3535.10.3
by James Westby
Talk about "trackers" rather than "tags" as it may be less confusing. |
49 |
bzr commit --fixes <tracker>:<id>
|
3535.10.2
by James Westby
Flesh out the bugs help topic and explain the simple things first. |
50 |
|
3535.10.3
by James Westby
Talk about "trackers" rather than "tags" as it may be less confusing. |
51 |
where "<tracker>" is an identifier for the bug tracker, and "<id>" is the
|
3535.10.2
by James Westby
Flesh out the bugs help topic and explain the simple things first. |
52 |
identifier for that bug within the bugtracker, usually the bug number.
|
53 |
||
3535.10.5
by James Westby
Don't say "well-known" as suggested by Robert. |
54 |
Bazaar knows about a few bug trackers that have many users. If
|
3535.10.2
by James Westby
Flesh out the bugs help topic and explain the simple things first. |
55 |
you use one of these bug trackers then there is no setup required to
|
3535.10.3
by James Westby
Talk about "trackers" rather than "tags" as it may be less confusing. |
56 |
use this feature, you just need to know the tracker identifier to use.
|
57 |
These are the bugtrackers that are built in:
|
|
58 |
||
4927.2.6
by Ian Clatworthy
Nicer formatting of bug tracking topic |
59 |
============================ ============ ============
|
60 |
URL Abbreviation Example
|
|
61 |
============================ ============ ============
|
|
62 |
https://bugs.launchpad.net/ lp lp:12345
|
|
63 |
http://bugs.debian.org/ deb deb:12345
|
|
64 |
http://bugzilla.gnome.org/ gnome gnome:12345
|
|
65 |
============================ ============ ============
|
|
3535.10.2
by James Westby
Flesh out the bugs help topic and explain the simple things first. |
66 |
|
3535.10.5
by James Westby
Don't say "well-known" as suggested by Robert. |
67 |
For the bug trackers not listed above configuration is required.
|
68 |
Support for generating the URLs for any project using Bugzilla or Trac
|
|
69 |
is built in, along with a template mechanism for other bugtrackers with
|
|
3535.10.6
by James Westby
Mention that the a plugin can support their tracker as the last resort. |
70 |
simple URL schemes. If your bug tracker can't be described by one
|
71 |
of the schemes described below then you can write a plugin to support
|
|
72 |
it.
|
|
3535.10.2
by James Westby
Flesh out the bugs help topic and explain the simple things first. |
73 |
|
3053.8.1
by Ian Clatworthy
Improve bug tracker integration documentation (Ian Clatworthy) |
74 |
If you use Bugzilla or Trac, then you only need to set a configuration
|
75 |
variable which contains the base URL of the bug tracker. These options
|
|
76 |
can go into ``bazaar.conf``, ``branch.conf`` or into a branch-specific
|
|
77 |
configuration section in ``locations.conf``. You can set up these values
|
|
78 |
for each of the projects you work on.
|
|
79 |
||
80 |
Note: As you provide a short name for each tracker, you can specify one or
|
|
81 |
more bugs in one or more trackers at commit time if you wish.
|
|
82 |
||
3860.2.1
by Martin Pool
Mention in 'help bugs' the syntax for Launchpad |
83 |
Launchpad
|
84 |
---------
|
|
85 |
||
86 |
Use ``bzr commit --fixes lp:2`` to record that this commit fixes bug 2.
|
|
87 |
||
4927.2.6
by Ian Clatworthy
Nicer formatting of bug tracking topic |
88 |
bugzilla_<tracker>_url
|
89 |
----------------------
|
|
3053.8.1
by Ian Clatworthy
Improve bug tracker integration documentation (Ian Clatworthy) |
90 |
|
91 |
If present, the location of the Bugzilla bug tracker referred to by
|
|
4927.2.6
by Ian Clatworthy
Nicer formatting of bug tracking topic |
92 |
<tracker>. This option can then be used together with ``bzr commit
|
3053.8.1
by Ian Clatworthy
Improve bug tracker integration documentation (Ian Clatworthy) |
93 |
--fixes`` to mark bugs in that tracker as being fixed by that commit. For
|
94 |
example::
|
|
95 |
||
96 |
bugzilla_squid_url = http://www.squid-cache.org/bugs
|
|
97 |
||
98 |
would allow ``bzr commit --fixes squid:1234`` to mark Squid's bug 1234 as
|
|
99 |
fixed.
|
|
100 |
||
4927.2.6
by Ian Clatworthy
Nicer formatting of bug tracking topic |
101 |
trac_<tracker>_url
|
102 |
------------------
|
|
3053.8.1
by Ian Clatworthy
Improve bug tracker integration documentation (Ian Clatworthy) |
103 |
|
104 |
If present, the location of the Trac instance referred to by
|
|
4927.2.6
by Ian Clatworthy
Nicer formatting of bug tracking topic |
105 |
<tracker>. This option can then be used together with ``bzr commit
|
3053.8.1
by Ian Clatworthy
Improve bug tracker integration documentation (Ian Clatworthy) |
106 |
--fixes`` to mark bugs in that tracker as being fixed by that commit. For
|
107 |
example::
|
|
108 |
||
109 |
trac_twisted_url = http://www.twistedmatrix.com/trac
|
|
110 |
||
111 |
would allow ``bzr commit --fixes twisted:1234`` to mark Twisted's bug 1234 as
|
|
112 |
fixed.
|
|
113 |
||
4927.2.6
by Ian Clatworthy
Nicer formatting of bug tracking topic |
114 |
bugtracker_<tracker>_url
|
115 |
------------------------
|
|
3089.3.14
by Ian Clatworthy
follow-up tweaks to bzr.dev integration |
116 |
|
3053.8.1
by Ian Clatworthy
Improve bug tracker integration documentation (Ian Clatworthy) |
117 |
If present, the location of a generic bug tracker instance referred to by
|
4927.2.6
by Ian Clatworthy
Nicer formatting of bug tracking topic |
118 |
<tracker>. The location must contain an ``{id}`` placeholder,
|
3053.8.1
by Ian Clatworthy
Improve bug tracker integration documentation (Ian Clatworthy) |
119 |
which will be replaced by a specific bug ID. This option can then be used
|
120 |
together with ``bzr commit --fixes`` to mark bugs in that tracker as being
|
|
121 |
fixed by that commit. For example::
|
|
122 |
||
123 |
bugtracker_python_url = http://bugs.python.org/issue{id}
|
|
124 |
||
125 |
would allow ``bzr commit --fixes python:1234`` to mark bug 1234 in Python's
|
|
126 |
Roundup bug tracker as fixed, or::
|
|
127 |
||
128 |
bugtracker_cpan_url = http://rt.cpan.org/Public/Bug/Display.html?id={id}
|
|
129 |
||
130 |
for CPAN's RT bug tracker.
|
|
131 |
"""
|
|
132 |
||
133 |
||
2376.4.23
by Jonathan Lange
Change 'tag' to 'abbreviated_tracker_name' |
134 |
def get_bug_url(abbreviated_bugtracker_name, branch, bug_id): |
135 |
"""Return a URL pointing to the canonical web page of the bug identified by
|
|
136 |
'bug_id'.
|
|
137 |
"""
|
|
138 |
tracker = tracker_registry.get_tracker(abbreviated_bugtracker_name, branch) |
|
139 |
return tracker.get_bug_url(bug_id) |
|
2376.4.4
by jml at canonical
Beginnings of generic bug-tracker plugin system. |
140 |
|
141 |
||
142 |
class TrackerRegistry(registry.Registry): |
|
143 |
"""Registry of bug tracker types."""
|
|
144 |
||
2376.4.23
by Jonathan Lange
Change 'tag' to 'abbreviated_tracker_name' |
145 |
def get_tracker(self, abbreviated_bugtracker_name, branch): |
146 |
"""Return the first registered tracker that understands
|
|
147 |
'abbreviated_bugtracker_name'.
|
|
2376.4.7
by jml at canonical
- Add docstrings to tests. |
148 |
|
149 |
If no such tracker is found, raise KeyError.
|
|
150 |
"""
|
|
2376.4.23
by Jonathan Lange
Change 'tag' to 'abbreviated_tracker_name' |
151 |
for tracker_name in self.keys(): |
152 |
tracker_type = self.get(tracker_name) |
|
153 |
tracker = tracker_type.get(abbreviated_bugtracker_name, branch) |
|
2376.4.4
by jml at canonical
Beginnings of generic bug-tracker plugin system. |
154 |
if tracker is not None: |
155 |
return tracker |
|
2376.4.28
by Jonathan Lange
Focus the tests better and clean up some dodgy bits in UnknownBugTrackerAbbreviation |
156 |
raise errors.UnknownBugTrackerAbbreviation(abbreviated_bugtracker_name, |
157 |
branch) |
|
2376.4.7
by jml at canonical
- Add docstrings to tests. |
158 |
|
2376.4.36
by Jonathan Lange
Provide really basic help topic for our bug tracker support. |
159 |
def help_topic(self, topic): |
3053.8.1
by Ian Clatworthy
Improve bug tracker integration documentation (Ian Clatworthy) |
160 |
return _bugs_help |
2376.4.36
by Jonathan Lange
Provide really basic help topic for our bug tracker support. |
161 |
|
2376.4.4
by jml at canonical
Beginnings of generic bug-tracker plugin system. |
162 |
|
163 |
tracker_registry = TrackerRegistry() |
|
2376.4.6
by jml at canonical
Basic docstrings for bugtracker.py |
164 |
"""Registry of bug trackers."""
|
2376.4.4
by jml at canonical
Beginnings of generic bug-tracker plugin system. |
165 |
|
2376.4.15
by Jonathan Lange
Whitespace cleanup |
166 |
|
2376.4.40
by Jonathan Lange
Redo the hierarchy of bug trackers to reduce duplication. |
167 |
class BugTracker(object): |
168 |
"""Base class for bug trackers."""
|
|
169 |
||
170 |
def check_bug_id(self, bug_id): |
|
171 |
"""Check that the bug_id is valid.
|
|
172 |
||
173 |
The base implementation assumes that all bug_ids are valid.
|
|
174 |
"""
|
|
175 |
||
176 |
def get_bug_url(self, bug_id): |
|
177 |
"""Return the URL for bug_id. Raise an error if bug ID is malformed."""
|
|
178 |
self.check_bug_id(bug_id) |
|
179 |
return self._get_bug_url(bug_id) |
|
180 |
||
181 |
def _get_bug_url(self, bug_id): |
|
182 |
"""Given a validated bug_id, return the bug's web page's URL."""
|
|
183 |
||
184 |
||
185 |
class IntegerBugTracker(BugTracker): |
|
186 |
"""A bug tracker that only allows integer bug IDs."""
|
|
187 |
||
188 |
def check_bug_id(self, bug_id): |
|
189 |
try: |
|
190 |
int(bug_id) |
|
191 |
except ValueError: |
|
192 |
raise errors.MalformedBugIdentifier(bug_id, "Must be an integer") |
|
193 |
||
194 |
||
195 |
class UniqueIntegerBugTracker(IntegerBugTracker): |
|
2376.4.19
by Jonathan Lange
Rename SimpleBugTracker to UniqueBugTracker |
196 |
"""A style of bug tracker that exists in one place only, such as Launchpad.
|
2376.4.15
by Jonathan Lange
Whitespace cleanup |
197 |
|
2376.4.41
by Jonathan Lange
Update UniqueIntegerBugTracker docstring for new API |
198 |
If you have one of these trackers then register an instance passing in an
|
3270.5.3
by James Westby
No longer add an extra class to accomoadate gnome. |
199 |
abbreviated name for the bug tracker and a base URL. The bug ids are
|
200 |
appended directly to the URL.
|
|
2376.5.1
by James Westby
Add a superclass for easy bug trackers. Also add bugs.debian.org as deb: |
201 |
"""
|
202 |
||
2376.4.25
by Jonathan Lange
Make singleton bug tracker thing work via instances. |
203 |
def __init__(self, abbreviated_bugtracker_name, base_url): |
204 |
self.abbreviation = abbreviated_bugtracker_name |
|
205 |
self.base_url = base_url |
|
206 |
||
207 |
def get(self, abbreviated_bugtracker_name, branch): |
|
2376.4.23
by Jonathan Lange
Change 'tag' to 'abbreviated_tracker_name' |
208 |
"""Returns the tracker if the abbreviation matches. Returns None
|
209 |
otherwise."""
|
|
2376.4.25
by Jonathan Lange
Make singleton bug tracker thing work via instances. |
210 |
if abbreviated_bugtracker_name != self.abbreviation: |
2376.5.1
by James Westby
Add a superclass for easy bug trackers. Also add bugs.debian.org as deb: |
211 |
return None |
2376.4.25
by Jonathan Lange
Make singleton bug tracker thing work via instances. |
212 |
return self |
2376.5.1
by James Westby
Add a superclass for easy bug trackers. Also add bugs.debian.org as deb: |
213 |
|
2376.4.40
by Jonathan Lange
Redo the hierarchy of bug trackers to reduce duplication. |
214 |
def _get_bug_url(self, bug_id): |
2376.5.1
by James Westby
Add a superclass for easy bug trackers. Also add bugs.debian.org as deb: |
215 |
"""Return the URL for bug_id."""
|
3270.5.3
by James Westby
No longer add an extra class to accomoadate gnome. |
216 |
return self.base_url + bug_id |
2376.5.1
by James Westby
Add a superclass for easy bug trackers. Also add bugs.debian.org as deb: |
217 |
|
218 |
||
2376.4.25
by Jonathan Lange
Make singleton bug tracker thing work via instances. |
219 |
tracker_registry.register( |
220 |
'launchpad', UniqueIntegerBugTracker('lp', 'https://launchpad.net/bugs/')) |
|
221 |
||
222 |
||
223 |
tracker_registry.register( |
|
2376.4.29
by Jonathan Lange
Tests for builtin trackers. |
224 |
'debian', UniqueIntegerBugTracker('deb', 'http://bugs.debian.org/')) |
2376.4.4
by jml at canonical
Beginnings of generic bug-tracker plugin system. |
225 |
|
2376.4.15
by Jonathan Lange
Whitespace cleanup |
226 |
|
3270.5.3
by James Westby
No longer add an extra class to accomoadate gnome. |
227 |
tracker_registry.register('gnome', |
228 |
UniqueIntegerBugTracker('gnome', 'http://bugzilla.gnome.org/show_bug.cgi?id=')) |
|
229 |
||
230 |
||
2376.4.40
by Jonathan Lange
Redo the hierarchy of bug trackers to reduce duplication. |
231 |
class URLParametrizedIntegerBugTracker(IntegerBugTracker): |
232 |
"""A type of bug tracker that can be found on a variety of different sites,
|
|
233 |
and thus needs to have the base URL configured.
|
|
234 |
||
235 |
Looks for a config setting in the form '<type_name>_<abbreviation>_url'.
|
|
236 |
`type_name` is the name of the type of tracker (e.g. 'bugzilla' or 'trac')
|
|
237 |
and `abbreviation` is a short name for the particular instance (e.g.
|
|
238 |
'squid' or 'apache').
|
|
239 |
"""
|
|
240 |
||
2376.4.42
by Jonathan Lange
Parametrize URLParametrizedIntegerBugTracker even further so we don't need to |
241 |
def get(self, abbreviation, branch): |
2376.4.40
by Jonathan Lange
Redo the hierarchy of bug trackers to reduce duplication. |
242 |
config = branch.get_config() |
243 |
url = config.get_user_option( |
|
2376.4.42
by Jonathan Lange
Parametrize URLParametrizedIntegerBugTracker even further so we don't need to |
244 |
"%s_%s_url" % (self.type_name, abbreviation)) |
2376.4.40
by Jonathan Lange
Redo the hierarchy of bug trackers to reduce duplication. |
245 |
if url is None: |
246 |
return None |
|
247 |
self._base_url = url |
|
2376.4.42
by Jonathan Lange
Parametrize URLParametrizedIntegerBugTracker even further so we don't need to |
248 |
return self |
249 |
||
250 |
def __init__(self, type_name, bug_area): |
|
251 |
self.type_name = type_name |
|
252 |
self._bug_area = bug_area |
|
2376.4.40
by Jonathan Lange
Redo the hierarchy of bug trackers to reduce duplication. |
253 |
|
254 |
def _get_bug_url(self, bug_id): |
|
2376.4.6
by jml at canonical
Basic docstrings for bugtracker.py |
255 |
"""Return a URL for a bug on this Trac instance."""
|
2376.4.42
by Jonathan Lange
Parametrize URLParametrizedIntegerBugTracker even further so we don't need to |
256 |
return urlutils.join(self._base_url, self._bug_area) + str(bug_id) |
257 |
||
258 |
||
259 |
tracker_registry.register( |
|
260 |
'trac', URLParametrizedIntegerBugTracker('trac', 'ticket/')) |
|
261 |
||
262 |
tracker_registry.register( |
|
263 |
'bugzilla', |
|
264 |
URLParametrizedIntegerBugTracker('bugzilla', 'show_bug.cgi?id=')) |
|
3035.3.1
by Lukáš Lalinský
Generic bug tracker configuration. |
265 |
|
266 |
||
267 |
class GenericBugTracker(URLParametrizedIntegerBugTracker): |
|
268 |
"""Generic bug tracker specified by an URL template."""
|
|
269 |
||
270 |
def __init__(self): |
|
3035.3.2
by Lukáš Lalinský
Add tests for InvalidBugTrackerURL. |
271 |
super(GenericBugTracker, self).__init__('bugtracker', None) |
272 |
||
273 |
def get(self, abbreviation, branch): |
|
274 |
self._abbreviation = abbreviation |
|
275 |
return super(GenericBugTracker, self).get(abbreviation, branch) |
|
3035.3.1
by Lukáš Lalinský
Generic bug tracker configuration. |
276 |
|
277 |
def _get_bug_url(self, bug_id): |
|
278 |
"""Given a validated bug_id, return the bug's web page's URL."""
|
|
279 |
if '{id}' not in self._base_url: |
|
280 |
raise errors.InvalidBugTrackerURL(self._abbreviation, |
|
281 |
self._base_url) |
|
282 |
return self._base_url.replace('{id}', str(bug_id)) |
|
283 |
||
284 |
||
285 |
tracker_registry.register('generic', GenericBugTracker()) |
|
4119.4.1
by Jonathan Lange
Extract bug fix encoding logic from commit. |
286 |
|
287 |
||
4119.4.2
by Jonathan Lange
Some refactoring, some unit tests. |
288 |
FIXED = 'fixed' |
289 |
||
4119.4.3
by Jonathan Lange
Add Revision.iter_bugs. |
290 |
ALLOWED_BUG_STATUSES = set([FIXED]) |
291 |
||
4119.4.2
by Jonathan Lange
Some refactoring, some unit tests. |
292 |
|
4119.4.1
by Jonathan Lange
Extract bug fix encoding logic from commit. |
293 |
def encode_fixes_bug_urls(bug_urls): |
4119.4.5
by Jonathan Lange
Fix the docstring. |
294 |
"""Get the revision property value for a commit that fixes bugs.
|
295 |
||
296 |
:param bug_urls: An iterable of escaped URLs to bugs. These normally
|
|
297 |
come from `get_bug_url`.
|
|
298 |
:return: A string that will be set as the 'bugs' property of a revision
|
|
299 |
as part of a commit.
|
|
4119.4.1
by Jonathan Lange
Extract bug fix encoding logic from commit. |
300 |
"""
|
4119.4.2
by Jonathan Lange
Some refactoring, some unit tests. |
301 |
return '\n'.join(('%s %s' % (url, FIXED)) for url in bug_urls) |