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 gestionnaire 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 »)
Quand vous éditez une propriété 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
Positionnez cette propriété sur l'URL de votre outil de suivi de bogue. Elle doit être correctement encodée en URI et doit contenir
%BUGID%. Le paramètre%BUGID%est remplacé par le numéro d'incident que vous avez saisi. Cela permet à TortoiseSVN d'afficher un lien dans la boîte de dialogue de journal, pour que vous puissiez basculer directement vers votre outil de suivi de bogue depuis le journal de révision. Il n'est pas obligatoire de fournir cette propriété, mais dans ce cas TortoiseSVN n'affiche que le numéro de l'incident et pas le lien vers celui-ci. Par exemple, le projet TortoiseSVN utilisehttp://issues.tortoisesvn.net/?do=details&id=%BUGID%.Vous pouvez aussi utiliser des URLs relatives au lieu d'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ères de spécifier une URL relative :Si elle commence par la chaîne
^/, elle est relative à la racine du dépôt. Par exemple,^/../?do=details&id=%BUGID%va se résoudre enhttps://tortoisesvn.net/?do=details&id=%BUGID%si votre dépôt est situé surhttps://tortoisesvn.net/svn/trunk/.Une URL qui commence par la chaîne
/est relative au nom d'hôte du serveur. Par exemple,/?do=details&id=%BUGID%va se résoudre enhttps://tortoisesvn.net/?do=details&id=%BUGID%si votre dépôt est situé quelque part sur le domainehttps://tortoisesvn.net.- bugtraq:warnifnoissue
Positionnez cette valeur à
truesi vous voulez que TortoiseSVN vous avertisse quand le champ du numéro d'incident est vide. Les valeurs valables sonttrue/false. Si elle n'est pas définie,falseest prise par défaut.
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 utiliserIncident : %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'incidentsera 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 sonttrue/false. Si elle n'est pas définie,trueest 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,trueest par défaut, pour que les projets existants ne cassent pas.
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.
Si deux expressions sont définies, alors la première est utilisée comme pré-filtre pour trouver les expressions qui contiennent des IDs de bogue. La seconde expression extrait alors les IDs de bogue du résultat de la première expression régulière. Cela vous permet d'utiliser une liste d'IDs de bogue avec du langage courant si vous le souhaitez. Par exemple, vous pourriez avoir résolu plusieurs bogues et saisir une chaîne de ce type : « Cette modification résout les incidents #23, #24 et #25 ».
Si vous souhaitez extraire les IDs de bogue d'un message de journal du type de celui de l'expression ci-dessus, vous pourriez utiliser les expressions régulières suivantes, qui sont celles utilisées par le projet TortoiseSVN :
[Ii]ncidents?:?(\s*(,|et)?\s*#\d+)+et(\d+).La première expression extrait « incidents #23, #24 et #25 » du message de journal. La seconde regex extrait les nombres décimaux du résultat de la première regex, on aura donc « 23 », « 24 » et « 25 » à utiliser comme ID de bogue.
Détaillons un peu la première regex. Elle doit commencer par le mot « incident », dont la première lettre peut être une majuscule. Elle continue par un « s » optionnel (s'il y a plusieurs incidents) et deux points également optionnels. Elle continue ensuite par un ou plusieurs groupes ayant chacun zéro, un ou plusieurs espaces de tête, une virgule optionnelle ou le mot « 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.Si les expressions régulières ne vous sont pas familières, vous pouvez consulter une introduction sur https://fr.wikipedia.org/wiki/Expression_r%C3%A9guli%C3%A8re, et de la documentation en ligne et un tutoriel sur http://www.regular-expressions.info/.
Il n'est pas toujours facile de trouver la bonne regex. Pour vous y aider, il y a une boîte de dialogue de test intégrée à la boîte de dialogue de propriétés bugtraq. Cliquez sur le bouton à droite des zones de saisie pour la faire apparaître. Vous pouvez y saisir des exemples de texte, et modifier chaque regex pour voir les résultats. Si la regex est invalide, le fond de la zone de saisie passe en rouge.
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.
Positionnez les propriétés sur les dossiers
Ces propriétés doivent être positionnées sur les dossiers pour que le système fonctionne. Quand vous livrez un fichier ou un dossier, ce sont les propriétés de ce dossier qui sont lues. S'il n'y trouve pas les propriétés, TortoiseSVN va les chercher en remontant l'arborescence jusqu'à ce qu'il arrive à un dossier non versionné ou à la racine (par exemple C:\). Si vous pouvez être sûr que chaque utilisateur extrait à partir du même endroit, par exemple de trunk/ et pas d'un sous-dossier, alors il suffit de positionner les propriétés sur trunk/. Si vous ne pouvez pas en être sûr, vous devriez positionner les propriétés sur chaque sous-dossier de manière récursive. Une propriété positionnée plus bas dans la hiérarchie du projet surcharge celles positionnées sur les niveaux plus élevés (c'est-à-dire plus près de trunk/).
Depuis la version 1.8, TortoiseSVN et Subversion utilisent ce qu'on appelle des propriétés héritées, ce qui signifie qu'une propriété positionnée sur un dossier est aussi implicitement positionnée sur tous les sous-dossiers automatiquement. Il n'est donc plus nécessaire de positionner les propriétés sur tous les dossiers, mais uniquement sur le dossier racine.
Pour les propriétés de projet uniquement, c'est-à-dire tsvn:, bugtraq: et webviewer: vous pouvez utiliser la case à cocher Récursif pour appliquer la propriété à tous les sous-dossiers, sans avoir à la mettre aussi sur tous les fichiers.
Lorsque vous ajoutez un nouveau sous-dossier à une copie de travail via TortoiseSVN, toutes les propriétés de projet du dossier parent seront automatiquement ajoutées à ce nouveau dossier fils.
Aucune information sur le suivi des incidents à partir du navigateur du dépôt
Comme l'intégration du suivi d'incidents repose sur l'accès aux propriétés Subversion, vous n'en verrez les résultats que quand vous travaillez sur une copie de travail extraite. Récupérer des propriétés sur le serveur est une opération lente, donc vous ne verrez pas cette fonctionnalité à l'œuvre dans le navigateur de dépôt, à moins que vous n'ayez démarré le navigateur de dépôt depuis votre copie de travail. Si vous avez démarré le navigateur de dépôt en saisissant l'URL du dépôt, vous ne verrez pas cette fonctionnalité.
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.
L'intégration de suivi d'incidents n'est pas limitée à TortoiseSVN ; elle peut être utilisée avec n'importe quel client Subversion. Pour plus d'informations, lisez la spécification de l'intégration de suivi d'incidents dans le dépôt des sources de TortoiseSVN. (La la section intitulée « Licence » détaille comment accéder au dépôt.)
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.
Toute interface de ce type est évidemment extrêmement spécifique à votre système de gestion d'incidents, ce qui fait que nous ne pouvons pas en fournir, et décrire comment créer un tel logiciel dépasse le cadre de ce manuel. La définition d'interface et les exemples de plugin en C# et C++/ATL sont disponibles dans le dossier contrib du dépôt TortoiseSVN. (La la section intitulée « Licence » détaille comment accéder au dépôt.) Un résumé de l'API est également fourni au Chapitre 7, IBugtraqProvider interface. Un autre exemple (fonctionnel) de plugin en C# est Gurtle, qui implémente l'interface COM requise pour interagir avec le gestionnaire d'incidents de Google Code.
À 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.
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.