Intégration avec des systèmes de gestion de bug / gestion d'incidents

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 :

  1. 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 gestionnaire d'incidents. De cette façon, l'utilisateur sait que le commentaire peut être correctement analysé syntaxiquement.

  2. 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é.

Ajouter des numéros d'incidents aux messages de log

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 »)

Figure 4.68. La Boîte de Dialogue des Propriétés de Bugtraq

La Boîte de Dialogue des Propriétés de Bugtraq


Quand vous éditez ni'mporte laquelle des propriétés de bugtraq, un éditeur de propriétés spécial est utilisé pour faciliter la saisie de valeurs appropriées.

Il y a deux façons d'intégrer TortoiseSVN avec les gestionnaires d'incidents. L'une est basée sur des chaînes simples, l'autre sur les expressions régulières. Les propriétés utilisées par les deux approches sont :

bugtraq:url

Set this property to the URL of your bug tracking tool. It must be properly URI encoded and it has to contain %BUGID%. %BUGID% is replaced with the Issue number 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 bug tracking tool. You do not have to provide this property, but then TortoiseSVN shows only the issue number and not the link to it. e.g the TortoiseSVN project is using http://issues.tortoisesvn.net/?do=details&id=%BUGID%.

Vous pouvez utiliser des URLs relatives à la place des URLs absolues. Cela peut être utile quand votre gestionnaire d'incidents est sur le même serveur que votre dépôt. 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 :

Si ça commence avec le caractère ^/, cela suppose que c'est relatif à la racine du dépôt. Par exemple, ^/../?do=details&id=%BUGID% deviendra http://tortoisesvn.net/?do=details&id=%BUGID% si votre dépôt est situé surhttp://tortoisesvn.net/svn/trunk/.

Une URL commençant par le caractère / est supposé être relatif au nom de l'hôte du serveur. Par exemple /?do=details&id=%BUGID% se résume à http://tortoisesvn.net/?do=details&id=%BUGID% si votre dépôt est situé n'importe où sur http://tortoisesvn.net.

bugtraq:warnifnoissue

Mettez cela à true, si vous voulez que TortoiseSVN vous avertisse quand le champ du numéro d'incident est vide. Les valeurs valables sont true/false. Si elle n'est pas définie, false est prise par défaut.

Numéro d'incident dans un Champ Texte

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

Cette propriété active le système de gestion de bugs en mode champ de saisie. Si cette propriété est définie, alors TortoiseSVN vous demandera d'entrer un numéro d'incident quand vous livrez vos changements. Elle est utilisée pour ajouter une ligne à la fin du commentaire. Elle doit contenir %BUGID%, qui est remplacé par le numéro d'incident à la livraison. Cela assure que votre journal de livraison contient une référence au numéro d'incident qui est toujours dans un format cohérent et peut être analysé syntaxiquement par votre outil de gestion de bugs pour associer le numéro d'incident à une livraison particulière. Par exemple vous pourriez utiliser Incident : %BUGID%, mais cela dépend de votre outil.

bugtraq:label

Ce texte est affiché par TortoiseSVN sur la boîte de dialogue de livraison comme label pour la boîte de saisie où vous entrez le numéro d'incident. S'il n'est pas défini, Bug-ID/ N° d'incident sera affiché. Gardez à l'esprit que la fenêtre ne sera pas redimensionnée pour s'adapter à ce label, gardez donc la taille du label en-dessous de 20-25 caractères.

bugtraq:number

Si elle est définie à true, seuls les nombres sont autorisés dans le champ du numéro d'incident. La virgule est une exception, donc vous pouvez séparer plusieurs numéros par des virgules. Les valeurs valides sont true/false. Si elle n'est pas définie, true est la valeur par défaut.

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, true est par défaut, pour que les projets existants ne cassent pas.

Numéros d'incidents utilisant des expressions régulières

