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