Es ist in der Software-Entwicklung üblich, Änderungen am Quellcode mit einer spezifischen ID in einem Fehlerverfolgungssystem (Bugtracker) 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“)
Wenn Sie eine der Bugtraq-Eigenschaften bearbeiten, wird ein spezieller Editor verwendet, um die Eingabe zu erleichtern.
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, die 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, sodass 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, wenn 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 Eigenschaft
bugtraq:urlnicht anpassen. Es gibt zwei Möglichkeiten, relative URLs zu definieren:Wenn es mit der Zeichenkette
^/beginnt, wird davon ausgegangen, dass es relativ zur Wurzel des Projektarchivs ist. Beispielsweise wird^/../?do=details&id=%BUGID%inhttps://tortoisesvn.net/?do=details&id=%BUGID%aufgelöst, wenn sich Ihr Projektarchiv aufhttps://tortoisesvn.net/svn/trunk/befindet.Eine URL, die mit dem Zeichen
/beginnt, wird als relativ zum Hostnamen des Servers angesehen. Zum Beispiel wird/?do=details&id=%BUGID%inhttps://tortoisesvn.net/?do=details&id=%BUGID%aufgelöst, wenn sich Ihr Projektarchiv irgendwo aufhttps://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 Extrazeile 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: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 maximal 20 bis 25 Zeichen.- bugtraq:number
Auf
truegesetzt, werden nur Zahlen im Eingabefeld akzeptiert. Eine Ausnahme bildet das Komma, damit Sie es als Trennzeichen für mehrere Zahlen verwenden können. Gültige Werte sind:true/false. Wenn nichts angegeben ist, wirdtrueangenommen.- bugtraq:append
Diese Eigenschaft definiert, ob die Eintragsnummer an das Ende angehängt (true) oder vor der Logmeldung (false) eingefügt wird. Gültige Werte sind:
true/false. Wenn nichts angegeben ist, wirdtrueangenommen, um existierende Projekte nicht zu beschädigen.
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 ein 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 gefunden werden, die Eintrags-IDs enthalten. 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“ beginnt, alternativ klein geschrieben. 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 https://de.wikipedia.org/wiki/Regulärer_Ausdruck sowie die Online-Dokumentation und -Anleitung auf https://www.regular-expressions.info/ durch.
Es ist nicht immer einfach, einen regulären Ausdruck korrekt zu definieren. Als Hilfsmittel gibt es einen Testdialog, der im bugtraq-Eigenschaftendialog integriert ist. Klicken Sie auf die Schaltfläche rechts vom Eingabefeld, um ihn anzuzeigen. Hier können Sie einen Testtext eingeben und jeden regulären Ausdruck ändern, um die Ergebnisse zu sehen.
Wenn sowohl die Eigenschaft bugtraq:message als auch bugtraq:logregex 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, die 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. Wenn 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 sein 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 (näher an trunk/).
Ab Subversion 1.8 verwenden TortoiseSVN und Subversion sogenannte vererbte Eigenschaften. Das bedeutet, dass eine Ordnereigenschaft automatisch auch für alle Unterordner gilt. Deshalb ist es nicht erforderlich, die Eigenschaften für alle Ordner zu setzen, sondern nur noch für den Wurzelordner.
Ausschließlich für Projekteigenschaften, z. B. tsvn:, bugtraq: und webviewer:, können Sie die Rekursiv-Option wählen, um die Eigenschaft auf alle Unterordner zu übertragen, ohne sie gleichzeitig auch für alle Dateien zu setzen.
Wenn Sie mit TortoiseSVN neue Unterordner zu einer Arbeitskopie hinzufügen, werden sämtliche Projekteigenschaften des Elternordners auf den Unterordner übertragen.
Keine Fehlerverfolgungsinformationen im Projektarchivbetrachter
Da die Integration mit Fehlerverfolgungssystemen vom Zugriff auf Subversion-Eigenschaften abhängt, sehen Sie die Ergebnisse nur in einer Arbeitskopie. Da das Holen der Eigenschaften von einem Server eine zeitintensive Operation ist, steht diese Funktion im Projektarchivbetrachter nicht zur Verfügung, es sei denn, er wurde aus der Arbeitskopie heraus gestartet. Wenn Sie die URL des Projektarchivs direkt eingeben, steht die Funktion nicht zur Verfügung.
Aus dem gleichen Grund werden Projekteigenschaften nicht automatisch weitergereicht, wenn ein Unterordner im Projektarchivbetrachter angelegt wird.
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. („Lizenz“ 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.
So eine Schnittstelle ist natürlich sehr spezifisch für Ihr System, sodass wir diesen Teil nicht zur Verfügung stellen können. Die Beschreibung eines solchen Programms sprengt den Rahmen dieses Handbuchs. Die Schnittstellendefinition und Beispielmodule in C# und C++/ATL können Sie im contrib-Ordner des TortoiseSVN-Projektarchivs finden. („Lizenz“ erklärt, wie man auf das TortoiseSVN-Projektarchiv zugreift.) Eine Zusammenfassung der API findet sich in Kapitel 7, 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, das 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.