Blog

So verknüpfen Sie Branches, Commits und Pull Requests mit Issues

Fragen Sie ein Team, zu welchem Issue ein Pull Request gehört, folgt oft eine Pause und dann eine Suche. Fragen Sie, welcher Code für ein bestimmtes Issue ausgeliefert wurde, lautet die Antwort: Commit-Verlauf durchsuchen. Beide Fragen lassen sich in Sekunden beantworten, wenn eine Gewohnheit gilt: Der Issue-Schlüssel begleitet die Arbeit vom Branch-Namen über die Commit-Nachricht bis zum Pull Request.

Diese Gewohnheit braucht weder einen neuen Prozess noch ein neues Werkzeug. Sie braucht einige wenige einfache Konventionen, die jedes Mal gleich angewendet werden. Dieser Ratgeber beschreibt diese Konventionen, die Fehler, die sie unbemerkt aushöhlen, und wie ISO Mate sie nutzt, um den Code zu jedem Issue anzuzeigen, ohne dass jemand ein Formular ausfüllt.

Warum der Issue-Schlüssel die Verbindung ist

Git weiß nichts von Ihrem Issue-Tracker. Ein Branch, ein Commit und ein Pull Request sind nur Namen und Text. Der einzige Weg, sie mit einer geplanten Aufgabe zu verbinden, ist, in diesen Text etwas zu schreiben, das ein Mensch oder ein Werkzeug später erkennen kann. Der Issue-Schlüssel (zum Beispiel PROJ-42) eignet sich dafür ideal, weil er kurz und eindeutig ist und das Team die Arbeit ohnehin so benennt.

Sobald der Schlüssel in dem Text steht, den Git aufbewahrt, werden viele mühsame Fragen einfach. Reviewer sehen, warum eine Änderung existiert. Wer die Release-Zusammenfassung schreibt, sieht, welche Änderungen zu welchen Issues gehören. Wer Monate später eine Regression analysiert, kann von einer Codezeile zum Commit und zum Grund seiner Entstehung gelangen. Und wenn ein Auditor oder Kunde fragt, welche Änderung eine bestimmte Anforderung abgedeckt hat, antworten Sie aus der Aufzeichnung statt aus dem Gedächtnis.

Die fünf Gewohnheiten

  1. Verwenden Sie Schlüssel, die sich nie ändern.
  2. Benennen Sie den Branch mit dem Schlüssel.
  3. Beginnen Sie Commit-Nachrichten mit dem Schlüssel.
  4. Setzen Sie den Schlüssel in den Titel des Pull Requests.
  5. Legen Sie fest, was ein Merge für das Issue bedeutet.

1. Verwenden Sie Schlüssel, die sich nie ändern

Ein Schlüssel funktioniert nur dann als Verbindung, wenn er so lange, wie der Code existiert, genau ein Element bezeichnet. Wenn Schlüssel neu nummeriert, wiederverwendet oder bei einem Typwechsel umgeschrieben werden können, wird jeder alte Branch-Name und jede alte Commit-Nachricht zu einem toten Verweis. Wählen Sie für jedes Projekt ein kurzes, erkennbares Präfix wie API oder WEB und behandeln Sie die Nummer als dauerhaft.

Die Lösung: Wählen Sie einen Tracker, der Schlüssel nie umschreibt, und einigen Sie sich auf ein Präfix pro Projekt, bevor der erste Branch entsteht. In ISO Mate besteht der Projektschlüssel aus 2 bis 10 Großbuchstaben oder Ziffern und steht nach dem Anlegen des Projekts fest. Ein Issue behält außerdem seinen Schlüssel, auch wenn Sie es später von Task auf Bug ändern, sodass Verweise in Commit-Nachrichten gültig bleiben.

2. Benennen Sie den Branch mit dem Schlüssel

Der Branch ist das Erste, was beim Start der Arbeit entsteht, also der früheste Punkt, an dem sich die Verbindung herstellen lässt. Ein einheitliches Muster macht Branches außerdem in jedem Git-Werkzeug sortierbar und lesbar.

Die Lösung: Einigen Sie sich auf ein Muster und verwenden Sie es überall. Eine gängige Wahl ist feature/PROJ-42-add-invoice-export: ein Typ, der Schlüssel und ein kurzer Slug der Zusammenfassung. Halten Sie den Schlüssel am Anfang und den Slug kurz und streben Sie einen Branch pro Issue an. Wenn ein Branch unbemerkt drei Issues trägt, stimmt die Verbindung für alle drei und nützt keinem.

