Integration mit einem System zur Fehlerverfolgung

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:

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

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

Eintragsnummern in Logmeldungen einfügen

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

Abbildung 4.67. Der Dialog Bugtraq-Eigenschaften

Der Dialog Bugtraq-Eigenschaften


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äre http://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:url nicht 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% in https://tortoisesvn.net/?do=details&id=%BUGID% aufgelöst, wenn sich Ihr Projektarchiv auf https://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% in https://tortoisesvn.net/?do=details&id=%BUGID% aufgelöst, wenn sich Ihr Projektarchiv irgendwo auf https://tortoisesvn.net befindet.

bugtraq:warnifnoissue

Wenn die Eigenschaft auf true gesetzt 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, wird false angenommen.

Eintragsnummer in einem Textfeld

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 true gesetzt, 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, wird true angenommen.

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, wird true angenommen, um existierende Projekte nicht zu beschädigen.

Eintragsnummern mittels regulärer Ausdrücke

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

Informationen vom Fehlerverfolgungssystem beziehen

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, sodass wir diesen Teil nicht zur Verfügung stellen können. Die Beschreibung eines solchen Programms sprengt den Rahmen dieses Handbuchs. Die Schnittstellendefinition und Beispielanwendungen 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.

Abbildung 4.68. Beispielabfrage des Fehlerverfolgungssystems

Beispielabfrage des Fehlerverfolgungssystems


In diesem Beispiel können Sie eine oder mehrere offene Aufgaben auswählen. Das Modul kann dann automatisch Text für Ihre Logmeldung generieren.