Het is gemeengoed in Software Ontwikkeling om wijzigingen te relateren aan een specifieke bug of issue ID. Gebruikers van bug tracking systemen (issue trackers) zullen de wijzigingen welke zij maken in Subversion willen associëren aan een specifiek ID in hun issue tracker. Het merendeel van de issue trackers levert hiervoor een pre-commit hook script welke het logbericht analyseert om het bug ID te vinden waarmee de vastlegging wordt geassociëerd. Dit is enigzins foutgevoelig omdat dit afhankelijk is van de correctheid van het door de gebruiker geschreven logbericht zodat het pre-commit hook script het correct kan analyseren.
TortoiseSVN kan de gebruiker op twee manieren helpen:
Wanneer de gebruiker een logbericht ingeeft kan automatisch een vooraf gedefiniëerde regel, met daarin het met de vastlegging geassociëerde issue-nummer, worden toegevoegd. Dit verkleint het risico dat de gebruiker het issue-nummer op een dusdanige wijze ingeeft dat dit niet correct door de bug tracking tools kan worden geanalyseerd.
Of ToirtoiseSVN kan het gedeelte van het ingegeven logbericht, wat wordt herkend door de issue tracker, accentueren. Op die manier is het voor de gebruiker duidelijk of het logbericht correct kan worden geanalyseerd.
Wanneer de gebruiker door de logberichten bladert, maakt TortoiseSVN van elke bug ID in het logbericht een verwijzing waarmee de genoemde issue in een browser kan worden geopend.
U kunt een bug tracking tool naar keuze in TortoiseSVN integreren. Hiervoor dient een aantal eigenschappen te worden gedefiniëerd, welke starten met bugtraq:. Ze dienen te worden ingesteld op Mappen: (de paragraaf met de naam “Project Instellingen”)
When you edit any of the bugtraq properties a special property editor is used to make it easier to set appropriate values.
Er zijn twee manieren om TortoiseSVN te integreren met issue trackers. De een is gebaseerd op eenvoudige tekenreeksen, de ander is gebaseerd op reguliere expressies. De eigenschappen welke door beide benaderingen worden gebruikt zijn:
- 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 usinghttp://issues.tortoisesvn.net/?do=details&id=%BUGID%.U kunt ook gebruik maken van relatieve URL's in plaats van absolute. Dit kan handig zijn in het geval dat uw issue tracker zich op hetzelfde domein/server bevindt als uw bron archief. In het geval dat de domeinnaam ooit wijzigt hoeft u de
bugtraq:urlniet aan te passen. Er zijn twee manieren om een relatieve URL aan te geven:If it begins with the string
^/it is assumed to be relative to the repository root. For example,^/../?do=details&id=%BUGID%will resolve tohttps://tortoisesvn.net/?do=details&id=%BUGID%if your repository is located onhttps://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 tohttps://tortoisesvn.net/?do=details&id=%BUGID%if your repository is located anywhere onhttps://tortoisesvn.net.- bugtraq:warnifnoissue
Stel dit in op
trueindien u wilt dat TortoiseSVN u waarschuwt in het geval van een leeg issue-nummer tekst veld. Geldige waarden zijntrue/false. Indien niet gedefiniëerd, wordt aangenomen dat de waardefalseis.
In de eenvoudige benadering toont TortoiseSVN een apart invoerveld aan de gebruiker, waar een bug ID kan worden ingegeven. Daarna wordt een aparte regel toegevoegd/vooringevoegd aan het door de gebruiker ingegeven logbericht.
- bugtraq:message
Deze eigenschap activeert het bug tracking systeem in Invoerveld modus. Als deze eigenschap is ingesteld zal TortoiseSVN u vragen om een issue-nummer in te geven wanneer u uw wijzigingen vastlegt. Dit wordt gebruikt om een regel aan het einde van het logbericht toe te voegen. Het moet
%BUGID%bevatten, wat wordt vervangen door het issue-nummer bij vastleggen. Dit biedt de zekerheid dat uw vastleggingslog een referentie naar het issue-nummer bevat, welke altijd in een consistent formaat is en kan worden geanalyseerd door uw bug tracking tool, om het issue-nummer met een bepaalde vastlegging te associëren. Als voorbeeld zou uIssue : %BUGID%kunnen gebruiken, maar dat hangt van uw tool af.- bugtraq:label
Deze tekst wordt door TortoiseSVN getoond op het vastleggings venster om het invoerveld aan te geven waar u het issue-nummer ingeeft. Wanneer het niet is ingesteld zal
Bug-ID / Issue-Nr:worden getoond. Houdt in gedachten dat het venster niet in grootte wordt aangepast om het label te laten passen, dus houdt de grootte van het label onder de 20-25 tekens.- bugtraq:number
Indien ingesteld op
truezijn alleen nummers in het issue-nummer tekstveld toegestaan. Een uitzondering is de komma, zodat meerdere nummers door een komma kunnen worden gescheiden. Geldige waarden zijntrue/false. Indien niet gedefiniëerd wordt aangenomen dat de waardetrueis.- bugtraq:append
Deze eigenschap definiëert of het bug-ID wordt toegevoegd (true) aan het einde van het logbericht of ingevoegd (false) aan het begin van het logbericht. Geldige waarden zijn
true/false. Indien niet gedefiniëerd wordt aangenomen dat de waardetrueis, zodat bestaande projecten niet mislukken.
In de benadering met reguliere expressies toont TortoiseSVN geen apart invoerveld, maar wordt het gedeelte van de door de gebruiker ingegeven logbericht aangemerkt wat door de issue tracker wordt herkend. Dit wordt gedaan terwijl de gebruiker het logbericht ingeeft. Dit betekent ook dat het bug ID zich overal in het logbericht mag bevinden! Deze methode is veel flexibeler en is de methode welke door het TortoiseSVN project zelf wordt gebruikt.
- bugtraq:logregex
Deze eigenschap activeert het bug tracking systeem in Regex modus. Het bevat of een enkele reguliere expressie, of twee door een nieuwe regel gescheiden reguliere expressies.
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”.
If you want to catch bug IDs as used in the expression above inside a log message, you could use the following regex strings, which are the ones used by the TortoiseSVN project:
[Ii]ssues?:?(\s*(,|and)?\s*#\d+)+and(\d+).De eerste expressie haalt “issues #23, #24 and #25” uit het omringende logbericht. De tweede regex extraheert zuivere decimale nummers uit de uitvoer van de eerste regex, zodat het “23”, “24” en “25” teruggeeft om te gebruiken als bug ID's.
Wanneer we de eerste regex in stukken opbreken, dan moet deze beginnen met het woord “issue”, mogelijk in hoofdletters. Dit wordt eventueel gevolgd door een “s” (meerdere issues) en eventueel een dubbele punt. Dit wordt gevolgd door een of meerdere groepen welke elk worden voorafgegaan door 0 of meer witruimte tekens, een komma of “en” en meer optionele spaties. Als laatste is er een verplichte “#” en een verplicht decimaal nummer.
Indien slechts één expressie is ingesteld, moeten de kale bug ID's worden vergeleken met de groepen van de regex tekenreeks. Voorbeeld:
[Ii]ssue(?:s)? #?(\d+)Deze methode is vereist door een aantal issue trackers, bijv. trac, maar het is moeilijker om de regex samen te stellen. We adviseren deze methode alleen te gebruiken wanneer de documentatie van de issue tracker dit voorschrijft.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.
Als beide eigenschappen bugtraq:message en bugtraq:logregex zijn ingesteld, krijgt logregex voorrang.
Tip
Zelfs als u geen issue tracker heeft welke uw logberichten analyseert met een pre-commit hook, kunt u dit gebruiken om de in uw logbericht genoemde issues om te zetten naar verwijzingen!
En zelfs als u de verwijzingen niet nodig heeft, worden de issue-nummers getoond als een aparte kolom in het log venster wat het gemakkelijker maakt om de wijzigingen te vinden welke aan een bepaalde issue zijn gerelateerd.
Sommige tsvn: eigenschappen vereisen een true/false waarde. TortoiseSVN begrijpt ook yes als een synoniem voor true en no als een synoniem voor false.
Stel de Eigenschappen in op Mappen
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.
Bij eigenschappen welke alleen op projecten van toepassing zijn, bijv. tsvn:, bugtraq: en webviewer:, kunt u gebruik maken van de Recursief vinkbox om de eigenschap op alle sub-mappen binnen de hiërarchie in te stellen, zonder het ook op de bestanden in te stellen.
Als u met TortoiseSVN nieuwe sub-mappen aan een werkkopie toevoegd, zullen alle project eigenschappen welke in de bovenliggende map aanwezig zijn, automatisch aan de nieuwe sub-map worden toegevoegd.
Geen Issue Tracker Informatie vanuit de Archief Verkenner
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.
Om de zelfde reden zullen de project eigenschappen niet automatisch worden gepropageerd wanneer een sub-map wordt toegevoegd vanuit de archief-verkenner.
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. (de paragraaf met de naam “Licentie” explains how to access the repository.)
De vorige sectie betrof het toevoegen van issue informatie aan de logberichten. Maar wat als u de informatie wilt verkrijgen uit de issue tracker? Het vastleg scherm bezit een COM interface welke de mogelijkheid biedt een extern programma, wat met uw tracker kan praten, te integreren. Gewoonlijk wilt u de tracker een lijst vragen met openstaande issues op uw naam, zodat u die issues eruit kunt pikken welke betrekking hebben op deze vastlegging.
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. (de paragraaf met de naam “Licentie” explains how to access the repository.) A summary of the API is also given in Hoofdstuk 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.
Als voorbeeld: Aangenomen dat uw systeemadministrator u een issue tracker plugin heeft aangeleverd welke u heeft geïnstalleerd, en dat u enkele van uw werkkopieën zo heeft ingesteld, met behulp van het TortoiseSVN instellingen scherm, dat ze gebruik maken van de plugin. Wanneer u het vastleggen scherm opent vanuit de werkkopie waaraan de plugin is toegekend, zult u een nieuwe knop zien aan de bovenkant van het venster.
In dit voorbeeld kunt u één of meerdere issues selecteren. De plugin kan vervolgens een speciaal opgemaakte tekst genereren welke deze toevoegt aan uw logbericht.