Il est très fréquent dans le développement logiciel que les changements soient liés à un bug spécifique ou à un ID d'incident. Les utilisateurs de systèmes de traque de bug (traqueurs d'incidents) peuvent associer les changements qu'ils font dans Subversion avec un ID spécifique dans leur traqueur d'incidents. La plupart des traqueurs fournissent donc un script hook de pre-commit qui analyse syntaxiquement le commentaire pour trouver l'ID du bug auquel la livraison est associée. C'est une source d'erreurs puisque l'utilisateur a la responsabilité d'écrire correctement le commentaire afin que le script hook de pre-commit puisse en faire l'analyse syntaxique correctement.
TortoiseSVN peut aider l'utilisateur de deux manières :
Quand l'utilisateur entre un commentaire, une ligne bien définie incluant le numéro de l'incident associé à la livraison peut être ajoutée automatiquement. Cela réduit le risque que l'utilisateur entre le numéro de l'incident d'une façon que les outils de traque de bugs ne peuvent pas analyser correctement.
Ou TortoiseSVN peut mettre en évidence la partie du commentaire saisi qui est reconnu par le traqueur d'incidents. De cette façon, l'utilisateur sait que le commentaire peut être correctement analysé syntaxiquement.
Quand l'utilisateur parcourt les commentaires, TortoiseSVN crée un lien à partir de chaque ID de bug dans le commentaire qui lance le navigateur à l'incident mentionné.
Vous pouvez intégrer le traqueur de bugs de votre choix dans TortoiseSVN. Pour ce faire, vous devez définir quelques propriétés, qui commencent par bugtraq:. Elles doivent être définies sur les dossiers : (la section intitulée « Configuration des projets »)
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
Cette propriété correspond à l'URL de votre traqueur de bugs. Cette URL doit être correctement encodée et doit contenir
%BUGID%.%BUGID%est remplacé par le numéro de l'incident que vous avez saisi. Cela permet à TortoiseSVN d'afficher un lien dans la boîte de dialogue de journal, qui pointe vers l'entrée correspondant au développement dans votre outil de traque de bugs. Vous n'êtes pas obligé de fournir cette propriété, TortoiseSVN ne montre alors que le numéro de l'incident, pas le lien. Par exemple le projet de TortoiseSVN utilisehttp://issues.tortoisesvn.net/?do=details&id=%BUGID%Vous pouvez utiliser des URLs relatives à la place des URLs absolues. Cela peut être utile quand votre traqueur de bug est sur le même serveur que votre référentiel. Ainsi, si vous changez de nom de domaine, vous n'aurez pas à modifier la propriété
bugtraq:url. Il y a deux manière de donner des URL relatives :If it begins with the string
^/it is assumed to be relative to the repository root. For example,^/../?do=details&id=%BUGID%will resolve tohttp://tortoisesvn.net/?do=details&id=%BUGID%if your repository is located onhttp://tortoisesvn.net/svn/trunk/.A URL beginning with the string
/is assumed to be relative to the server's hostname. For example/?do=details&id=%BUGID%will resolve tohttp://tortoisesvn.net/?do=details&id=%BUGID%if your repository is located anywhere onhttp://tortoisesvn.net.- bugtraq:warnifnoissue
Set this to
true, if you want TortoiseSVN to warn you because of an empty issue-number text field. Valid values aretrue/false. If not defined,falseis assumed.
Dans l'approche simple, TortoiseSVN montre à l'utilisateur un champ de saisie séparé où un ID de bug peut être entré. Une ligne séparée est alors ajoutée avant/après le commentaire que l'utilisateur a saisi.
- bugtraq:message
This property activates the bug tracking 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 log message. It must contain
%BUGID%, which is replaced with the issue number on commit. This ensures that your commit log contains a reference to the issue number which is always in a consistent format and can be parsed by your bug tracking tool to associate the issue number with a particular commit. As an example you might useIssue : %BUGID%, but this depends on your Tool.- bugtraq:append
Cette propriété définit si l'ID-bug est ajouté (true) à la fin du commentaire ou inséré (false) au début du commentaire. Les valeurs valables sont
true/false. Si elle n'est pas définie,trueest par défaut, pour que les projets existants ne cassent pas.- bugtraq:label
This text is shown by TortoiseSVN on the commit dialog to label the edit box where you enter the issue number. 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
trueonly numbers are allowed in the issue-number text field. An exception is the comma, so you can comma separate several numbers. Valid values aretrue/false. If not defined,trueis 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
Cette propriété active le système de bug tracking en mode Regex. Elle contient soit une expression régulière, soit deux séparées par un retour à la ligne.
If two expressions are set, then the first expression is used as a pre-filter to find expressions which contain bug IDs. The second expression then extracts the bare bug IDs from the result of the first regex. This allows you to use a list of bug IDs and natural language expressions if you wish. e.g. you might fix several bugs and include a string something like this: « This change resolves issues #23, #24 and #25 »
Si vous voulez isoler les ID des bugs tels qu'utilisés à l'intérieur des messages de log, vous pouvez utiliser utiliser les espressions régulières suivantes, qui sont celles utilisées par TortoiseSVN en personne :
[Ii]ssues?:?(\s*(,|and)?\s*#\d+)+et(\d+)The first expression picks out « issues #23, #24 and #25 » from the surrounding log message. The second regex extracts plain decimal numbers from the output of the first regex, so it will return « 23 », « 24 » and « 25 » to use as bug IDs.
Breaking the first regex down a little, it must start with the word « issue », possibly capitalised. This is optionally followed by an « s » (more than one issue) and optionally a colon. This is followed by one or more groups each having zero or more leading whitespace, an optional comma or « and » and more optional space. Finally there is a mandatory « # » and a mandatory decimal number.
If only one expression is set, then the bare bug IDs must be matched in the groups of the regex string. Example:
[Ii]ssue(?:s)? #?(\d+)This method is required by a few issue trackers, e.g. trac, but it is harder to construct the regex. We recommend that you only use this method if your issue tracker documentation tells you to.If you are unfamiliar with regular expressions, take a look at the introduction at http://en.wikipedia.org/wiki/Regular_expression, and the online documentation and tutorial at http://www.regular-expressions.info/.
Si les deux propriétés bugtraq:message et bugtraq:logregex sont définies, logregex a la priorité.
Astuce
Même si vous n'avez pas de traqueur d'incidents avec un hook pre-commit analysant syntaxiquement vos commentaires, vous pouvez toujours utiliser cela pour transformer les incidents mentionnés dans vos commentaires en liens !
And even if you don't need the links, the issue numbers show up as a separate column in the log dialog, making it easier to find the changes which relate to a particular issue.
Some tsvn: properties require a true/false value. TortoiseSVN also understands yes as a synonym for true and no as a synonym for false.
Mettre les propriétés sur les dossiers
Pour que le système fonctionne elles doivent être définies sur des dossiers. Quand vous livrez un fichier ou un dossier les propriétés sont lues depuis ce dossier. Si les propriétés n'y sont pas trouvées, TortoiseSVN cherchera vers le haut dans l'arborescence des dossiers pour les trouver jusqu'à ce qu'il arrive à un dossier non versionné, ou à la racine de l'arborescence (par exemple C:\). Si vous pouvez être sûr que chaque utilisateur n'extraie que depuis trunk/ par exemple et pas d'un autre sous-dossier, alors il est suffisant de définir les propriétés sur trunk/. Dans le cas contraire, vous devriez définir les propriétés récursivement sur chaque sous-dossier. Une propriété sur un répertoire remplace les réglages des niveaux supérieurs (plus près de trunk/).
Pour les propriétés du projet uniquement, c'est à dire tsvn:, bugtraq: et webviewer: vous pouvez utiliser la case à cocher guilabel>Récursif
Lorsque vous ajoutez un nouveau sous répertoire via TortoiseSVN, toutes les propriétés du projet du répertoire parent seront automatiquement ajoutées à ce nouveau sous répertoire.
No Issue Tracker Information from Repository Browser
Because the issue tracker integration depends upon accessing subversion properties, you will only see the results when using a checked out working copy. Fetching properties remotely is a slow operation, so you will not see this feature in action from the repo browser unless you started the repo browser from your working copy. If you started the repo browser by entering the URL of the repository you won't see this feature.
For the same reason, project properties will not be propagated automatically when a child folder is added using the repo browser.
This issue tracker integration is not restricted to TortoiseSVN; it can be used with any Subversion client. For more information, read the full Issue Tracker Integration Specification in the TortoiseSVN source repository. (la section intitulée « Licence » explains how to access the repository).
The previous section deals with adding issue information to the log messages. But what if you need to get information from the issue tracker? The commit dialog has a COM interface which allows integration an external program that can talk to your tracker. Typically you might want to query the tracker to get a list of open issues assigned to you, so that you can pick the issues that are being addressed in this commit.
Any such interface is of course highly specific to your issue tracker system, so we cannot provide this part, and describing how to create such a program is beyond the scope of this manual. The interface definition and sample plugins in C# and C++/ATL can be obtained from the contrib folder in the TortoiseSVN repository. (la section intitulée « Licence » explains how to access the repository). A summary of the API is also given in Chapitre 6, IBugtraqProvider interface Another (working) example plugin in C# is Gurtle which implements the required COM interface to interact with the Google Code issue tracker.
For illustration purposes, let's suppose that your system administrator has provided you with an issue tracker plugin which you have installed, and that you have set up some of your working copies to use the plugin in TortoiseSVN's settings dialog. When you open the commit dialog from a working copy to which the plugin has been assigned, you will see a new button at the top of the dialog.
In this example you can select one or more open issues. The plugin can then generate specially formatted text which it adds to your log message.