3 Gründe, warum Sie konventionelle Commits verwenden sollten

Einführung

Als Programmierer entwickeln Sie vielleicht eine Anwendung, eine Bibliothek, einen Microservice, einen Monorepo voller Dienste und Bibliotheken oder (Gott bewahre!) einen riesigen Monolithen. Unabhängig von der Art der Anwendung, die Sie entwickeln, werden Sie, wenn Sie es "richtig machen", eine Versionskontrolle verwenden (In 90% der Fälle wird dies mit git).

Die Frage ist - wie verwalten Sie Ihren Versionsverlauf? Wie melden Sie die Beseitigung von Fehlern, die Hinzufügung von Funktionen, die Erledigung einer Aufgabe im Arbeitsbereich oder sogar eine bahnbrechende Änderung? Und noch wichtiger, wie einfach ist es, das zu sehen?

Konventionelle Commits ist ein standardisierter Ansatz zur Versionskontrolle, der die Klarheit, Konsistenz und Zusammenarbeit zwischen Entwicklern verbessert. In diesem Beitrag erfahren Sie, was Conventional Commits sind, wie sie funktionieren und welche drei Hauptvorteile Sie durch ihre Verwendung erzielen.

Wie sehen Git-Nachrichten ohne Standards aus?

standard_commit_example

Das Bild oben zeigt eine übliche Git-Commit-Sequenz. Sie hat eine einzige klare Linie, was gut ist, aber eine Menge unbeantworteter Fragen übrig lässt. Was können wir aus den Commit-Meldungen erkennen? Was bedeutet fix path bedeutet? Welcher Pfad? In welcher Komponente?

Diese Frage lässt sich nicht beantworten, wenn man sich die Commit-Historie ansieht.

Auch eine Maschine kann das nicht tun. Merken Sie sich das für später.

Wie sieht es mit konventionellem Engagement aus?

Zum Vergleich: So sehen Commit-Nachrichten nach den Standards von Conventional Commit aus:

conventional_commit_example

Wenn wir uns nur die ersten beiden Informationen in jedem Commit ansehen, erfahren wir bereits sehr viel. Wenn wir von unten nach oben gehen, können wir sehen, dass eine Funktion zur fab Komponente hinzugefügt wurde, etwas in der Typografie behoben wurde, eine Funktion zum Datumspicker hinzugefügt wurde, etwas in der docs, eine weitere Funktion im Zusammenhang mit accordion item, und so weiter.

Sind Sie nicht auch der Meinung, dass unsere Meldungen jetzt klarer und anschaulicher sind, was die Veränderungen bei den einzelnen Vorstößen betrifft?

Aber Entwickler verbringen normalerweise nicht viel Zeit damit, sich Commit-Nachrichten anzusehen, oder? Schauen wir uns die wahre Leistung von Conventional Commits an.

Die Vorteile der Verwendung herkömmlicher Commits**

Herkömmliche Commits haben drei wesentliche Vorteile: automatisch generierte Änderungsprotokolle, automatische Versionierung und verbesserte Teamkommunikation.

1. Automatisch generierter Changelog

Es gibt viele Werkzeuge, die ein Änderungsprotokoll nach herkömmlichen Commits erstellen können. Ein Changelog sieht so aus:

vivids_auto_generated_changelog

Ist Ihnen schon aufgefallen, dass der Conventional Commit-Standard regelmäßige Commits in ein einfach zu lesendes Änderungsprotokoll verwandelt? Es wird sogar in Versionen mit Datum aufgeteilt, um neue Funktionen und Fehlerbehebungen aufzuspüren.

Wie kann es die Version kennen? Dies ist der nächste Vorteil.

2. Automatische Versionierung nach SemVer

Der Standard Conventional Commit ist wie folgt aufgebaut:

{type}({scope}): {description}

Der Typ gibt an, welche Art von Änderung vorgenommen wurde. Es gibt 3 Haupttypen: Funktionen, Korrekturen oder Aufgaben.

Die Website Geltungsbereich bezieht sich auf die Sache, die von dieser Änderung betroffen ist. Dies kann eine Komponente, eine Bibliothek, eine Anwendung oder ein Dienst sein.

Die Beschreibung beschreibt genauer, was geändert wurde.

Das ist das Wesentliche. Ich werde Sie nicht langweilen mit den vollständigen Spezifikationenlangweilen, aber ich empfehle Ihnen, sie zu lesen. Es ist kurz und macht Sinn.

Wie hilft uns das also bei der Versionskontrolle?

SemVer ist eine Möglichkeit, unsere Software zu versionieren. Die Version setzt sich aus 3 Ziffern zusammen: X.Y.Z.

X wird genannt Majorgenannt, Y heißt Minorund Z heißt Patch.

Wenn Sie eine bahnbrechende Änderung vornehmen, erhöhen Sie eine Hauptversion. Das bedeutet, dass sich die Schnittstelle dieses Bereichs geändert hat.

Wenn Sie eine neue Funktion hinzufügen (ohne bestehende zu zerstören), erhöhen Sie eine Nebenversion.

Wenn Sie einen Fehler beheben, ohne eine Funktion zu verändern, erhöhen Sie eine Patch-Version.

Sehen Sie, worauf wir hinauswollen?

Jetzt kann eine Maschine unsere Commits lesen und entscheiden, welche Version unser Bereich erhalten soll.

