| blob | 3ec3e24ec0f7acf1b4ab9de9f0f5c7354ba49a24 |
1 <?xml version="1.0" encoding="UTF-8"?>\r
2 <!DOCTYPE sect1 SYSTEM "../../../dtd/dblite.dtd">\r
3 <sect1 id="tsvn-dug-bugtracker">\r
4 <title>Integration with Bug Tracking Systems / Issue Trackers</title>\r
5 <indexterm>\r
6 <primary>bug tracking</primary>\r
7 </indexterm>\r
8 <indexterm>\r
9 <primary>bug tracker</primary>\r
10 </indexterm>\r
11 <indexterm>\r
12 <primary>issue tracker</primary>\r
13 </indexterm>\r
14 <indexterm>\r
15 <primary>bugtracker</primary>\r
16 </indexterm>\r
17 <para>\r
18 It is very common in Software Development for changes to be related to a specific\r
19 bug or issue ID. Users of bug tracking systems (issue trackers) would like to associate\r
20 the changes they make in Git with a specific ID in their issue tracker.\r
21 Most issue trackers therefore provide a pre-commit hook script which parses the log\r
22 message to find the bug ID with which the commit is associated.\r
23 This is somewhat error prone since it relies on the user to write the log message\r
24 properly so that the pre-commit hook script can parse it correctly.\r
25 </para>\r
26 <para>\r
27 TortoiseGit can help the user in two ways:\r
28 <orderedlist>\r
29 <listitem>\r
30 <para>\r
31 When the user enters a log message, a well defined line including\r
32 the issue number associated with the commit can be added automatically.\r
33 This reduces the risk that the user enters the issue number in a way\r
34 the bug tracking tools can't parse correctly.\r
35 </para>\r
36 <para>\r
37 Or TortoiseGit can highlight the part of\r
38 the entered log message which is recognized by the issue tracker.\r
39 That way the user knows that the log message can be parsed correctly.\r
40 </para>\r
41 </listitem>\r
42 <listitem>\r
43 <para>\r
44 When the user browses the log messages, TortoiseGit\r
45 creates a link out of each bug ID in the log message which fires\r
46 up the browser to the issue mentioned.\r
47 </para>\r
48 </listitem>\r
49 </orderedlist>\r
50 </para>\r
51 <sect2 id="tsvn-dug-bugtracker-link">\r
52 <title>Adding Issue Numbers to Log Messages</title>\r
53 <para>\r
54 You can integrate a bug tracking tool of your choice in\r
55 TortoiseGit. To do this, you have to define\r
56 some configuration, which start with <literal>bugtraq.</literal>.\r
57 <xref linkend="tsvn-setting-bugtraq"/>)\r
58 </para>\r
59 <para>\r
60 There are two ways to integrate TortoiseGit with issue trackers. One is\r
61 based on simple strings, the other is based on\r
62 <emphasis>regular expressions</emphasis>.\r
63 The configuration used by both approaches are:\r
64 <variablelist>\r
65 <varlistentry>\r
66 <term condition="pot">bugtraq.url</term>\r
67 <listitem>\r
68 <para>\r
69 Set this configuration to the URL of your bug tracking tool.\r
70 It must be properly URI encoded and it has to contain\r
71 <literal>%BUGID%</literal>.\r
72 <literal>%BUGID%</literal> is replaced with the Issue number\r
73 you entered. This allows TortoiseGit\r
74 to display a link in the log dialog, so when you are looking\r
75 at the revision log you can jump directly to your\r
76 bug tracking tool.\r
77 You do not have to provide this configuration, but then\r
78 TortoiseGit shows only the\r
79 issue number and not the link to it.\r
80 e.g the TortoiseGit project is using\r
81 <systemitem class="url">http://code.google.com/p/tortoisegit/issues/detail?id=%BUGID%</systemitem>\r
82 </para>\r
83 <para>\r
84 You can also use relative URLs instead of absolute ones. This is\r
85 useful when your issue tracker is on the same domain/server\r
86 as your source repository. In case the domain name ever changes,\r
87 you don't have to adjust the <literal>bugtraq.url</literal> configuration.\r
88 There are two ways to specify a relative URL:\r
89 </para>\r
90 <!--\r
91 <para>\r
92 If it begins with the string <literal>^/</literal> it is assumed\r
93 to be relative to the repository root.\r
94 For example, <literal>^/../?do=details&id=%BUGID%</literal>\r
95 will resolve to\r
96 <systemitem class="url">http://TortoiseGit.net/?do=details&id=%BUGID%</systemitem>\r
97 if your repository is located on\r
98 <systemitem class="url">http://TortoiseGit.net/svn/trunk/</systemitem>.\r
99 </para>\r
100 -->\r
101 <para>\r
102 A URL beginning with the string <literal>/</literal> is assumed\r
103 to be relative to the server's hostname.\r
104 For example <literal>/?do=details&id=%BUGID%</literal>\r
105 will resolve to\r
106 <systemitem class="url">http://TortoiseGit.net/?do=details&id=%BUGID%</systemitem>\r
107 if your repository is located anywhere on\r
108 <systemitem class="url">http://TortoiseGit.net</systemitem>.\r
109 </para>\r
110 </listitem>\r
111 </varlistentry>\r
112 <varlistentry>\r
113 <term condition="pot">bugtraq.warnifnoissue</term>\r
114 <listitem>\r
115 <para>\r
116 Set this to <literal>true</literal>, if you want\r
117 TortoiseGit to warn you\r
118 because of an empty issue-number text field. Valid values \r
119 are <literal>true/false</literal>.\r
120 <emphasis>\r
121 If not defined, <literal>false</literal> is assumed.\r
122 </emphasis>\r
123 </para>\r
124 </listitem>\r
125 </varlistentry>\r
126 </variablelist>\r
127 </para>\r
128 <sect3 id="tsvn-dug-bugtracker-link-simple">\r
129 <title>Issue Number in Text Box</title>\r
130 <para>\r
131 In the simple approach, TortoiseGit shows the user a separate\r
132 input field where a bug ID can be entered. Then a separate line\r
133 is appended/prepended to the log message the user entered.\r
134 <variablelist>\r
135 <varlistentry>\r
136 <term condition="pot">bugtraq.message</term>\r
137 <listitem>\r
138 <para>\r
139 This configuration activates the bug tracking system\r
140 in <emphasis>Input field</emphasis> mode.\r
141 If this configuration is set, then TortoiseGit\r
142 will prompt you to enter an issue number when you commit\r
143 your changes. It's used to add a line at the end of the\r
144 log message. It must contain\r
145 <literal>%BUGID%</literal>, which is replaced with the\r
146 issue number on commit. This ensures that your commit log\r
147 contains a reference to the issue number which is always\r
148 in a consistent format and can be parsed by your\r
149 bug tracking tool to associate the issue number with a\r
150 particular commit. As an example you might use\r
151 <literal>Issue : %BUGID%</literal>, \r
152 but this depends on your Tool.\r
153 </para>\r
154 </listitem>\r
155 </varlistentry>\r
156 <varlistentry>\r
157 <term condition="pot">bugtraq.append</term>\r
158 <listitem>\r
159 <para>\r
160 This configuration defines if the bug-ID is appended (true)\r
161 to the end of the log message or inserted (false) at the\r
162 start of the log message. Valid values are\r
163 <literal>true/false</literal>.\r
164 <emphasis>\r
165 If not defined, <literal>true</literal> is assumed,\r
166 so that existing projects don't break.\r
167 </emphasis>\r
168 </para>\r
169 </listitem>\r
170 </varlistentry>\r
171 <varlistentry>\r
172 <term condition="pot">bugtraq.label</term>\r
173 <listitem>\r
174 <para>\r
175 This text is shown by TortoiseGit\r
176 on the commit dialog to label the edit box where you enter\r
177 the issue number. If it's not set,\r
178 <literal>Bug-ID / Issue-Nr:</literal> will be displayed.\r
179 Keep in mind though that the window will not be resized\r
180 to fit this label, so keep the size of the label below\r
181 20-25 characters. \r
182 </para>\r
183 </listitem>\r
184 </varlistentry>\r
185 <varlistentry>\r
186 <term condition="pot">bugtraq.number</term>\r
187 <listitem>\r
188 <para>\r
189 If set to <literal>true</literal> only numbers are allowed\r
190 in the issue-number text field.\r
191 An exception is the comma, so you can comma separate several\r
192 numbers. Valid values are <literal>true/false</literal>. \r
193 <emphasis>\r
194 If not defined, <literal>true</literal> is assumed.\r
195 </emphasis>\r
196 </para>\r
197 </listitem>\r
198 </varlistentry>\r
199 </variablelist>\r
200 </para>\r
201 </sect3>\r
202 <sect3 id="tsvn-dug-bugtracker-link-regex">\r
203 <title>Issue Numbers Using Regular Expressions</title>\r
204 <para>\r
205 In the approach with <emphasis>regular expressions</emphasis>, TortoiseGit\r
206 doesn't show a separate input field but marks the part of the log message\r
207 the user enters which is recognized by the issue tracker. This is done while\r
208 the user writes the log message. This also means that the bug ID can be\r
209 anywhere inside a log message! This method is much more flexible, and is\r
210 the one used by the TortoiseGit project itself.\r
211 <variablelist>\r
212 <varlistentry>\r
213 <term condition="pot">bugtraq.logregex</term>\r
214 <listitem>\r
215 <para>\r
216 This configuration activates the bug tracking system\r
217 in <emphasis>Regex</emphasis> mode.\r
218 It contains either a single regular expressions,\r
219 or two regular expressions separated by a newline.\r
220 </para>\r
221 <para>\r
222 If two expressions are set, then the first expression is used as\r
223 a pre-filter to find expressions which contain bug IDs. The\r
224 second expression then extracts the bare bug IDs from the\r
225 result of the first regex. This allows you to use a list\r
226 of bug IDs and natural language expressions if you wish.\r
227 e.g. you might fix several bugs and include a string something\r
228 like this:\r
229 <quote>This change resolves issues #23, #24 and #25</quote>\r
230 </para>\r
231 <para>\r
232 If you want to catch bug IDs as used in the expression above\r
233 inside a log message, you could use the following regex strings,\r
234 which are the ones used by the TortoiseGit project:\r
235 <literal>[Ii]ssues?:?(\s*(,|and)?\s*#\d+)+</literal> and\r
236 <literal>(\d+)</literal>\r
237 </para>\r
238 <para>\r
239 The first expression picks out <quote>issues #23, #24 and #25</quote>\r
240 from the surrounding log message.\r
241 The second regex extracts plain decimal numbers from the output\r
242 of the first regex, so it will return <quote>23</quote>, <quote>24</quote>\r
243 and <quote>25</quote> to use as bug IDs.\r
244 </para>\r
245 <para>\r
246 Breaking the first regex down a little, it must start with\r
247 the word <quote>issue</quote>, possibly capitalised.\r
248 This is optionally followed by an <quote>s</quote> (more than one\r
249 issue) and optionally a colon. This is followed by one or more\r
250 groups each having zero or more leading whitespace, an optional\r
251 comma or <quote>and</quote> and more optional space. Finally there\r
252 is a mandatory <quote>#</quote> and a mandatory decimal number.\r
253 </para>\r
254 <para>\r
255 If only one expression is set, then the bare bug IDs must be\r
256 matched in the groups of the regex string. Example:\r
257 <literal>[Ii]ssue(?:s)? #?(\d+)</literal>\r
258 This method is required by a few issue trackers, e.g. trac,\r
259 but it is harder to construct the regex. We recommend that you\r
260 only use this method if your issue tracker documentation\r
261 tells you to.\r
262 </para>\r
263 <para>\r
264 If you are unfamiliar with regular expressions, take a look at\r
265 the introduction at\r
266 <ulink url="http://en.wikipedia.org/wiki/Regular_expression">\r
267 <citetitle>http://en.wikipedia.org/wiki/Regular_expression</citetitle>\r
268 </ulink>,\r
269 and the online documentation and tutorial at\r
270 <ulink url="http://www.regular-expressions.info/">\r
271 <citetitle>http://www.regular-expressions.info/</citetitle>\r
272 </ulink>.\r
273 </para>\r
274 </listitem>\r
275 </varlistentry>\r
276 </variablelist>\r
277 </para>\r
278 </sect3>\r
279 <para>\r
280 If both the <literal>bugtraq:message</literal> and <literal>bugtraq:logregex</literal>\r
281 properties are set, <literal>logregex</literal> takes precedence.\r
282 </para>\r
283 <tip>\r
284 <para>\r
285 Even if you don't have an issue tracker with a pre-commit hook parsing your\r
286 log messages, you still can use this to turn the issues mentioned in your\r
287 log messages into links!\r
288 </para>\r
289 <para>\r
290 And even if you don't need the links, the issue numbers show up as a\r
291 separate column in the log dialog, making it easier to find the changes\r
292 which relate to a particular issue.\r
293 </para>\r
294 </tip>\r
295 <para>\r
296 Some <literal>tsvn:</literal> properties require a\r
297 <literal>true/false</literal> value. TortoiseGit also understands\r
298 <literal>yes</literal> as a synonym for <literal>true</literal> and\r
299 <literal>no</literal> as a synonym for <literal>false</literal>.\r
300 </para>\r
301 <important>\r
302 <title>Set the Properties on Folders</title>\r
303 <para>\r
304 These properties must be set on folders for the system to work. \r
305 When you commit a file or folder the properties are read from that folder.\r
306 If the properties are not found there, TortoiseGit will search upwards\r
307 through the folder tree to find them until it comes to an unversioned\r
308 folder, or the tree root (eg. <literal>C:\</literal>) is found.\r
309 If you can be sure that each user checks out only from e.g\r
310 <filename>trunk/</filename> and not some sub-folder, then it's enough if\r
311 you set the properties on <filename>trunk/</filename>.\r
312 If you can't be sure, you should set the properties recursively\r
313 on each sub-folder.\r
314 A configuration setting deeper in the project hierarchy overrides settings on\r
315 higher levels (closer to <filename>trunk/</filename>).\r
316 </para>\r
317 <para>\r
318 For <literal>tsvn:</literal> properties <emphasis>only</emphasis>\r
319 you can use the <guilabel>Recursive</guilabel> checkbox to set\r
320 the configuration to all sub-folders in the hierarchy, without also\r
321 setting it on all files.\r
322 </para>\r
323 </important>\r
324 <tip>\r
325 <title>No Issue Tracker Information from Repository Browser</title>\r
326 <para>\r
327 Because the issue tracker integration depends upon accessing Git\r
328 properties, you will only see the results when using a checked\r
329 out working tree. Fetching properties remotely is a slow operation,\r
330 so you will not see this feature in action from the repo browser.\r
331 </para>\r
332 </tip>\r
333 <para>\r
334 This issue tracker integration is not restricted to TortoiseGit; it can be used\r
335 with any Git client. For more information, read the full\r
336 <ulink url="http://TortoiseSVN.tigris.org/svn/TortoiseSVn/trunk/doc/issuetrackers.txt">\r
337 <citetitle>Issue Tracker Integration Specification</citetitle>\r
338 </ulink>\r
339 in the TortoiseGit source repository.\r
340 (<xref linkend="tsvn-preface-source"/> explains how to access the repository).\r
341 </para>\r
342 </sect2>\r
343 <sect2 id="tsvn-dug-bugtracker-ref">\r
344 <title>Getting Information from the Issue Tracker</title>\r
345 <para>\r
346 The previous section deals with adding issue information to the\r
347 log messages. But what if you need to get information from the issue\r
348 tracker? The commit dialog has a Windows COM interface which allows\r
349 integration an external program that can talk to your tracker.\r
350 Typically you might want to query the tracker to get a list of\r
351 open issues assigned to you, so that you can pick the issues that\r
352 are being addressed in this commit.\r
353 </para>\r
354 <para>\r
355 Any such interface is of course highly specific to your system,\r
356 so we cannot provide this part, and describing how to create such a\r
357 program is beyond the scope of this manual. The interface definition\r
358 and sample programs can be obtained from the <literal>contrib</literal>\r
359 folder in the\r
360 <ulink url="http://TortoiseSVN.tigris.org/svn/TortoiseSVN/trunk/contrib/issue-tracker-plugins">\r
361 <citetitle>TortoiseGit repository</citetitle>\r
362 </ulink>.\r
363 (<xref linkend="tsvn-preface-source"/> explains how to access the repository).\r
364 A summary of the API is also given in <xref linkend="tsvn-ibugtraqprovider"/>\r
365 \r
366 Another (working) example plugin in C# is \r
367 <ulink url="http://code.google.com/p/gurtle/">\r
368 <citetitle>Gurtle</citetitle>\r
369 </ulink>\r
370 which implements the required COM interface to interact with the \r
371 <ulink url="http://code.google.com/hosting/">\r
372 <citetitle>Google Code</citetitle>\r
373 </ulink>\r
374 issue tracker.\r
375 </para>\r
376 <para>\r
377 For illustration purposes, let's suppose that your system administrator\r
378 has provided you with an issue tracker plugin which you have installed,\r
379 and that you have set up some of your working trees to use the plugin\r
380 in TortoiseGit's settings dialog.\r
381 When you open the commit dialog from a working tree to which the plugin\r
382 has been assigned, you will see a new button at the top of the dialog.\r
383 <figure id="tsvn-dug-bugtracker-dia-1">\r
384 <title>Example issue tracker query dialog</title>\r
385 <graphic fileref="../images/IssueTrackerQuery.png"/>\r
386 </figure>\r
387 In this example you can select one or more open issues. The plugin\r
388 can then generate specially formatted text which it adds to your log\r
389 message.\r
390 </para>\r
391 </sect2>\r
392 </sect1>\r