doc/issuetrackers.txt

   1 Integration of Git (GUI) clients with Bug Tracking Tools:\r
   2 ================================================================================\r
   3 \r
   4 I. Preface\r
   5 ==========\r
   6 This document is primarily intended for writers of various GUI clients for \r
   7 Git.  Clients such as TortoiseGit, TortoiseSVN, Subclipse, RapidSVN, PySVN and many \r
   8 others.\r
   9 \r
  10 The goal of this document is to outline a common technique for defining and then \r
  11 integrating these GUI clients with third party bug tracking software.  \r
  12 \r
  13 II. Introduction\r
  14 ================\r
  15 It is very common in Software Development for changes to be related to a \r
  16 specific bug or issue ID. Users of bug tracking systems would like to associate \r
  17 the changes they make in Git with a specific ID in their bug tracking \r
  18 system. There are already a number of people that have integrated these systems \r
  19 with Git. They typically rely on the end user entering a log message on \r
  20 their commits in some kind of a specific format that can be parsed with a \r
  21 commit-hook or in some cases just on-the-fly in a web-based presentation of the \r
  22 commit info. This option is OK, but it is not very user-friendly and it places \r
  23 all of the integration within the bug tracking tool. When using a Git \r
  24 client, you can see the log message info, but there is no way to jump to the bug \r
  25 system.\r
  26 \r
  27 Git (GUI) clients can help both the users and the bug tracking tools in \r
  28 that task:\r
  29 \r
  30 - When the user enters a log message, a well defined line including the issue \r
  31 number associated with the commit can be added by the client automatically. This \r
  32 reduces the risk that the users enters the issue number in a way the bug \r
  33 tracking tools can't parse correctly and therefore won't know that the commit \r
  34 was associated with a specific issue. The users won't have to remember the \r
  35 format they have to use for each log message and each individual project - the \r
  36 client will take care of that.\r
  37 \r
  38 - When the user browses the log messages, there should be an easy way to fire up \r
  39 the webbrowser to see the issue associated with that log message/commit.\r
  40 \r
  41 III. Requirements\r
  42 =================\r
  43 To make the integration with bug tracking tools possible, a Git client \r
  44 needs some information about the bug tracking tool used in a project. That \r
  45 information should be available inside the working copy so that clients don't \r
  46 have to access the repository over a possibly very slow connection to get that \r
  47 information.\r
  48 \r
  49 The information a client needs is:\r
  50 \r
  51 - the URL pointing to the bug tracking tool \r
  52 - the format of the issue number it has to add to the log messages so the \r
  53   bug tracking tool can recognize it. Or\r
  54 - a regular expression to parse the log message with to extract the issue number\r
  55 \r
  56 There are other things a Git (GUI) client could use to make the \r
  57 integration with bug tracking tools easier for the user, but these are \r
  58 essential for the integration to work.\r
  59 \r
  60 IV. Implementation\r
  61 ==================\r
  62 The required information is stored in the .git/config file.\r
  63 \r
  64 There are two different ways a client can integrate with an issue tracker. One\r
  65 is very basic but provides the user with a separate GUI to enter bug ID's,\r
  66 and the other one is based on regular expressions where the user has to enter\r
  67 the bug ID's directly into the log message.\r
  68 \r
  69 \r
  70 The following properties are defined which are used by both ways:\r
  71 \r
  72 ---------\r
  73 name  : bugtraq.url\r
  74 value : (string)\r
  75 This value is the URL pointing to the bug tracking tool. The URL string should \r
  76 contain the substring "%BUGID%" which the client replaces with the issue number. \r
  77 That way the resulting URL will point directly to the correct issue.\r
  78 NOTE: The URL must be properly URI encoded by the user.\r
  79 This URL can be used by clients to create a link to the bug tracking tool when\r
  80 showing the logmessage of a revision.\r
  81 ---------\r
  82 \r
  83 ---------\r
  84 name  : bugtraq.warnifnoissue\r
  85 value : "true"/"yes" or "false"/"no"\r
  86 If set to "true", then the clients will warn the user if the issue text box is\r
  87 left empty. But it must _not_ block the commit, only give the user a chance to\r
  88 enter an issue number in case (s)he forgot it.\r
  89 ---------\r
  90 \r
  91 Properties used with the basic integration:\r
  92 \r
  93 ---------\r
  94 name  : bugtraq.label\r
  95 value : (string)\r
  96 This can be used by a client as a GUI label describing the text box where the \r
  97 user has to enter the issue number. If this is not set, then a default value \r
  98 should be used, e.g. "Bug-ID / Issue-Number :". Keep in mind though that most \r
  99 GUI clients don't resize their windows according to the size of GUI elements. So \r
 100 keep the size of the label string below 20-25 chars.\r
 101 ---------\r
 102 \r
 103 ---------\r
 104 name  : bugtraq.message\r
 105 value : (string)\r
 106 If this property is set, then the client should show a text box in the commit \r
 107 window where the user can enter an issue number.\r
 108 \r
 109 The value string of this property is used by the client to create an additional \r
 110 line added to the log message. The string must contain the substring "%BUGID%" \r
 111 which is replaced with the issue number the user entered before applied to the \r
 112 log message. The client will add the resulting string as a new line to the end \r
 113 of the log message the user entered:\r
 114 logmessage + "\n" + resultstring\r
 115 In case bugtraq.append is set to "false", then the log message is defined as\r
 116 resultstring + "\n" + logmessage\r
 117 \r
 118 The client should make sure that the string doesn't have multiple lines.\r
 119 If more than one issue number is entered by the user (separated by commas), the \r
 120 client must make sure that there's no whitespace chars before and after the \r
 121 comma. And also the whole issue number string must be trimmed.\r
 122 Note: if the bugtraq.logregex property is set, then this property should be\r
 123 ignored for parsing the log message but only be used to show the issue ID edit box.\r
 124 ---------\r
 125 \r
 126 ---------\r
 127 name  : bugtraq.number\r
 128 value : "true"/"yes" or "false"/"no"\r
 129 If this property is set to "false", then the client allows any character entered \r
 130 in the issue text box. Any other value or if the property is missing then only \r
 131 numbers are allowed as the issue number. One exception is the ',' char, which is\r
 132 used to separate multiple issues.\r
 133 \r
 134 The client must never complain if the text box is left empty, i.e. if no issue\r
 135 number is given. Not all commits are assigned to an issue!\r
 136 \r
 137 Note: if the property bugtraq.logregex is set and this property is set to false,\r
 138 then the client should use the regex against the created string which is added\r
 139 to the log message to check if the bug ID is valid.\r
 140 ---------\r
 141 \r
 142 ---------\r
 143 name  : bugtraq.append\r
 144 value : "true"/"yes" or "false"/"no"\r
 145 If set to "false", then the bugtraq.message part is inserted at the top of\r
 146 the log message, if "yes" or not set, then it's appended to the log message at\r
 147 the bottom.\r
 148 ---------\r
 149 \r
 150 \r
 151 Properties used with the regex integration:\r
 152 \r
 153 ---------\r
 154 name  : bugtraq.logregex\r
 155 value : (string)\r
 156 This property contains one or two regular expressions, separated by a newline.\r
 157 If only one expression is set, then the bare bug ID's must be matched in the\r
 158 groups of the regex string. Example:\r
 159 [Ii]ssue #?(\d+)\r
 160 \r
 161 If two expressions are set, then the first expression is used to find a \r
 162 string which relates to a bug ID but may contain more than just the bug ID \r
 163 (e.g. "Issue #123" or "resolves issue 123").\r
 164 The second expression is then used to extract the bare bug ID from the string\r
 165 extracted with the first expression.\r
 166 An example:\r
 167 if you want to catch every pattern "issue #XXX" and "issue #890, #789" inside\r
 168 a log message you could use the following regex strings:\r
 169 [Ii]ssue #?(\d+)(,? ?#?(\d+))+\r
 170 (\d+)\r
 171 \r
 172 The property bugtraq.logregex will override bugtraq.number and bugtraq.message.\r
 173 If both bugtraq.logregex and bugtraq.message are set, then bugtraq.message is\r
 174 only used if the user enters an issue ID in the edit box of the commit window.\r
 175 Both are used in the log window to find the URL's to point to the issuetracker.\r
 176 ---------\r
 177 \r
 178 \r
 179 Please note:\r
 180 - All property names and values must be properly UTF8 encoded. The client must\r
 181   take care of that when setting the properties.\r