Und Sie müssen es nicht selbst tun. Da Conventional Commits ein Standard ist, gibt es viele Tools, die ein automatisches Änderungsprotokoll, eine automatische Versionierung und normalerweise beides anbieten.

Ein solches Werkzeug ist release-pleasedas auch über eine praktische Github-Aktion.

Förderung einer besseren Kommunikation im Team

Abgesehen davon, dass Commit-Nachrichten besser lesbar sind, gibt uns die Definition der Struktur noch etwas anderes. Sie gibt der Commit-Nachricht einen Kontext. Selbst wenn die Beschreibung mehist, weil die Art der Übergabe und ihr Umfang bekannt sind, kann der Leser zumindest erahnen, was auf ihn zukommt.

Schauen Sie sich dieses Beispiel an:

standarized_commits_example

Hier wird ein Versuch der Standardisierung unternommen. Dennoch kann ein Mensch, der sich das ansieht, weder nachvollziehen, welche Art von Änderung vorgenommen wurde (handelt es sich um eine Korrektur oder ein Feature?) noch an welcher Komponente. Auch ein Änderungsprotokoll lässt sich daraus nicht ableiten.

Wenn wir dies ein wenig ändern, sieht es wie folgt aus:

fix(button): verified 48 done and fixed 3 (#172/vivid-103)
feat(button): verified 2 and added demo example (#172/vivid-103)
chore(dialog): fixed 1/5 (font) (#172/vivid-103)

Das ist auch nicht viel besser, denn die Beschreibung ist nicht sehr aussagekräftig.

Andererseits, wenn man die Übergabe mit fix(button): {description} schreiben muss, ist es weniger wahrscheinlich, dass diese Person eine solche Beschreibung schreiben würde. Es ist wahrscheinlicher, dass eine Person die fix oder feat die auf dem button.

Wie immer hilft ein gewisser Standard den Menschen, die Dinge besser zu machen. Es ist ein bisschen wie die Theorie der zerbrochenen Fenster.

Versuchen Sie es. Sehen Sie, was passiert.

Beispiel aus der Produktion: Der Commit Message Standard von Vivid

Wir verwenden Conventional Commits im Designsystem von Vonage, Vivid.

Es hilft uns bei der Erstellung unseres Änderungsprotokoll und Versionsprotokoll und die automatische Bestimmung der Release-Version.

Außerdem sind unsere Commit-Meldungen seither viel besser geworden.

Aber unsere konventionelle Commit-Durchsetzung gilt nicht für jeden einzelnen Commit. Während der Entwicklung kann ein Entwickler so viele Commits mit einer beliebigen Nachricht hinzufügen, wie er möchte.

Wenn jemand einen Pull Request (PR) erstellt, erzwingen wir jedoch einen Conventional Commit für den Titel des Pull Requests:

github_commit_title_linter

Eine obligatorische Github-Aktion, die unseren PR-Titel verifiziert, folgt konventionellen Commits

Wir haben einen weiteren Standard hinzugefügt, der uns hilft, den Commit mit einem JIRA-Ticket zu verbinden. Jeder PR-Titel endet mit (VIV-XXX), wobei XXX die Ticketnummer ist. Zum Beispiel:

fix(disabled): adds a consistent cursor to disabled elements (VIV-999)

Schließlich wird in unserem Versionsprotokoll der VIV-XXX in einen Link zu JIRA umgewandelt:

convetional_commits_with_jira_links

Wenn ein PR schließlich zusammengeführt wird, wird der PR-Titel als Commit festgelegt. Wir verwenden squash + merge damit die gesamte Commit-Historie aus dem main Zweig entfernt wird und nur der Conventional Commit übrig bleibt. Das sieht dann so aus:

github_squash_and_merge_button

Wenn eine Pull-Anfrage mehr als eine Änderung enthält (mehr als eine Korrektur oder ein Feature), kann man sie immer in den Kommentaren des Merge Commits hinzufügen. Wir machen das folgendermaßen:

pr_with_multiple_commits

Das Conventional Commit Tool (in unserem Fall release-please) berücksichtigt diese Kommentare, als wären sie Teil der Nachricht.

Auf diese Weise wählen wir einen relativ lax Ansatz in Bezug auf Commit-Nachrichten und stellen sicher, dass der letzte Schritt darin besteht, die Änderung tatsächlich zu beschreiben.

Zusammenfassung

Herkömmliche Commits bieten zwei einfache Vorteile: ein automatisch generiertes Änderungsprotokoll und automatische Versionierung.

Es gibt viele Möglichkeiten, diese Ziele zu erreichen.

Ein solches Werkzeug ist Beachball. Dieses Tool verwendet eine CLI, die eine JSON-Datei erzeugt, anstatt die Git-Historie zu lesen. Der große Vorteil dabei ist, dass es viel einfacher ist, die Historie zu ändern, wenn man einen Fehler gemacht hat (das Ändern der Git-Historie kann ziemlich chaotisch sein...).

Abgesehen von diesen beiden eindeutigen und unmittelbaren Vorteilen, behaupte ich, dass es auch dazu beiträgt, die Menschen zu ermutigen, bessere Commit-Botschaften zu schreiben.

Ich könnte falsch liegen 🙂 Lassen Sie es mich auf unserem Vonage Community Slack oder senden Sie uns eine Nachricht auf X, früher bekannt als Twitter.

Zusätzliche Ressourcen

Systeme entwerfen: Lektionen von Vivid

Wie Softwaretests zur Kommunikation beitragen können

Eine Einführung in Git