3. Beginnen Sie Commit-Nachrichten mit dem Schlüssel

Bei Commits hält die Verbindung am längsten, denn der Commit-Verlauf bleibt bestehen, auch wenn Branches gelöscht werden. Eine Nachricht wie PROJ-42 Add CSV export for invoices lässt sich nach Schlüssel durchsuchen und ist auf einen Blick lesbar.

Die Lösung: Beginnen Sie mit dem Schlüssel und beschreiben Sie dann die Änderung in klaren Worten. Halten Sie nach Möglichkeit ein Issue pro Commit. Eine Einschränkung: Wenn Ihr Team per Squash mergt, werden die einzelnen Commits zu einem zusammengefasst, und dessen Nachricht stammt meist aus dem Pull Request. Damit ist die nächste Gewohnheit die wichtigere der beiden.

4. Setzen Sie den Schlüssel in den Titel des Pull Requests

Der Pull Request ist das, was Reviewer, Projektverantwortliche und Release-Verantwortliche tatsächlich ansehen. Ein Titel wie PROJ-42 Add CSV export for invoices sagt ihnen, wofür die Änderung da ist, noch bevor sie ihn öffnen. Die Beschreibung ist der Ort für verwandte Schlüssel, Kontext und alles, was ein Reviewer prüfen sollte.

Die Lösung: Öffnen Sie den Pull Request als Entwurf, sobald es etwas zu zeigen gibt. Dann besteht die Verbindung schon während der Arbeit, und Projektverantwortliche sehen, dass hinter dem Issue Code steht, ohne nachzufragen. Wenn ein einzelner Pull Request tatsächlich mehr als ein Issue abdeckt, nennen Sie jeden Schlüssel. Das ist zugleich ein Anlass zu fragen, ob die Änderung hätte aufgeteilt werden sollen.

5. Legen Sie fest, was ein Merge für das Issue bedeutet

Code mit einem Issue zu verknüpfen und ein Issue abzuschließen sind zwei verschiedene Dinge. Ein gemergter Pull Request heißt nicht zwingend, dass die Arbeit erledigt ist. Es kann noch ein Deployment, ein Testlauf oder ein Abgleich mit den Akzeptanzkriterien fehlen. Teams, die diese Entscheidung auslassen, haben am Ende Issues, die als Done markiert sind, aber niemand geprüft hat, oder Issues, die noch lange In Progress stehen, obwohl ihr Code längst ausgeliefert wurde.

Die Lösung: Halten Sie schriftlich fest, wer das Issue wann weiterbewegt: beim Merge, beim Deployment oder nach der Prüfung. Machen Sie das dann zum Teil Ihrer Definition of Done, statt es dem Gedächtnis zu überlassen.

Vier Arten, wie die Verbindung unbemerkt reißt

  • Ein Tippfehler im Schlüssel. Wer PROJ-24 statt PROJ-42 schreibt, verknüpft die Arbeit mit einem anderen, real existierenden Issue. Es gibt keine Fehlermeldung, also zeigt das falsche Issue eine Aktivität, die nicht zu ihm gehört. Kopieren Sie den Schlüssel aus dem Issue, statt ihn zu tippen.
  • Beginnen, bevor das Issue existiert. Arbeit, die als namenloser Branch beginnt, bekommt ihren Schlüssel erst später, wenn überhaupt. Das Issue anzulegen dauert eine Minute und erspart das Aufräumen.
  • Langlebige Branches. Ein Branch, der wochenlang offen bleibt und mehrere Issues sammelt, schwächt jede Verbindung auf ihm. Kleinere Branches bedeuten außerdem kleinere, leichtere Reviews.
  • Schlüssel nur in der Beschreibung. Manche Werkzeuge lesen nur den Titel. Setzen Sie den Hauptschlüssel in den Titel und nutzen Sie die Beschreibung für Ergänzungen.

Wie ISO Mate die Verknüpfung für Sie übernimmt

