Es ist in der Software Entwicklung üblich, Änderungen am Quellcode mit einer spezifischen ID in einem Fehlerverfolgungssystem zu verbinden. Dies wird meist mittels eines pre-commit Aktionsskripts im Projektarchiv erreicht, das vom Fehlerverfolgungssystem zur Verfügung gestellt wird und die Logmeldung einer Übertragung nach bestimmten Wörtern durchsucht. Dies ist jedoch sehr fehleranfällig, da der Benutzer sich merken muss wie die Logmeldung auszusehen hat damit das Aktionsskript dies auch richtig erkennen kann.
TortoiseSVN kann hier zweifach helfen:
Wenn der Benutzer eine Logmeldung eingibt, kann eine vordefinierte Zeile automatisch der Logmeldung angehängt oder vorangestellt werden. Dies reduziert das Risiko, dass der Benutzer die Logmeldung falsch eingibt und das Aktionsskript die Eintragsnummer nicht mehr erkennen kann.
Oder TortoiseSVN kann, während der Benutzer die Logmeldung eingibt die Stelle in der Logmeldung hervorheben, die vom Aktionsskript als Eintragsnummer erkannt wird. Auf diese Weise hat der Benutzer eine visuelle Bestätigung für die Korrektheit der Logmeldung.
Wenn der Benutzer die Logmeldungen im Log-Dialog ansieht, kann TortoiseSVN einen Verweis zum Eintrag erstellen und damit durch einen Klick den Web-Browser gleich auf die entsprechende Seite führen.
Sie können ein Fehlerverfolgungssystem Ihrer Wahl in TortoiseSVN einbinden. Dafür müssen Sie ein paar Subversion Eigenschaften definieren, die mit bugtraq: beginnen. Diese Eigenschaften müssen auf Ordner gesetzt werden: („Projekt-Einstellungen“)
Es gibt zwei verschiedene Wege, um TortoiseSVN mit einem Fehlerverfolgungssystem zu verbinden. Ein Weg basiert auf einfachen Zeichenketten, der andere basiert auf Regulären Ausdrücken. Die Eigenschaften, welche von beiden Methoden benutzt werden sind:
- bugtraq:url
Hier geben Sie die URL zu Ihrem Fehlerverfolgungssystem ein. Die URL muss korrekt URI-codiert sein und
%BUGID%enthalten.%BUGID%wird später durch die Eintragsnummer ersetzt. Dies ermöglicht es TortoiseSVN einen direkten Verweis auf die Revision im Log-Dialog anzuzeigen, so dass Sie direkt dorthin springen können. Sie müssen diese Eigenschaft nicht setzen, aber wenn Sie sie weglassen, zeigt TortoiseSVN später nur die Eintragsnummer an und keinen Verweis. Ein Beispiel für TortoiseSVN wärehttp://issues.tortoisesvn.net/?do=details&id=%BUGID%Sie können auch relative URLs anstelle von absoluten verwenden. Das ist nützlich, falls Ihr Fehlerverfolgungssystem sich in derselben Domäne oder auf demselben Server befindet, wie Ihr Projektarchiv. Falls sich der Domänenname ändern sollte, müssen Sie die
bugtraq:urlEigenschaft nicht anpassen. Es gibt zwei Möglichkeiten, relative URLs zu definieren:Falls die URL mit der Zeichenkette
^/beginnt, wird sie relativ zur Wurzel des Projektarchivs angenommen. Zum Beispiel wird^/../?do=details&id=%BUGID%zuhttp://tortoisesvn.net/?do=details&id=%BUGID%aufgelöst, falls Ihr Projektarchiv sich aufhttp://tortoisesvn.net/svn/trunk/befindet.Eine URL die mit der Zeichenkette
/anfängt, wird relative zum Namen des Servers interpretiert. Zum Beispiel wird/?do=details&id=%BUGID%zuhttp://tortoisesvn.net/?do=details&id=%BUGID%aufgelöst, falls Ihr Projektarchiv sich irgendwo aufhttp://tortoisesvn.netbefindet.- bugtraq:warnifnoissue
Wenn die Eigenschaft auf
truegesetzt ist, warnt Sie TortoiseSVN, falls das Feld für die Eintragsnummer im Übertragen-Dialog leer gelassen wurde. Das ist nur eine Erinnerungshilfe, falls der Benutzer die Eingabe vergessen hat. Gültige Werte:true/false. Wenn keine Eigenschaft definiert ist, wirdfalseangenommen.
In der einfachen Variante zeigt TortoiseSVN dem Benutzer ein zusätzliches Eingabefeld für die Eintragsnummer an. Es wird dann der Logmeldung eine zusätzliche Zeile angehängt oder vorangestellt.
- bugtraq:message
Diese Eigenschaft aktiviert das Fehlerverfolgungssystem im Eingabefeld Modus. Wenn sie gesetzt ist, wird TortoiseSVN Sie auffordern, beim Übertragen eine Eintragsnummer anzugeben. Sie wird benutzt, um eine extra Zeile an das Ende der Logmeldung anzufügen. Dafür muss sie den Text
%BUGID%enthalten, der beim Übertragen durch die Eintragsnummer ersetzt wird. Mithilfe dieses Textes kann Ihr Fehlerverfolgungssystem die Logmeldungen analysieren und die Revisionen einem Eintrag zuordnen. TortoiseSVN benutzt z.B.Issue : %BUGID%, aber das hängt von Ihrem Programm ab.- bugtraq:append
Diese Eigenschaft definiert ob die Eintragsnummer an das Ende angehängt oder vor der Logmeldung eingefügt wird. Gütige Werte sind:
true/false. Wenn keine Eigenschaft definiert ist, wirdtrueangenommen.- bugtraq:label
Dieser Text wird von TortoiseSVN im Übertragen-Dialog angezeigt. Er beschreibt das Eingabefeld für die Eintragsnummer. Wird er weggelassen, wird Fehler-ID / Eintrags-Nr: angezeigt. Beachten Sie bitte, dass der Text nicht zu lang ist, da er sonst eventuell einfach abgeschnitten wird. (empfohlen werden max 20 bis 25 Zeichen)
- bugtraq:number
Auf
truegesetzt, werden, außer dem Komma nur Zahlen im Fehlerverfolgungs Eingabefeld akzeptiert.Falseerlaubt auch die Eingabe von Buchstaben. Gültige Werte:true/false. Wenn keine Eigenschaft definiert ist, wirdtrueangenommen.
In der Variante mit den Regulären Ausdrücken zeigt TortoiseSVN kein separates Eingabefeld an, sondern hebt den Teil der Logmeldung hervor, der als Eintragsnummer erkannt wird. Die Erkennung erfolgt während der Benutzer die Logmeldung eingibt. Das bedeutet auch, dass die Eintragsnummer irgendwo in der Logmeldung stehen kann und nicht nur in einer separaten Zeile. Diese wesentlich flexiblere Methode wird vom TortoiseSVN Projekt verwendet.
- bugtraq:logregex
Diese Eigenschaft aktiviert das Fehlerverfolgungssystem im RegEx Modus. Sie enthält entweder einen oder zwei reguläre Ausdrücke, die durch einen Zeilenumbruch getrennt werden.
Wenn zwei Ausdrücke definiert sind, ist der erste Ausdruck ein Vorfilter, mit dem Zeichenfolgen, die Eintrags-IDs enthalten gefunden werden. Der zweite Ausdruck extrahiert dann die Eintrags-IDs aus dem Ergebnis des ersten. Das ermöglicht es Ihnen, Eintrags-IDs auf natürliche Art in die Beschreibung einfließen zu lassen, z.B.: „Diese Änderung erledigt die Fehler #23, #24 und #35“.
Wenn Sie, wie im obigen Beispiel, Zeichenketten in einer Logmeldung finden möchten, können Sie dazu die folgenden beiden regulären Ausdrücke verwenden:
[Ff]ehler:?(\s*(,|und)?\s*#\d+)+sowie(\d+)als zweiten Ausdruck.Der erste Ausdruck schneidet „Fehler #23, #24 und #35“ aus der umgebenden Logmeldung. Der zweite Ausdruck extrahiert die reinen Dezimalzahlen aus der Ausgabe des ersten Ausdrucks. Er gibt also „23“, „24“ und „25“ als Eintrags-IDs zurück.
Eine kleine Erklärung des ersten regulären Ausdrucks: Er sucht nach einem Text der mit „Fehler“, alternativ klein geschrieben, beginnt. Danach kann ein Doppelpunkt folgen. Darauf folgen eine oder mehrere Gruppen, bestehend aus null oder mehr führenden Leerzeichen, einem optionalen Komma oder „und“ sowie möglicherweise weiteren Leerzeichen. Abschließend werden ein „#“ und eine Dezimalzahl gesucht.
Wenn nur ein regulärer Ausdruck gesetzt ist, dann müssen alleine mit ihm die Eintragsnummern in den Gruppen des Ausdrucks gefunden werden. Als Beispiel:
[Ii]ssue(?:s)? #?(\d+). Diese Methode wird von einigen Fehlerverfolgungssystemen, wie z.B. Trac verwendet, es ist jedoch schwieriger, einen passenden regulären Ausdruck zu konstruieren. Wir empfehlen, dass Sie diese Methode nur verwenden, wenn Ihr Fehlerverfolgungssystem dies erfordert.Wenn Sie sich mit regulären Ausdrücken noch nicht so gut auskennen, lesen Sie sich die Einführung unter http://de.wikipedia.org/wiki/Regulärer_Ausdruck sowie die Online-Dokumentation und -Anleitung auf http://www.regular-expressions.info/ durch.
Wenn sowohl die bugtraq:message als auch die bugtraq:logregex Eigenschaft gesetzt ist, erhält logregex Vorrang.
Tipp
Auch wenn Sie gar kein Fehlerverfolgungssystem mit einem pre-commit Aktionsskript haben, können Sie diese Funktion dazu nutzen, Eintragsnummern welche Sie in Ihren Logmeldungen erwähnt haben, in einen Verweis zum Fehlerverfolgungssystem zu verwandeln.
Auch wenn Sie die Verweise selbst nicht benötigen, können Sie Änderungen zu einer bestimmten Nummer einfach finden, denn die Eintragsnummern werden in separaten Spalten im Log-Dialog angezeigt.
Manche tsvn: Eigenschaften erfordern einen true/false Wert. TortoiseSVN versteht auch yes als Synonym für true und no als Synonym für false.
Setzen Sie die Eigenschaften auf Ordner
Die obigen Eigenschaften müssen auf Ordner gesetzt sein, damit das System richtig funktioniert. Beim Übertragen werden die Eigenschaften des aktuellen Ordners gelesen. Falls die Eigenschaften nicht gefunden werden, sucht TortoiseSVN nach oben durch die Ordnerstruktur bis es auf einen nicht versionierten Ordner oder die Wurzel (z.B. C:\) stößt. Wenn Sie sicher gehen können, dass jeder Benutzer z.B. von trunk/ und nicht aus einem Unterordner auscheckt, definieren Sie die Eigenschaften nur für trunk/. Wenn Sie nicht sicher sein können, definieren Sie die Eigenschaft rekursiv für jeden Unterordner. Eigenschaften in einem Unterordner überschreiben die Einstellungen in einem übergeordneten Ordner.
Ausschließlich für tsvn: Eigenschaften können Sie die Rekursiv Option wählen, um die Eigenschaft auf alle Unterordner zu setzen, ohne sie gleichzeitig auch für alle Dateien zu setzen.
Keine Fehlerverfolgungsinformationen im Projektarchivbetrachter
Da die Integration mit Fehlerverfolgungssystemen vom Zugriff auf Subversion Eigenschaften abhängt, sehen Sie die Ergebnisse nur in einer Arbeitskopie. Im Projektarchivbetrachter steht diese Funktion nicht zur Verfügung, weil das Holen der Eigenschaften von einem Server eine zeitintensive Operation list.
Die Integration mit Fehlerverfolgungssystemen ist nicht auf TortoiseSVN limitiert, sie kann von jedem Subversion Client benutzt werden. Für weitere Informationen hierzu lesen Sie bitte die Issuetracker Integration Specification im TortoiseSVN Projektarchiv. („TortoiseSVN ist frei!“ erklärt, wie man auf das TortoiseSVN Projektarchiv zugreift).
Der vorherige Abschnitt befasste sich damit, Eintragsnummern zu den Logmeldungen hinzuzufügen. Aber wie bekommt man Informationen aus dem Fehlerverfolgungssystem? Der Übertragen-Dialog besitzt eine Windows COM Schnittstelle mit deren Hilfe ein externes Programm eingebunden werden kann, das mit dem Fehlerverfolgungssystem kommuniziert. Ein typischer Fall wäre, das Fehlerverfolgungssystem nach einer Liste der Ihnen zugeordneten offenen Aufgaben zu fragen, die Sie beim Übertragen als erledigt markieren wollen.
Jede solche Schnittstelle ist natürlich sehr spezifisch für Ihr System, so dass wir diesen Teil nicht zur Verfügung stellen können und die Beschreibung eines solchen Programms sprengt den Rahmen dieses Handbuchs. Die Schnittstellendefinition und Beispielanwendungen können Sie im contrib Verzeichnis des TortoiseSVN Projektarchivs finden. („TortoiseSVN ist frei!“ erklärt, wie man auf das TortoiseSVN Projektarchiv zugreift). Eine Zusammenfassung der API findet sich in Kapitel 6, IBugtraqProvider Schnittstelle. Ein weiteres, funktionierendes Beispiel in C# ist Gurtle, das die COM Schnittstelle für den Zugriff auf das Google Code Fehlerverfolgungssystem implementiert.
Lassen Sie uns zur Veranschaulichung annehmen, dass Ihr Systemadministrator Sie mit einem Modul für Ihr Fehlerverfolgungssystem versorgt hat, welches Sie installiert haben. Ferner haben Sie im TortoiseSVN Einstellungsdialog einige Ihrer Arbeitskopien so eingerichtet, dass diese die Integration der Fehlerverfolgung nutzen. Wenn Sie nun den Übertragen-Dialog in einer der Arbeitskopien aufrufen, denen das Modul zugewiesen ist, sehen Sie oben im Dialog eine neue Schaltfläche.
In diesem Beispiel können Sie eine oder mehrere offene Aufgaben auswählen. Das Modul kann dann automatisch Text für Ihre Logmeldung generieren.