Integration with Bugtracking Systems / Issue trackers
It is very common in Software Development for changes to be related to a specific
bug or issue ID. Users of bug tracking systems (issue trackers) would like to associate
the changes they make in Subversion with a specific ID in their issue tracker.
Most issue trackers therefore provide a pre-commit hook script which parses the log
message to find the bug ID with which the commit is associated.
This is somewhat error prone since it relies on the user to write the log message
properly so that the pre-commit hook script can parse it correctly.
TortoiseSVN can help the user in two ways:
When the user enters a log message, a well defined line including
the issue number associated with the commit can be added automatically.
This reduces the risk that the user enters the issue number in a way
the bug tracking tools can't parse correctly.
Or TortoiseSVN can highlight the part of
the entered log message which is recognized by the issue tracker.
That way the user knows that the log message can be parsed correctly.
When the user browses the log messages, TortoiseSVN
creates a link out of each bug ID in the log message which fires
up the browser to the issue mentioned.
You can integrate a Bugtracking Tool of your choice in
TortoiseSVN. To do this, you have to define
some properties, which start with bugtraq:.
They must be set on Folders: (the section called “Project Settings”)
There are two ways to integrate TortoiseSVN with issue trackers. One is
based on simple strings, the other is based on regular expressions.
The properties used by both approaches are:
- bugtraq:url
Set this property to the url of your bugtracking tool.
It must be properly URI encoded and it has to contain
%BUGID%.
%BUGID% is replaced with the Issuenumber
you entered. This allows TortoiseSVN
to display a link in the log dialog, so when you are looking
at the revision log you can jump directly to your
bugtracking tool.
You do not have to provide this property, but then
TortoiseSVN shows only the
issuenumber and not the link to it.
e.g the TortoiseSVN project is using
http://issues.tortoisesvn.net/Ёdo=details&id=%BUGID%
- bugtraq:warnifnoissue
Set this to true, if you want
TortoiseSVN to warn you
because of an empty issuenumber textfield. Valid values
are true/false.
If not defined, false is assumed.
In the simple approach, TortoiseSVN shows the user
a separate input field where a bug ID can be entered. Then a separate line
is appended/prepended to the log message the user entered.
- bugtraq:message
This property activates the Bugtracking System
in Input field mode.
If this property is set, then TortoiseSVN
will prompt you to enter an issue number when you commit
your changes. It's used to add a line at the end of the
logmessage. It must contain
%BUGID%, which is replaced with the
issuenumber on commit. This ensures that your commit log
contains a reference to the issuenumber which is always
in a consistent format and can be parsed by your
Bugtracking tool to associate the issuenumber with a
particular commit. e.g the TortoiseSVN project is using
Issue : %BUGID%,
but this depends on your Tool.
- bugtraq:append
This property defines if the bug-ID is appended (true)
to the end of the log message or inserted (false) at the
start of the log message. Valid values are
true/false.
If not defined, true is assumed,
so that existing projects don't break.
- bugtraq:label
This text is shown by TortoiseSVN
on the commit dialog to label the edit box where you enter
the issuenumber. If it's not set,
Bug-ID / Issue-Nr: will be displayed.
Keep in mind though that the window will not be resized
to fit this label, so keep the size of the label below
20-25 characters.
- bugtraq:number
If set to true only numbers are allowed
in the issuenumber textfield.
An exception is the comma, so you can comma separate several
numbers. Valid values are true/false.
If not defined, true is assumed.
In the approach with regular expressions, TortoiseSVN
doesn't show a separate input field but marks the part of the log message the user
enters which is recognized by the issue tracker. This is done while the user
writes the log message. This also means that the bug ID can be anywhere inside a log
message!
This method is much more flexible, and is the one used by the TortoiseSVN project itself.
- bugtraq:logregex
This property activates the Bugtracking System
in Regex mode.
It contains one or two regular expressions, separated by a newline.
If only one expression is set, then the bare bug ID's must be matched
in the groups of the regex string. Example:
[Ii]ssue(Ё:s)Ё #Ё(\d+)
If two expressions are set, then the first expression is used to find
a string which relates to the bug ID but may contain more than just
the bug ID (e.g. "Issue #123" or "resolves issue 123").
The second expression is then used to extract the bare bug ID from the string
extracted with the first expression.
An example:
If you want to catch every pattern "issue #XXX" and "issue #890, #789"
inside a log message you could use the following regex strings:
[Ii]ssue #Ё(\d+)(,Ё Ё#(\d+))* and the second expression as
(\d+)
If you are unfamiliar with regular expressions, take a look at
the online documentation and tutorial at
http://www.regular-expressions.info/
.
If both the bugtraq:message and bugtraq:logregex
properties are set, logregex takes precedence.
Tip
Even if you don't have an issue tracker with a pre-commit hook parsing your
log messages, you still can use this to turn the issues mentioned in your
log messages into links!
Some tsvn: properties require a
true/false value. TSVN also understands
yes as a synonym for true and
no as a synonym for false.
Set the Properties on Folders
These properties must be set on folders for the system to work.
When you commit a file or folder the properties are read from that folder.
If the properties are not found there, TortoiseSVN will search upwards
through the folder tree to find them until it comes to an unversioned
folder, or the tree root (eg. C:\) is found.
If you can be sure that each user checks out only from e.g
trunk/ and not some subfolder, then it's enough if
you set the properties on trunk/.
If you can't be sure, you should set the properties recursively
on each subfolder.
A property setting deeper in the project hierarchy overrides settings on
higher levels (closer to trunk/).
For tsvn: properties only
you can use the Recursive checkbox to set
the property to all subfolders in the hierarchy, without also
setting it on all files.
This issue tracker integration is not restricted to TortoiseSVN; it can be used
with any Subversion client. For more information, read the full
Issuetracker Integration Specification
.