Diese Gewohnheiten sind werkzeugunabhängig, zahlen sich aber am meisten aus, wenn etwas die Schlüssel für Sie liest. Genau das leisten die Projekt-Git-Integrationen in ISO Mate. So entspricht jede Gewohnheit dem, was die Plattform tut.

  • Schlüssel: Issues in einem Projekt tragen den Projektschlüssel als Präfix, ein Projekt mit dem Schlüssel PROJ erzeugt also PROJ-1, PROJ-2 und so weiter. Issues ohne Projekt verwenden ein Typ-Präfix (EPC, USR, TSK, BUG oder SUB). Der Leitfaden zu Issue-Schlüsseln erklärt die Nummerierung.
  • Ein Repository verbinden: Fügen Sie in den Einstellungen eines Projekts eine Verbindung zu GitHub, GitLab oder Bitbucket mit einem Zugriffstoken hinzu. ISO Mate prüft das Token und erkennt, ob es nur Lesezugriff oder Lese- und Schreibzugriff hat.
  • Abgleich: Alle 15 Minuten synchronisiert ISO Mate Branches, Commits und Pull Requests jedes verbundenen Repositorys. Es sucht nach Issue-Schlüsseln in Branch-Namen, Commit-Nachrichten sowie Titeln und Beschreibungen von Pull Requests und verknüpft Treffer mit dem passenden Issue. Groß- und Kleinschreibung spielt keine Rolle, und ein Pull Request, der zwei Schlüssel nennt, wird mit beiden verknüpft. Ein Schlüssel wird nur verknüpft, wenn ein Issue mit diesem Schlüssel existiert.
  • Git-Aktivität am Issue: Öffnen Sie ein Issue, und der Bereich Git-Aktivität listet die verknüpften Branches, Commits und Pull Requests nach Repository gruppiert auf, jeweils mit einem Link zum Anbieter. Pull Requests zeigen ihren Status, und eine Aktualisieren-Aktion synchronisiert das Issue sofort, statt auf den nächsten Zyklus zu warten.
  • Die Arbeit vom Issue aus starten: Branch erstellen bildet einen Namen aus Issue-Schlüssel und Zusammenfassung. Das Standardmuster lautet feature/{KEY}-{summary}, und jedes Projekt kann sein eigenes Standard-Branch-Muster festlegen. Sie können den Branch-Namen oder einen fertigen Checkout-Befehl kopieren. MR/PR erstellen öffnet einen Pull Request, der den Issue-Schlüssel im Titel trägt und als Entwurf beginnt. Beide Aktionen setzen eine Verbindung mit Schreibzugriff voraus.
  • Aufräumen: Jeder Branch und jeder Pull Request hat ein Aktionsmenü, um ihn vom Issue zu trennen und, mit Schreibzugriff, den Branch zu löschen oder einen offenen Pull Request beim Anbieter nach einer Bestätigung zu schließen.

Einige Grenzen sollten Sie kennen, bevor Sie sich darauf verlassen. Die Synchronisierung läuft im 15-Minuten-Takt, ein ganz neuer Branch kann also so lange brauchen, bis er erscheint, sofern Sie nicht aktualisieren. ISO Mate ändert den Status eines Issues nicht, wenn ein Pull Request gemergt wird, daher bleibt die fünfte Gewohnheit eine Entscheidung des Teams. Und eine einmal entstandene Verknüpfung wird nicht automatisch entfernt, wenn Sie einen Titel bearbeiten. Hat ein Tippfehler das falsche Issue verknüpft, trennen Sie die Verknüpfung im Bereich Git-Aktivität.

Ein Sicherheitshinweis: Vergeben Sie nur so viel Zugriff wie nötig. Wenn Ihre Entwickler Branches und Pull Requests mit eigenen Werkzeugen anlegen, reicht ein Token mit reinem Lesezugriff, damit ISO Mate synchronisiert und verknüpft. Vergeben Sie Schreibzugriff nur, wenn Sie Branches und Pull Requests direkt aus dem Issue erstellen möchten. Die Einrichtungsanleitung listet die Token-Berechtigungen je Anbieter auf.

Fünf Fragen zur Prüfung Ihres Teams

  1. Hat jedes Issue einen Schlüssel, der nie neu nummeriert oder wiederverwendet wird?
  2. Benennen alle Branches nach demselben Muster, mit dem Schlüssel zuerst?
  3. Beginnen Commit-Nachrichten und Pull-Request-Titel mit dem Schlüssel?
  4. Können Sie jedes Issue öffnen und den Code dahinter sehen, und jeden Pull Request öffnen und sein Issue nennen?
  5. Weiß das Team, wer ein Issue wann auf Done setzt?

Lautet die Antwort auf eine dieser Fragen nein, beginnen Sie mit der Gewohnheit, die am weitesten oben in der Liste steht, denn jede macht die nächste wertvoller. Um die Verknüpfungen an Ihren eigenen Issues zu sehen, verbinden Sie in DevOps-Management ein Repository mit einem Projekt. Jedes ISO-Mate-Konto beginnt mit einer 14-tägigen kostenlosen Testphase.

Leave a Reply