Dans l'approche avec les expressions régulières, TortoiseSVN n'affiche pas de champ de saisie séparé, mais marque la partie du commentaire que l'utilisateur entre qui est reconnue par le gestionnaire d'incidents. Cela se fait pendant que l'utilisateur écrit le commentaire. Cela signifie aussi que l'ID de bug peut être n'importe où à l'intérieur d'un commentaire ! Cette méthode est beaucoup plus souple et c'est celle utilisée par le projet TortoiseSVN lui-même.

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 souhaitez obtenir les IDs des bugs tels qu'ils sont utilisés dans l'expression au-dessus dans un message de log, vous pourriez utiliser les expressions régulières suivantes, qui sont celles utilisées par le projet TortoiseSVN: [Ii]ssues?:?(\s*(,|and)?\s*#\d+)+ and (\d+).

La première expression extrait « incidents #23, #24 et #25 » du message de log. La seconde regex extraits les nombres décimaux du résultat de la première regex, on aura donc « 23 », « 24 » et « 25 » à utiliser comme ID des bugs.

Détaillons un peu la première regex. Elle doit commencer par le mot « incident », qui peut être en majuscule. Ceci est éventuellement suivie d'un « s » (plus d'un problème) et éventuellement une virgule. C'est suivi par un ou plusieurs groupes ayant chacun zéro ou plusieurs espaces en tête, une virgule optionnelle ou « et » et d'autres espaces optionnels. Enfin, il y a un « # » obligatoire et un nombre décimal obligatoire.

Si seule une expression est définie, alors l'ID du bug seul doit correspondre aux groupes de la chaîne regex. Exemple : [Ii]ssue(?:s)? #?(\d+). Cette méthode est requise par quelques gestionnaires d'incidents, par exemple trac, mais il est plus difficile de construire la regex. Nous vous recommandons d'utiliser cette méthode uniquement si la documentation de votre gestionnaire d'incidents vous le demande.

If you are unfamiliar with regular expressions, take a look at the introduction at https://en.wikipedia.org/wiki/Regular_expression, and the online documentation and tutorial at http://www.regular-expressions.info/.

It's not always easy to get the regex right so to help out there is a test dialog built into the bugtraq properties dialog. Click on the button to the right of the edit boxes to bring it up. Here you can enter some test text, and change each regex to see the results. If the regex is invalid the edit box background changes to red.

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 gestionnaire d'incidents avec un hook de pré-livraison analysant syntaxiquement vos commentaires, vous pouvez toujours utiliser cela pour transformer les incidents mentionnés dans vos commentaires en liens !

Et même si vous n'avez pas besoin de liens, les numéros des incidents apparaissent dans une colonne distincte dans la boîte de dialogue de log, facilitant la recherche des changements qui se rapportent à un incident particulier.

Certaines propriétés tsvn: exigent une valeur true/false. TortoiseSVN comprend aussi yes comme synonyme de true et no comme synonyme de false.

Mettre les propriétés sur les dossiers

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 (e.g. C:\) is found. If you can be sure that each user checks out only from e.g trunk/ and not some sub-folder, 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 sub-folder. A property setting deeper in the project hierarchy overrides settings on higher levels (closer to trunk/).

As of version 1.8, TortoiseSVN and Subversion use so called inherited properties, which means a property that is set on a folder is automatically also implicitly set on all subfolders. So there's no need to set the properties on all folders anymore but only on the root folder.

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.

Aucune information sur le suivi des incidents à partir du navigateur du dépôt

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.

Pour la même raison, les propriétés du projet ne seront pas propagées automatiquement quand un dossier enfant est ajouté en utilisant le navigateur du dépôt.

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.)

Récupérer des informations depuis le gestionnaire d'incidents

La section précédente porte sur l'ajout d'information concernant les incidents dans des messages de log. Mais que faire si vous avez besoin d'obtenir des informations du gestionnaire d'incidents ? La boîte de dialogue de révision possède une interface COM qui permet l'intégration d'un programme externe qui peut dialoguer avec votre logiciel de gestion. Typiquement, vous voudrez peut-être interroger le gestionnaire pour obtenir la liste des incidents ouverts qui vous sont assignés, de sorte que vous pouvez choisir les incidents qui sont abordées dans cette livraison.

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 7, IBugtraqProvider interface. Another (working) example plugin in C# is Gurtle which implements the required COM interface to interact with the Google Code issue tracker.

À titre d'exemple, supposons que votre administrateur système vous a fourni un plugin de gestionnaire d'incidents que vous avez installé, et que vous avez paramétré certaines de vos copies de travail pour utiliser le plugin dans la boîte de configuration de TortoiseSVN. Lorsque vous ouvrez la boîte de dialogue de livraison à partir d'une copie de travail à laquelle le plugin a été attribué, vous pourrez voir un nouveau bouton en haut de la boîte de dialogue.

Figure 4.69. Exemple de fenêtre de gestionnaire d'incidents

Exemple de fenêtre de gestionnaire d'incidents


Dans cet exemple, vous pouvez sélectionner un ou plusieurs incidents en suspens. Le plugin peut alors générer du texte spécialement mis en forme qu'il ajoute à votre message de log.