Transkript
Matthias: [00:00:09.53] Hallo und herzlich willkommen bei der Macht der Craft. Ich bin Matthias
Alex: [00:00:13.70] Und ich bin Alex.
Matthias: [00:00:14.84] Schön, dass ihr da seid.
Alex: [00:00:17.00] Wenn du git verwendest oder eine andere Versionsverwaltung. Dann ist diese Folge was für dich. Wir beschäftigen uns heute mit einem Thema, dem manchmal zu wenig Beachtung geschenkt wird. Commit-Nachrichten.
Alex: [00:00:28.88] Die Sache ist nicht unbedingt neu, aber in meinen Augen durchaus aktuell, wichtig und interessant. Darüber hinaus machen wir einen kleinen Abstecher zum Thema Versionsnummern.
Alex: [00:00:40.16] Am Ende des Artikels, weißt du, was diese Commit-Nachrichten sind, warum sie wichtig sind und kennst ein paar Mittel und Wege, um sie besser zu gestalten. Das versetzt dich in der Lage, die Teaminterne Kommunikation zu verbessern, eine technische Dokumentation deines Projekts on the fly zu erstellen und ein paar andere Vorteile daraus zu ziehen, die wir euch später weitergeben.
Off: [00:01:00.89] Die Macht der Craft arbeitet für dich.
Alex: [00:01:05.76] Als erstes können wir uns von Matthias erzählen lassen, was ihm so mal passiert ist.
Matthias: [00:01:12.45] Und es ist noch gar nicht so lang her. Es ist eine recht aktuelle Geschichte sogar, und zwar, wie sich letztes Weihnachten zugetragen. Bei uns in der Firma ist Weihnachten traditionell eher so ein Zeitraum, wo so gut wie niemand im Büro ist. Und deswegen ist es nicht unüblich, dass man auch mal alleine ist. Und dieses Jahr, also 2020, hat es mich erwischt.
Matthias: [00:01:35.70] Ich kam also nach meinem Urlaub zurück ins Büro. Wir haben gerade ein neues Projekt angefangen, wo noch einiges unklar war, Dinge ausprobiert worden sind, hier ein paar Experimentier-Branches und dort ein paar andere Experimentier-Branches.
Matthias: [00:01:52.20] Manche wurden gemerged, manche nicht. So und dann kam ich aus meinem Urlaub zurück und habe als erstes meine E-Mails gecheckt und war positiv überrascht von meinen Kollegen E-Mails bekommen zu haben, wo mir der aktuelle Stand vermittelt werden sollte. Wie es in dem Projekt steht, welche Entscheidungen getroffen worden sind, wo die Reise hingeht.
Matthias: [00:02:12.45] Leider hat mir die Information aus den E-Mails nur bedingt geholfen, weil als ich dann mich dran machen wollte, an dem Projekt zu arbeiten und Tickets umzusetzen, sind mir ein paar Ungereimtheiten aufgefallen.
Matthias: [00:02:26.37] Dinge, die in der E-Mail als erledigt oder fertig deklariert worden sind, waren laut Issues noch nicht erledigt. Hingen noch in Doing, es waren noch Leute dran gehangen.
Matthias: [00:02:38.94] Es gab noch offene Merge Requests dafür und jetzt saß ich dann erst mal da, hatte keine meine Kolleginnen, an die ich mich wenden könnte, also fragen könnte, wie es denn ist, ob da jetzt was noch gemacht werden muss oder ob das eigentlich schon fertig ist und nur noch nicht gemerged wurde.
Matthias: [00:02:55.26] Das heißt, ich hatte leider das Pech, dass ich mich meinen ersten Tag nach meinem Urlaub eigentlich nur mit der git History auseinandergesetzt habe.
Matthias: [00:03:05.13] Codezeilen mir angeguckt habe, Diffs von vorher nachher, um dann mit dem gefährlichen Wissen oder gefährlichen Halbwissen, dass ich mir damit angeeignet habe, eigentlich zu entscheiden, ob an dieser Aufgabe noch etwas gemacht werden muss oder nicht.
Matthias: [00:03:21.69] Und ja, wie man sich denken kann, hat es meine Laune nicht besonders positiv beeinflusst. Und ich habe daraufhin in unserem internen Team-Board, dass wir für Dinge haben, die uns stören, direkt ein Ticket aufgemacht, weil ich mir gedacht habe, das will ich nie wieder erleben, dass ich aus dem Urlaub zurückkomme und eigentlich nicht arbeiten kann, weil zu viele Unklarheiten da sind.
Matthias: [00:03:50.37] Das Problem letztendlich haben wir dann im Team auch besprochen und haben uns dann überlegt, wie wir dieses Problem in den Griff bekommen könnten. Und es hat sich dann relativ schnell herauskristallisiert, dass schon vieles besser gewesen wäre, wenn die Commit-Nachrichten für die unterschiedlichen Issues, die wir halt so hatten, zu dem Zeitpunkt besser geschrieben worden wären.
Matthias: [00:04:18.42] Weil ich weiß nicht wie es anderen geht, aber mir geht es immer so, ich finde Commit Messages zu schreiben ist echt nicht leicht und häufig geht man leider den falschen Weg und schreibt nichtssagende Nachrichten, die niemanden weiterhelfen und eigentlich nur dafür geschrieben werden, um eine Maschine glücklich zu machen, weil eine Commit Message halt nicht leer sein darf.
Matthias: [00:04:43.95] Irgendetwas muss halt drinstehen. Genau daran haben wir uns im Team überlegt. Wie könnten wir das besser machen? Haben da letztendlich dann auch einen Weg gefunden. Deswegen haben wir uns gedacht Möchten wir jetzt mal mit euch oder euch davon erzählen, wie das genau abgelaufen ist, auf was wir uns geeinigt haben und wo die Reise letztendlich damit hingehen kann.
Alex: [00:05:07.47] Ich finde die Geschichte interessant, weil es zeigt, das Commit-Nachrichten durchaus einen Wert haben und dass man sie nutzen kann, um sich besser zu verständigen, um auch Sachen klarer darzustellen, ohne unbedingt jede Zeile im Code durchschauen zu müssen.
Alex: [00:05:25.51] Also wenn du mit git arbeitest, kennst du Commit-Nachrichten mit Sicherheit. In andere Tools verwendet man auch solche Nachrichten, die man beim Committen oder beim Check-In oder wie das auch in den speziellen Tool heißt, machen oder angeben muss.
Alex: [00:05:40.66] Für manche Leute ist das ein notwendiges Übel. Halt irgendwas, das man machen muss. Mein Gott, dann machen wir mal was rein. Andere Leute finden es aber sinnvoll und hilfreich, da anständige Nachrichten reinzutun.
Alex: [00:05:52.84] Ich gehört zu der zweiten Sorte. Nicht nur Aufgrund der Geschichte, die Matthias gerade erzählt hat, sondern auch, weil es hilft für andere Sachen, nicht nur für den Kolleginnen, obwohl Teamkollegen zu helfen durchaus wichtig ist.
Alex: [00:06:06.91] Gute Commit-Nachrichten bringen uns größere Vorteile und wir sollten diese auch nutzen. Dafür eignen sich einige Konventionen, welche uns am Ende des Tages die Arbeit erleichtern können.
Alex: [00:06:19.42] Warum haben wir euch diese Geschichte erzählt? Was versteckt sich hinter dieser Geschichte? Warum ist sie wichtig? Oder warum ich sie relevant?
Matthias: [00:06:27.13] Also in meinen Augen ist sie relevant, weil ich tatsächlich also ich meine, es ist jetzt eine sehr egoistische Perspektive, aber ich habe mindestens ein, wenn nicht sogar zwei Tage Arbeit darin versenkt, überhaupt den Punkt zu finden, wo ich weitermachen kann.
Matthias: [00:06:41.44] Also letztendlich hat das Geld gekostet. Wenn man komplett offen und ehrlich ist und das könnte man vermeiden, wenn man halt bessere Commit-Nachrichten schreibt. Also jetzt ich meine, es ist natürlich auch ein Sonderfall, der da eingetreten ist. Kommt halt jetzt nicht jeden Tag vor, dass jemand alleine an einem Projekt arbeitet, wo vorher fünf andere eine Woche lang gearbeitet haben oder so.
Matthias: [00:07:05.83] Aber es ist halt trotzdem auch wenn du zum Beispiel neu in ein Projekt reinkommst, ist es in meinen Augen unglaublich wertvoll, wenn man eine gepflegte git History hat oder auch ein anderes System. Aber wenn man aufgrund von der Versionsverwaltung einfach nachvollziehen kann, was ist passiert? Ja genau.
Alex: [00:07:26.53] Die Commit-Historie ist eigentlich die Summe aller Commit-Nachrichten in einem Projekt und sie kann genutzt werden als Werkzeug in der Entwicklung, denn sie hilft uns zu verstehen, wie das Projekt fortschreitet. Sie zeigt uns, was sich geändert hat, wie es sich geändert hat und warum. Sie verrät uns, welche neue Funktionalitäten dazugekommen sind und welche Mehrwert darin geschafft wurde.
Alex: [00:07:51.43] Sie ist nützlich, wenn wir in ein neues Projekt einsteigen, wie du gesagt hast oder auf Fehlersuche sind oder einen Review vornehmen müssen, weil dann siehst du in den Commits, was tatsächlich passiert ist. Ich habe in meinem Leben schon sehr viele grässliche Commits gehört, gelesen, sogar hab ich selber manche geschrieben, wo ich mich jetzt schämen müsste.
Matthias: [00:08:10.78] Ich glaube, davon können sich die wenigsten freisprechen
Alex: [00:08:14.65] Und wir sollen auch da eine gewisse Qualität einfließen lassen. Aber wie definiere ich einen schlechten Commit?
Matthias: [00:08:21.82] Ja also ich mein solche committen Nachrichten hat bestimmt schon mal jeder gesehen. „Fix Typo“. „Add Test“. Solche Geschichten, die einfach keinerlei Mehrwert bringen, kann man sich eigentlich komplett sparen und ganz häufig ist es zumindest in meiner eigenen Erfahrung, weil wie gesagt, ich möchte mich davon gar nicht freisprechen, dass ich nie solche Commit-Messages geschrieben habe.
Matthias: [00:08:42.79] Häufig ist es halt tatsächlich einfach Faulheit bzw. die Schwierigkeit, die Änderung in Worte zu fassen. Das ist vielleicht auch schon ein Problem und da sollte man eventuell dann einfach nochmal einen Schritt zurücktreten und versuchen es besser machen zu können.
Alex: [00:09:01.66] Okay, andere Sachen, die ich auch gesehen habe, sind vor allem, als ich mit TFS gearbeitet habe, war, dass man einfach einen Punkt eingetragen hat, als Nachricht, weil irgendetwas mussten wir eintragen. Die Nachricht dürfte nicht leer sein, also haben wir einfach einen Punkt reingeschoben, fertig, aus. Aber auch wie du gesagt hast. Texte wie „Klasse hinzugefügt“ oder „Button XYZ an eine andere Position hingestellt“.
Matthias: [00:09:27.31] Genau.
Alex: [00:09:28.36] Der Inhalt der Nachricht sagt mir nichts. Ne? Was soll ich daraus lernen? Was sagen mir diese Nachrichten? Wie kann ich aus diesen Beispiele irgendeine Information rausziehen, warum irgendwas passiert ist und helfen nicht, zu verstehen, also helfen überhaupt nicht zu verstehen, was tatsächlich passiert im Projekt?
Matthias: [00:09:45.46] Genau. Gutes Beispiel zum Beispiel auch sowas wie „CSS Klasse geändert“. Ja, was hilft mir diese Nachricht? Ich weiß nicht, welche CSS Klasse. Ich weiß nicht, warum sie geändert wurde. Es hilft einfach niemandem. Das ist einfach eine tatsächlich wertlose Nachricht. Aber grundlegend würde ich einfach sagen Offensichtliches muss nicht in einer Commit Message.
Matthias: [00:10:09.58] Weil ich habe ja zusätzlich zu meiner Commit Message, habe ich ja auch noch die Dateien zum Beispiel, die sich geändert haben. Das heißt, wenn ich einfach nur eine Testklasse hinzugefügt habe, dann sehe ich das schon auf Grund von der Testklasse, die dazugekommen ist und muss nicht zumindest ausschließlich nur schreiben „Edit test class“ oder so. Es hilft halt nicht.
Alex: [00:10:33.77] Ja. Hast du sonst irgendwelche Sachen, dass in die Commit-Nachrichten nicht gehören?
Matthias: [00:10:38.54] Nee, das sind so die hauptsächlichen Geschichten für mich.
Alex: [00:10:43.22] Wir wissen jetzt, was wir nicht reintun sollen. Wie sieht es also mit einer Commit-Nachricht, die den Namen auch verdient? Welche Informationen gehören da rein? Wie formatiere ich sie. Fangen wir an z.B. mit der Formulierung der Nachricht?
Alex: [00:10:58.19] Eines was ich gelernt habe ist, dass die Commit-Nachrichten in Imperativ Präsens, heißt glaub ich auf Deutsch, geschrieben werden und nicht in die Vergangenheitsform. Also wir stellen in der Commit-Nachricht, was wir tun und nicht was wir getan haben.
Matthias: [00:11:16.04] Jaja, ich weiß was du meinst. Kannst du auch erläutern, warum das nicht in der Vergangenheit geschrieben werden sollte?
Alex: [00:11:23.31] Eben auf den Grund. In der Commit-Nachricht beschreiben wir, was das Commit tut.
Matthias: [00:11:28.25] Also letztendlich, wenn man sich vorstellt wie… Du kannst ja einen Commit auch immer wieder anwenden, sozusagen. Und dann ist das ja quasi die Aktion, die durchgeführt wird und nicht wurde. So würde ich es mir persönlich erklären.
Alex: [00:11:42.95] Ja und abgesehen davon, wenn man mit git arbeitet, passt auch sehr gut zu den formatierten Nachrichten von git. Git verwendet auch die Präsens-Form, um die Commit-Nachrichten zu beschreiben. Also passt gut einfach zueinander und es hilft eine einheitliche Formulierung der Nachricht zu verwenden.
Alex: [00:12:03.40] Was ich jetzt noch angehen würde, ist welche Format die Nachricht haben soll. Es gibt unterschiedliche Möglichkeiten die Nachricht zu schreiben, und ich habe im Laufe der Zeit gemerkt, dass es ein bestimmtes Format sich ziemlich etabliert, in der Entwickler-Community.
Alex: [00:12:18.85] Die Nachricht wird in zwei Bereichen aufgeteilt. Betreffzeile und eine Beschreibung, die durch eine Leerzeile getrennt werden. Im Betreff ist kurz, 50 bis 70 Zeichen lang. Wo wir deutlich angeben, was sich geändert hat. Was ändern wir da? Dazu gibt es die Beschreibung, in dem wir dann detailliert auf die Änderungen eingehen.
Matthias: [00:12:42.58] Bei der Beschreibung würde ich tatsächlich hervorheben, dass da klar herauskommen sollte, warum eine Änderung durchgeführt worden ist, also der, wie soll ich sagen, auf Englisch wäre es der Intent, also die Absicht. Also warum wird diese Änderung durchgeführt. Einfach um den ganzen Kontext zu geben.
Alex: [00:13:01.03] Ja, finde ich auch eine wichtige Sache. Aber ich wollte jetzt eher dran eingehen, dass wir, eben dieser Betreff haben, kurze Zeile, klar, deutlich, plakativ. Was ändert dieses Commit? Dann eine Leerzeile und dann eine längere Beschreibung mit eine ganze Menge an Informationen, die wir jetzt dann gleich besprechen werden. Was gehört alles da drin? Was können wir alles da drin tun?
Alex: [00:13:26.35] Mir ist wichtig noch zu erwähnen, dass diese Trennung durch die Leerzeilen ist wichtig, weil wenn du dir die Commit-Nachrichten anzeigst, wird normalerweise nur die erste Zeile angezeigt. Es sei, du sagst, du willst die komplette Nachricht sehen und deswegen ist es wichtig, dass dieser Betreff so plakativ und eindeutig ist, dass mir in einem kurzen Satz erklärt: Was macht dieses Commit?
Alex: [00:13:51.22] Wenn ich mehr Informationen haben will oder brauche, dann kann ich mir die Details und die komplette Beschreibung dann anzeigen lassen. Aber wenn der Betreff schon so gut gewählt ist, dass ich das nicht brauche, dann spare ich mir auch Zeit. Nichtsdestotrotz müssen wir einen ziemlichen Effort reinstecken, in ordentliche Beschreibungen vor eine Commit-Nachricht anzulegen. Was denkst du dazu?
Matthias: [00:14:13.42] Ja, absolut. Bei mir selber ist mir auch aufgefallen, dass ich mittlerweile viel mehr drüber nachdenke, was ich committe auch welche Dateien ich zusammen commite, weil es z.B. wenn ich jetzt keine Ahnung 30 Dateien geändert habe, dann ist es unfassbar schwierig, schon mal eine kurze Zusammenfassung in 50 bis 70 Zeichen, wie du gesagt hast, zu finden, die überhaupt diese Änderung beschreibt.
Matthias: [00:14:41.62] Das heißt, ich habe mir persönlich angewöhnt, viel kleinere Commits zu machen, die viel klarer definiert sind. Also meistens ist es dann tatsächlich irgendwie eine Anpassung an einer Klasse, der entsprechende Test dazu und das war es dann. Die beiden Dateien werden entsprechend commitet. Und da finde ich, ist es relativ einfach, diese ganzen Sachen, die wir gerade besprochen haben, einzuhalten.
Matthias: [00:15:08.41] Aber je größer der Commit wird, desto schwieriger wird das. Und das sind dann auch die Momente, wo es mir selber immer aufgefallen ist an mir selbst, früher, wo man dazu tendiert, nichtssagende Texte zu schreiben, weil es einfach Fakt ist, du kannst diese riesige Änderung aus 30 Dateien und was weiß ich wie viele hundert Zeilen gar nicht sinnvoll beschreiben. Es geht nicht.
Alex: [00:15:34.06] Was gehört alles in die Beschreibung rein? Ich hätte da ein paar Ideen.
Matthias: [00:15:38.71] Die kurze Beschreibung oder die lange?
Alex: [00:15:40.84] Die längere.
Matthias: [00:15:41.96] Okay.
Alex: [00:15:42.88] Die kurze ist für mich einfach der Betreff, die Betreffzeile. In eine Beschreibung packen wir alles, was wir brauchen, um zu verstehen, was sich mit dem Commit ändert. Alle Informationen, die notwendig sind. Sie sollte so kurz wie möglich sein, aber so lange wie nötig. Wie gesagt, alle Informationen, die dazugehören. Da gibt’s eine ganze Latte an Möglichkeiten, an Sachen, die man da reinschreiben kann.
Alex: [00:16:08.77] Ich würde zum Beispiel damit anfangen zu beschreiben Was ist das Problem? Warum ist diese Commit überhaupt notwendig? Was hat dazu geführt, dass wir diese Änderungen machen müssen? Welche Funktionalität fügen wir hinzu oder welche Änderungen nehmen wir vor? und was hat das für ein Mehrwert?
Matthias: [00:16:26.20] Und was nehmen wir unter Umständen dafür in Kauf? Weil häufig ist es ja auch so, dass man irgendwelche Änderungen machen muss, mit denen man nicht super glücklich ist. Aber es geht vielleicht in dem Moment nicht anders. Auch sowas kann man in einer Beschreibung festhalten.
Alex: [00:16:44.83] Ja, klar, natürlich. Auch ist wichtig, diese Fragen zu beantworten, damit ich ein Gefühl bekomme, was sich ändert und warum. Wie du vorher gesagt hast wichtig ist das Warum. Warum mussten wir das ändern? Das setzt einen Rahmen um die ganze Änderung, sodass ich verstehen kann, warum sie notwendig ist.
Alex: [00:17:03.19] Dann gibt es weitere Informationen, die man reintun kann, wie z.B. wie haben wir die Änderung durchgeführt. Haben wir irgendwelche Patterns verwendet? Was haben wir für Objekte und Methoden verwendet, um die Implementierung durchzuführen? Vor allem, warum wir es so gemacht haben.
Alex: [00:17:18.91] Auch was du gerade so erwähnt hattest. Wenn wir einen Lösungsweg einschlagen, warum haben wir den gewählt und eventuell was haben wir uns damit eingekauft? Welche Waschmaschine kriegen wir jetzt?
Matthias: [00:17:31.93] Obwohl wir eine Spülmaschine brauchen …
Alex: [00:17:34.93] Ja, also, diese Sachen festzuhalten. Okay, wir wissen, es war nicht die Lösung fürs Leben oder wir müssen da noch Nacharbeiten liefern oder wir haben in irgendwelche technische Schulden eingefügt. Das festzulegen, mit reinzuschreiben, hilft auch für den Verständnis. Vor allem, weil wenn wir committen, wissen wir, warum wir das gemacht haben.
Alex: [00:17:54.73] Aber möglicherweise nach ein paar Wochen oder wenn ein andere Teamkollege, die nicht involviert war in die Implementierung, sich das anschaut. Weiß nicht, warum es so passiert ist und es kann ihm helfen zu verstehen, warum der Code jetzt so aussieht, wie es aussieht. Wenn er weiß, warum wir das gemacht haben oder warum wir das so gemacht haben?
Matthias: [00:18:13.09] Ich glaube, viele machen wir sowas mit Kommentaren im Code. Also versuchen über Kommentare quasi zu vermitteln, warum an einer Stelle etwas so oder so gelöst wurde. Würdest du da irgendwo ein Vorteil von Commit-Messages gegenüber dieser Kommentar-Methode sehen?
Alex: [00:18:32.95] Ich bin kein großer Freund von Kommentare, als Dokumentationsmethode, weil sie neigen dazu, sich nicht zu verändern. Ich schreibe einen Kommentar_ „Das hab ich so und so gemacht. Auf den und den Grund“, dann ändert sich die Implementierung irgendwann, aber keine passt das Kommentar.
Matthias: [00:18:51.35] Genau. Aber das ist ja das schöne an Commit Messages, weil sie ja zu dem Zeitpunkt, zu dem sie gemacht worden sind, wahr sind. Immer.
Alex: [00:19:01.33] Genau, und wenn ich mir die Commit Historie anschaue. Dann taucht der Commit an der Position, wo sie hingehört und zu dem Zeitpunkt ist die Aussage auch treffend. Und wenn sich irgendetwas ändert, dann sehe ich es später. Deswegen würde ich von Kommentare für solche Sachen zumindest absehen, wo ich das …
Matthias: [00:19:17.32] Würde ich tatsächlich auch genau aus dem Grund, weil sie einfach nie mit dem Code mitgeändert oder sagen mir nicht nie, aber seltenst mit dem Code mitgeändert werden, für den sie geschrieben worden sind. Daher eigentlich sehr oft lügen. tatsächlich. Und das ist das Schlimmste in meinen Augen, wenn man sich auf Code oder jetzt in dem Fall dann Kommentare nicht verlassen kann.
Alex: [00:19:42.83] Ja, bin voll bei dir. Eine weitere Sache, die ich aber auch gerne in Commit Nachrichten sehe oder sehen würde ist, ob noch offene Baustellen sind. Das heißt, wie wir bereits gesagt haben, es kann sein, wir nehmen eine Lösung, weil es jetzt ausreichend ist, weil wir der Meinung sind, dass es für das, was wir jetzt machen müssen, passt.
Alex: [00:20:02.14] Die aber bestimmte Themen nicht zu 100 prozent abdeckt. Oder wir haben Sachen, die wir wissentlich offen lassen und das reinzuschreiben z.B. Wir haben XYZ gemacht und wir haben der Normalfall oder der 80 Prozent Fall jetzt implementiert und bitte darauf achten. Wir müssen noch den Error Handling halt mal genauer beschreiben und genauer implementieren und wenn es fest ist.
Alex: [00:20:29.26] Am besten mach ich gleich ein Ticket in mein git oder in GitLab oder wo auch immer ich meine Tickets verwalte, verlinke ich es mit dem Commit, die ich gerade machen will, sodass in der Nachricht ich sehen kann. Okay, es gibt das und das, was noch zu tun ist. Und es wurde schon in den Ticketsystem hinterlegt, z.B. damit wir es einplanen, wenn der PO mal der Meinung ist, es wäre wichtig genug.
Matthias: [00:20:54.61] Genau.
Alex: [00:20:55.81] Das ist für mich auch eine wichtige Sache, die man angeben kann und musste. Wenn man die Gelegenheit hat, nämlich klarstellen ist die Änderung abgeschlossen oder nicht abgeschlossen und falls nicht was fehlt. Würde dir das helfen?
Matthias: [00:21:12.22] Absolut, ja, also ich glaube Weihnachten hätte ich mich vor Freude nicht mehr eingekriegt. Wenn ich so was gehabt hätte. Wäre ein Weihnachtsgeschenk gewesen für mich.
Alex: [00:21:21.70] Machen wir alles, nur für dich. Genau 🙂
Matthias: [00:21:24.40] Nee, finde ich. Ja, ist richtig. Also würde ich auch so sagen, wenn quasi von der Sache, die ich gerade mache und mit dem Commit erledigt habe, noch weitere Aufgaben hervorgehen, dann sehe ich das haargenau so. Issues, Tickets dazu anlegen und am besten in der Commit Message direkt drauf verlinken.
Alex: [00:21:48.13] Wir haben jetzt eine ganze Latte an Sachen beschrieben, die man eingeben kann, die man eintragen kann, die man gegebenenfalls auch eintragen sollte. Natürlich müssen nicht immer alle diese Informationen vorhanden sein. Das wäre ja Dummfug.
Alex: [00:22:00.85] Das sind halt nur ein paar Tipps und ein paar Richtlinien, wie man das machen kann. Auf jeden Fall, haben wir aber damit einen runden Bild, ohne im Code nachschauen zu müssen, was in diesem Commit passiert.
Alex: [00:22:12.28] Um es mal kurz zusammenzufassen, würde ich sagen, dass in der Beschreibung packen wir alles rein, was wir brauchen, um die Änderungen zu verstehen und gegebenenfalls nachprüfen zu können, ohne woanders schauen zu müssen. Nur auf die Nachricht selber.
Matthias: [00:22:27.31] Würdest du den Teil der Commit Message als den wichtigsten Teil sehen?
Alex: [00:22:32.89] Ich bin da ein bisschen hin und her gerissen. Der Betreff, ein guten Betreff zu finden, die in kurz in einem Satz beschreibt was ich gemacht habe, ist sehr wichtig. Aber da es manchmal schwierig ist, in so einen kurzen Satz alle Informationen rein zu tun, die notwendig sind, um tatsächlich zu verstehen, was wir gemacht haben, ist für mich die Beschreibung der Ort, wo das Gesamtwissen und der Wissensaustausch zwischen uns passiert.
Alex: [00:23:10.81] „Wir schreiben jetzt ein neuer Artikel, weil es wichtig ist, über das Thema Commit-Nachrichten zu reden.“ Und dann in die Beschreibungen kann ich erklären, warum es wichtig ist, oder warum wir das so machen, warum wir es nicht anders machen und so weiter. Das macht die Sache halt einfach rund und gib mir die notwendigen Informationen, um tatsächlich zu verstehen.
Alex: [00:23:31.87] Der Betreff ist eher so, dass Headliner, was passiert. Die Schlagzeile, genau.
Matthias: [00:23:39.22] Genau. Also bei dem Betreff oder ja genau bei der Kurzbeschreibung, Betreff, wie man es auch nennen will, will ich eigentlich für mich jetzt herauslesen können, ob ich in die lange Beschreibung reinschauen muss oder nicht.
Matthias: [00:23:54.91] Also ob es mich so sehr interessiert, dass ich den Commit mir näher anschaue oder ob das jetzt z.B. ein Teil des Systems betrifft, der gerade für das, was ich machen will, überhaupt nicht relevant ist.
Alex: [00:24:07.00] Genau, wenn ich auf auf Bug-Suche bin, ja, das Betreff soll helfen auf einem Blick zu sehen: „Könnte das Problem, das ich suche, sich in diesen Commit verstecken?“
Matthias: [00:24:17.17] Genau.
Alex: [00:24:18.02] Ja. Und wenn ich sage ja, anhand des Betreffs und die Dateien, die sich geändert haben, dann guck ich genau in die Beschreibung rein, um zu wissen, was tatsächlich passiert ist, bevor ich in den Code gehe. Weil eventuell sehe ich schon gleich bei der Beschreibung: „Na, das kann nicht sein“. Da brauche ich mir die 50 oder 60 Zeilen Code jetzt nicht anschauen, weil das brauche ich jetzt nicht.
Matthias: [00:24:37.03] Aber wenn ich z.B. irgendwie einen Fehler in einer Preisberechnung suche und ich stolpere über eine Commit Kurzbeschreibung: „Anpassung der, was weiß ich, Steuerlogik“ oder sowas ist vielleicht ein interessanter Punkt, würde ich reingehen und würde mir dann näher anschauen was steht in der Beschreibung, was wurde genau geändert und warum wurde es geändert?
Matthias: [00:24:59.96] Dann kann ich nämlich auch näher bestimmen und selbst wenn sich dann der Bug da drin versteckt, weiß ich zumindest, was das Ziel war, dass mit der Änderung erreicht werden sollte und kann dahingehend dann den Bugfix auch eventuell besser machen.
Alex: [00:25:17.86] Ja. Bin voll deiner Meinung. Eine Sache, die ich öfters auch in Commit-Nachrichten sehe, sind weitere Informationen, die angegeben werden in Form von Verweise auf externe Systeme. Ein guter Beispiel ist z.B. die Verlinkung auf dem Ticket in mein Ticketing System, die diese Änderungen zugrunde liegt.
Alex: [00:25:36.53] Hinter den Referenzen stecken immer bestimmte Informationen und wenn sie wichtig sind, um die Änderungen zu verstehen. Dann müssen wir sie trotzdem auch in die Nachricht aufnehmen. Zumindest ein Teil davon, das wichtige, ein Resümee. Ich muss nicht alles reinschreiben, was ich in mein Ticket geschrieben habe, aber die Kerninformation müssten trotzdem in der Nachricht vorhanden sein. Und zwar aus zwei Gründen. Kannst du dir vorstellen, welche?
Matthias: [00:26:05.69] Du meinst der Verweis auf das zugehörige Ticket.
Alex: [00:26:09.33] Also ich hab den Verweis, den zugehörige Ticket oder irgendwelche andere Informationen in eine Commit-Nachricht hinterlegt. Warum sollte ich trotzdem die Kernaussage von diesem Ticket in meine Nachricht aufnehmen, obwohl ich sie eh sowieso schon verlinke?
Matthias: [00:26:26.45] Naja, also kann mir vieles vorstellen. Also zum einen ist es leichter für jemand, der sich nur die Commit Historie ansieht mehr Kontext zu bekommen ohne in das Ticketing-System zu gucken. Und zum anderen kann man unter Umständen auch ja Automatisierung damit eventuell… Obwohl ja nee, das ist Blödsinn.
Alex: [00:26:51.32] Tatsächlich. Das ist einer der Punkte, die in meiner Liste steht.
Matthias: [00:26:55.37] Automatisierung auf Grund von der von der Beschreibung in dem Ticket.
Alex: [00:26:59.96] Ja,
Matthias: [00:27:00.86] Okay. Interessant, ist also, wie gesagt, es kam mir auch in den Kopf, aber irgendwie, als ich es ausgesprochen habe, kam es mir irgendwie falsch vor. Aber ich bin gespannt.
Alex: [00:27:11.48] Ganz kurze Erklärung. Es gibt für mich zwei grundlegende Motive, um das zu machen. Das Erste ist, dass es denkbar ist, dass ich in dem Ticket viel mehr Informationen hinterlegen möchte, als ich in meine Commit-Nachrichten reintun will.
Alex: [00:27:26.81] Deswegen in die Commit-Nachricht, nur die Kerninformationen, wie wir vorher erwähnt haben, so kurz wie möglich und dann die Referenz für weitere Informationen noch reinzupacken. Und der zweite Grund ist tatsächlich automatisierte Auswertungen. Diese Referenzen können maschinell ausgewertet werden. Zum Beispiel…
Matthias: [00:27:45.77] Die Referenzen. Ja stimmt. Klar, ich ich hatte jetzt im Kopf irgendwie, dass du die Kernaussage des Tickets gemeint hast.
Alex: [00:27:53.99] Na na, na, na, na. Ich meinte die Referenz.
Matthias: [00:27:56.66] Ah ja, weil… Da macht es dann auf einmal wieder Klick in meinem Kopf. Und das macht Sinn. Weil klar, ich kann ja z.B. Wenn es sich um ein Bug-Ticket handelt oder sowas, kann ich die Zeit z.B. messen, die zwischen Eröffnung und Schließung des Tickets hängt und das ist um einiges leichter, wenn ich die Referenz auf das Ticket in meiner Git-History habe.
Alex: [00:28:21.95] Es hilft meiner Meinung nach ungemein, wenn ich diese Verlinkungen zum Beispiel in Ticketing System verfolgen kann ohne ewig lang suchen zu müssen, solche Sachen. Das sind für mich die zwei Grundmotive warum ich Referenzen reintue.
Alex: [00:28:37.49] Und das wichtige Grund, warum ich trotzdem diese Kernaussage in der Nachricht mit aufnehme, ist, dass es kann ja passieren, dass ich mit dem Commit arbeite und ich habe gerade aber keine Möglichkeit, diese Verlinkungen aufzumachen, weil das System jetzt gerade nicht da ist oder ich kein Netzwerk habe, oder was auch immer, dass ich auf diese externen Referenzen nicht zugreifen kann.
Alex: [00:28:59.60] Und dann ist es super, wenn zumindest diese Kernaussage oder diese Kerninformationen mit in der Nachricht aufgenommen sind. Abgesehen davon wenn ich nichts mehr brauche als diese Kernaussage, dann brauche ich nicht zu den externen System zu wechseln.
Matthias: [00:29:16.10] Ja, Macht Sinn.
Alex: [00:29:18.02] Wir können jetzt auf das Thema zurückkehren, die du vorher kurz angesprochen hattest. Commit-Größe. Wie groß soll ein Commit sein? Deine Bühne.
Matthias: [00:29:30.31] Meine Bühne? Also in meinen Augen möglichst klein, natürlich. Vor allem, wenn wir uns innerhalb von einem Feature-Branch, Bugfix-Branche oder was auch immer bewegen.
Matthias: [00:29:41.74] Anders sieht es häufig aus, wenn gemerged wird, weil dann hast du naturgemäß einen Merge Commit oder ähnliches, der dann natürlich größer ist. Aber wenn ich jetzt in meiner täglichen Arbeit an dem Feature arbeite, dann ist meine übliche Größe von einem Commit tatsächlich sehr klein, nämlich das Hinzufügen eines neuen Tests und die Implementierung des neuen Tests.
Matthias: [00:30:06.24] Zumindest versuche ich es so zu machen. Klappt nicht immer. Häufig ist es halt dann doch mal ein bisschen mit … Na, kommt man vom Weg ab und hat dann vielleicht doch ein paar mehr Dateien angefasst. Manchmal schaffe ich es dann tatsächlich, auch wenn ich mich ans Committen macht, nochmal aufzuteilen.
Matthias: [00:30:26.31] Ich gehe dann eh nochmal alle meine Änderungen durch, bevor ich committe, um erstmal zu schauen, ob überhaupt nur das drin ist, was ich auch wirklich committen will. Genau. Aber alles in allem versuche ich sie möglichst klein zu halten und habe damit eigentlich auch ganz gute Erfahrungen gemacht.
Matthias: [00:30:43.14] Wichtig in meinen Augen ist, man sollte möglichst nur commiten, wenn das System funktioniert, also alle Tests z.B. grün sind. Das wäre ein guter Zeitpunkt zum commiten.
Alex: [00:30:57.68] Ja.
Matthias: [00:30:58.95] Kurz noch Hintergrund dazu, ist in meinen Augen einfach, ich will gefahrlos zu jeder Stelle zurückkehren können, ohne mir Sorgen machen zu müssen, dass irgendetwas gar nicht funktioniert.
Alex: [00:31:13.10] Ja, das bringt mich auch zum Grübeln. Und zwar, weil ich öfters das Problem habe, dass meine Commits einfach viel zu groß sind. Aber was bedeutet eigentlich viel zu groß? Naja, eigentlich ist es so, dass ich habe entweder mehrere Änderungen auf einmal hinzugefügt oder die Änderungen, die ich vornehmen wollte, war von vornherein viel zu groß.
Alex: [00:31:35.58] Gegen diese zwei Probleme versuche ich anzugehen, und zwar für das erste Problem: mehrere Änderungen auf einmal gemacht, und Sachen, die eigentlich nichts miteinander zu tun haben. Wie du gesagt hast, ich versuche die Commits so aneinander abzustimmen, dass sie in einen Commit nur Änderungen sind die zusammenhängen.
Alex: [00:31:59.88] Änderungen, die nicht miteinander zu tun haben, oder die funktional abgetrennt sind voneinander, sollten in unterschiedliche Commits reingepackt werden. Auch wenn ich sie gleichzeitig gemacht habe. Und zwar weil ich dann eine ganz genauere Beschreibung machen kann, wenn ich sie trenne, als wenn ich sie zusammen tue. Das hilft schon mal dabei, sie kleiner zu halten.
Alex: [00:32:22.10] Das zweite Thema, nämlich die Änderung, die wir machen wollten, war von vorneherein viel zu groß. Aber haben wir viel zu viel reingepackt. Kann ja ein vorgelagertes Problems sein. Tickets mit zu viel Inhalt.
Matthias: [00:32:35.54] Kenne ich.
Alex: [00:32:36.11] Und ja, dann müssen wir eben die Tickets irgendwie kleiner machen, kleiner aufteilen, kleine Tickets auf die Reihe kriegen, die voneinander abgetrennt sind. Damit ist das Problem auch bereinigt.
Alex: [00:32:49.49] Ich habe aber auch zigtausend Mal gehört: “ Ja, das Ticket kann man aber nicht kleiner machen, weil sonst keinen Wert hat“. Das höre ich öfters. Und das kann ich mir tatsächlich nicht immer erklären, warum dem so ist. Aber auch dann haben wir die Möglichkeit, nicht alles auf einmal zu commiten, sondern wie du vorher sehr gut erzählt hast, einfach nur ein Teil der Implementierung machen, die wir mit Tests abdecken.
Alex: [00:33:15.65] Wenn alle Tests grün sind und wir diese Teil der Implementierung haben, dann einfach committen und dann mit der nächste Teil weitermachen. Gleiche Vorgehensweise. Rund machen. Tests. Alles Mögliche. Wenn wir sicher sind es passt, dann einchecken und so weiter. Und so können wir auch eine größere Änderung in kleinere Commits aufteilen.
Matthias: [00:33:37.46] Genau. Und wie gesagt, letztendlich. Also falls einem dann trotzdem alles zu viel ist, gibt es ja auch immer noch die Möglichkeit im Nachgang die komplette Historie ein bisschen zu tweaken, Commits zusammenzufassen und solche Geschichten. Aber das geht wahrscheinlich jetzt dann zu weit.
Alex: [00:33:56.62] Ja, das ist cheaten, machen wir es lieber gleich richtig.
Matthias: [00:34:00.20] Naja, was heißt cheaten? Also ich finde schon… Also wenn man jetzt, wie ich jetzt vorhin gesagt hat, im Test hinzufügt und die Implementierung dazu macht und das mach ich halt 10 mal oder so. Bei einer Klasse finde ich es persönlich nicht gecheatet, wenn ich am Ende dieser 10 Commits sage alles in allem kann ich das in einem Commit zusammenfassen,
Matthias: [00:34:23.15] Weil ich kann die Funktionalität, die ich in dieser Klasse implementiert habe, in der Kurzbeschreibung so zusammenfassen, dass jeder sieht, was passiert ist. Und in der langen Beschreibung kann ich ja so viel schreiben, also zu viel schreiben wie ich will in Anführungszeichen.
Matthias: [00:34:38.18] Aber klar, es gibt auch Situationen, wo vielleicht ist das squashen von Commits nicht das Schönste ist aber es gibt Situationen, wo es eine Berechtigung hat.
Alex: [00:34:48.83] Ja, natürlich. Das kann ja auch sein. Also wir müssen nicht immer die Commits kleiner machen, als sie sind. Manchmal macht es durchaus Sinn, ein Commit etwas größer zu machen, wenn wir im Nachhinein festlegen, dass die Sachen zusammengehören, ja.
Matthias: [00:35:03.02] Zusammengehören. Das ist der wichtige Punkt, glaube ich. Also in einem Commit sollten einfach nur Sachen sein, die zu einer Geschichte gehören und nicht über 5 Teile in dem System verteilt.
Matthias: [00:35:16.01] Irgendwie da eine Tabellenspalte in der Datenbank hinzugefügt, da ein bisschen CSS verändert und dahinten vielleicht noch irgendwie eine komplett neue Klasse hinzugefügt. Das werde ich niemals so vereinheitlichen können, dass es eine sinnvolle Commit-Nachricht geben kann.
Alex: [00:35:34.12] Also um es auf den Punkt zu bringen, würde ich sagen nutze lieber kleinere unabhängige Commits anstatt größere mit verschiedenen Abhängigkeiten.
Alex: [00:35:45.14] Ich denke, das wäre jetzt der richtige Zeitpunkt, um eins drauf zu legen und uns ein bisschen über Conventional Commits zu unterhalten, was das ist, wofür das gut sein soll. Möchtest du anfangen?
Matthias: [00:35:59.39] Ach nee, mach nur. Quasi dein Lieblingsthema.
Alex: [00:36:03.84] Ja, mit allem, was wir bis jetzt erzählt haben, kann man eigentlich schon ganz coole, ganz gute Commit-Nachrichten verfassen und schreiben, die inhaltlich auch top sind. Die wir einen guten Inhalt und die Informationen beinhalten, die wir tatsächlich brauchen.
Alex: [00:36:22.00] Mit Conventional Commits setzt man noch eins drauf.
Alex: [00:36:25.90] Wir haben es bei uns ausprobiert und meiner Meinung nach haben wir so die Next Level Commit-Nachricht auf die Reihe gekriegt.
Alex: [00:36:34.15] Aber was sind eigentlich Conventional Commits? Conventional Commits ist eine einfache Konvention, welche das Format der Commit-Nachricht beschreibt.
Matthias: [00:36:42.94] Also sozusagen eine eigene Standardisierung. Ein Versuch einer Standardisierung, wie man Commit Messages schreiben könnte.
Alex: [00:36:50.68] Es ist eine Konvention, die man sich im Team geben kann oder auf Unternehmensebene, wie auch immer. Wir machen das für unser Team z.B. Haben wir gesagt Okay, wir verwenden Conventional Commits für unsere Nachrichten und das machen wir jetzt einfach.
Alex: [00:37:05.44] Die Struktur ist sehr ähnlich wie die, die wir vorher vorgestellt haben. Erinnerst du dich? Dieses Teil mit den zwei Bereichen durch eine Leerzeile getrennt: Betreff und Beschreibung. Also im Großen und Ganzen kommt nicht viel mehr dazu. Aber einiges.
Alex: [00:37:24.46] Vor allem wie die Formatierung aussieht, ist in Teilen etwas unterschiedlich. Auf www.conventional-commits.org findest die Dokumentation dafür. Da gibt’s weitere Details und ein paar Beispiele, wie das funktioniert. Aber im Groben kann ich jetzt mal das durchgehen.
Alex: [00:37:43.68] Wie sieht es denn also mit der Struktur? Also anstatt zwei Bereiche: Betreff und Beschreibung, gibt es drei Bereiche. Die erste zwei bleiben dieselben, nämlich die Betreffzeile und die Beschreibung aber es gibt einen zusätzlichen Bereich mit dem Fussnoten.
Alex: [00:38:03.30] So, das mit Referenzen oder zusätzliche Informationen geben wir nicht in der Beschreibung, sondern gesammelt in einem Bereich, die Coventional Commits Fußnoten nennt.
Alex: [00:38:15.88] Fangen wir mit dem einfachen Teil nämlich die Beschreibung. Für die Beschreibung des Commits, gilt das Gleiche, was mir bis jetzt erzählt haben. All die Informationen, die wir vorher erwähnt haben, gehören weiterhin da rein.
Alex: [00:38:30.07] Was sich ein bisschen verändert ist das Format der Betreffzeile und das Thema mit dem Fußnoten.
Alex: [00:38:36.97] Betreffzeile fängt dann immer an mit dem Änderungstyp, die wir durchführen. Es gibt zwei fixe Änderungstypen, die wir immer verwenden. Das ist: Feat und Fix. Feat steht für Feature und Fix halt für Fix. Und Feat verwenden wir, wenn wir neue Funktionalität hinzufügen, ein neues Feature reinbringen. Fix verwenden wir, wenn wir Fehlerkorrekturen machen.
Alex: [00:39:05.51] Warum diese zwei? Das hängt mit semver oder mit Semantic Versioning. Dazu sprechen wir später noch ein bisschen, was das ist, wofür das gut ist und hängt mir der automatische Vergabe von Versionsnummern oder von der Versionierung zusammen.
Alex: [00:39:23.17] Also wie gesagt, als erstes der Änderungstyp angeben. Feat für Features, Fix für Korrekturen. Das heißt aber nicht, dass wir nur die zwei benutzen dürfen. Die zwei sind muss. Sie muss jetzt gehen und die müssen wir verwenden.
Alex: [00:39:37.99] Wir können aber auch viele andere Änderungstypen erfinden oder verwenden. Paar Beispiele, die wir gerne öfters verwenden, ist z.B. Docs, wenn wir Dokumentation anpassen. Test, wenn wir nur Tests geändert haben oder an den Test geschraubt haben. Refactoring, wenn wir ein refactor gemacht haben.
Alex: [00:39:57.08] Also es gibt sehr viele unterschiedliche mögliche Änderungstypen. Da muss man sich im Team einig sein, welche man verwenden will. Auf die Conventional Commits Seite werden auch weitere genannt, die man verwenden kann.
Alex: [00:40:12.97] Ich finde es eine gute Idee, sie auch zu nutzen, weil nicht alles was wir im Code machen sind einfach Bug-Korrekturen oder neue Features hinzufügen, sondern gibt es viele andere Themen, die wir machen.
Matthias: [00:40:25.85] Genau. Wird wahrscheinlich auch immer mehr werden. Thema Devops und so.. Also ich sehe hier auch, dass es ein CI zum Beispiel gibt als Vorschlag. Style, also wenn dann irgendwie mal wieder der Linter oder sowas, bei einem JavaScript Projekt meckert, ist es dann eine Style Anpassung. Genau da gibt’s eine ganze Reihe.
Alex: [00:40:50.88] Ja, es gibt einfach sehr viele. Und wie gesagt, wichtig ist, dass wir uns im Team halt absprechen und sagen okay, die 5, 10, 15 verwenden wir und das sind unsere Pool an Änderungstypen, die wir verwenden.
Alex: [00:41:04.93] Aber wir sind immer noch bei der Betreffzeile und wir sind noch gar nicht fertig. Wir haben ja nur gesagt, was für eine Änderung wir gemacht haben.
Alex: [00:41:13.57] Als nächstes sagen wir oder geben wir an, in welchem Bereich wir die Änderungen durchgeführt haben. Der Bereich wird in runden Klammern angegeben und da haben wir freie Wahl.
Matthias: [00:41:24.22] Hier kann man sich ja auch im Team ja überlegen, sowas wie Frontend, Backend zum Beispiel haben will.
Alex: [00:41:31.48] Man kann auch Klassennamen oder Feature-Namen oder Bereich-Namen oder Microservices-Namen verwenden. Alles mögliche. Es ist alles gut. Wenn ich zum Beispiel die Konfigurationsdateien angepasst habe, ist Configuration vielleicht ein guter Kandidat.
Alex: [00:41:50.05] Wenn ich an Kafka-Anbindung arbeite, dann gebe ich Kafka vielleicht an. Also das muss man aber auch im Team halt mal absprechen, was mir da für Sachen verwenden können. Gibt aber seitens der Konvention keine feste Regeln.
Matthias: [00:42:04.06] Welchen Mehrwert würdest du bei der Angabe von Scope hervorheben wollen?
Alex: [00:42:09.50] Was mir jetzt so einfällt, ist, wenn wir tatsächlich automatisierte Auswertungen fahren, um wir uns auf bestimmte Bereiche festgelegt haben, dann können wir Auswertungen fahren, welche Bereiche, wann betroffen sind und so weiter.
Matthias: [00:42:26.12] Ich persönlich würde sogar sagen, dass das sogar noch ein Punkt, den wir vorhin schon genannt haben, unterstützt. Wie du vorhin gesagt hast. Das ich mir wünsche, dass so eine Kurzbeschreibung mir hilft zu entscheiden, ob ich überhaupt in die lange Beschreibung rein will oder nicht.
Matthias: [00:42:43.07] Und je nachdem, wie man diese Scopes halt wählt, finde ich, hilft es nochmal zusätzlich, weil wenn ich lese der Scope ist keine Ahnung, das betrifft jetzt, wie du gerade gesagt hast, Kafka. Aber das Problem, das ich gerade untersuch, ist ganz woanders, nämlich irgendwie ja irgendeine REST-Schnittstelle nach außen oder so… Hilft es mir auch gleich zu sagen okay, der Commit interessiert mich nicht. Nächster Commit.
Alex: [00:43:09.17] Sehr sehr sehr gut erkannt. Sehr gut gesagt. Finde ich auch.
Alex: [00:43:14.15] Nichtsdestotrotz ist das nicht das letzte, was wir in der Betreffzeile angeben, sondern nach den Scope in klammern, falls man ein Scope angeben will. Wie gesagt, es ist nicht Pflicht, hilft aber in meinen Augen. Kommt ein Doppelpunkt, ein Leerzeichen und dann die kurze Betreffzeile, also das, was wir in unsere ursprüngliche Formatierung gesagt haben, kommt jetzt hier wieder zum Tragen.
Alex: [00:43:38.79] Schreiben also Änderungstyp, dann in Klammern Änderungsbereich, Doppelpunkt, Leerzeichen und dann die, diese Betreffzeile. Die ganz kurze, prägnante, deutliche Aussage: Was passiert in dem Commit?
Alex: [00:43:57.53] Bei der Beschreibung hab ich schon gesagt kommt alles zum Tragen, was wir schon erwähnt haben, das Warum, das Wie. Und all diese Informationen, die wir schon erwähnt hatten,
Matthias: [00:44:08.00] Da ist auch das das wichtigste die Leerzeile oder zwischen Betreff und der Zusammen…, Beschreibung.
Alex: [00:44:14.87] Ja, es ist wichtig, um sie zu trennen. Optisch aber auch, wie gesagt, diese Conventional Commits sind auch teilweise gedacht, damit man eine Struktur in der Commit Nachricht reinbringt, damit man Nachrichten auch automatisiert parsen kann, wenn man es will.
Alex: [00:44:30.86] Aber gut, wie gesagt, die Beschreibung beliebig langer Text. Und hier kommt alles zum Tragen, was wir vorher für für bessere Commit-Nachricht erzählt haben.
Alex: [00:44:43.87] Damit wären wir bei den dritten Teil der Commit-Nachricht angekommen, nämlich die Fußzeilen. Und in diese Fußzeilen kommen all diese externen Referenzen und Zusatzinformationen. Jede Art von Zusatzinformationen kann hier angegeben werden. Es muss nur ein bestimmten Format haben.
Alex: [00:45:06.97] Es gibt Key-Value Pairs, also es werden… Diese Fußzeile werden als Key-Value Pair angegeben, in dem man den Schlüssel dann Doppelpunkt Leerzeichen und dann einen beliebigen Text, kann z.B. sein Reviewed -By Doppelpunkt Leerzeichen und der Name des Reviewers, so kleine Information.
Alex: [00:45:25.72] Aber auch die zweite Möglichkeit eine Zusatzinformation anzugeben. Auch mit eine zweite Formatierung, die aus der Git-Geschichte entsteht, wäre einfach ein Text einzugeben, ein Leerzeichen, dann die Raute und den Issue-Nummer. Das verwendet man auch sehr oft.
Matthias: [00:45:47.60] Genau. Häufig erkennen solche Systeme ja dann auch, dass irgendetwas passieren muss mit dem Issue. Also ich kenne es von GitLab z.B., dass wenn man da bestimmte Syntax verwendet, also sowas wie Closes Raute Issue-Nummer, dass dann auch wenn das gemerged wurde z.B. das Ticket geschlossen wird.
Alex: [00:46:11.34] Jawohl, so ist es. Also mal kurz nochmal Die Fußnoten sind alle Zusatzinformationen, die wir uns vorstellen können oder wir der Meinung sind, dass wir sie brauchen. Es gibt zwei unterschiedliche Formatierungen: Schlüssel, Doppelpunkt, Leerzeichen und dann die Information, die wir geben wollen oder Text, Leerzeichen, Raute und die Issue-Nummer. Z.B. Closes Wie du vorher gesagt hast ja. Closes. Raute 1 2 3 4.
Alex: [00:46:41.36] Ein Extra gibt es noch. Es ist eine ganz coole Sache, wie ich finde. Wenn deine Anpassungen dazu führen, dass die öffentliche Schnittstelle deiner Anwendung sich verändert. Das ist eine sogenannte Breaking Change.
Alex: [00:46:57.44] Dann willst du das auch in deiner Commit-Nachricht angeben. Es muss in die Commit-Nachricht deutlich sein, dass dieser Commit ein Breaking Change verursacht.
Alex: [00:47:07.65] Dafür gibt dir Conventional Commits auch zwei Möglichkeiten, das zu tun. Die eine ist eine Fußnote mit ganz bestimmte Formatierung, die fängt mit den Worten oder mit dem Wort BREAKING-CHANGE. Dann Doppelpunkt Leerzeichen und eine Erklärung, warum der Breaking Change oder was für ein Breaking Change wir eingeführt haben.
Alex: [00:47:27.87] Es kann viel detaillierter in die Beschreibung geklärt werden, aber wichtig, einfach da einzutragen: BREAKING-CHANGE, Doppelpunkt, Leerzeichen und dann was war dieser Breaking Change.
Alex: [00:47:39.93] Das ist die einfachere Möglichkeit. Das sieht man sofort, weil wenn man die, sich die Nachricht anschaut samt Beschreibung. Man steht dort prominent. Große Buchstaben. BREAKING-CHANGE. Super. Aber das hilft uns leider nicht, wenn wir uns nur den Betreff anzeigen lassen.
Alex: [00:47:59.67] Ja, wenn ich den Betreff nur sehe, dann sehe ich das nicht, weil die Fußzeilen werden nicht angezeigt. Dafür haben Sie sich auch was ausgedacht, nämlich nachdem ich den Scope oder den Bereich angegeben habe. Ein Ausrufezeichen, Ausrufezeichen Schreiben vor dem Doppelpunkt.
Alex: [00:48:17.97] Dann weiß ich, wenn ich den Betreff oder die Betreffzeile mir anschaue und da irgendwas steht, wo Ausrufezeichen Doppelpunkt hat, vor den Text, dass das eben ein Breaking Change ist.
Alex: [00:48:29.90] Wie gesagt, Beispiele und alles könnt ihr euch in den Conventional Commits Seiten anschauen. Wir hängen die Links dann weiter unten in den Notes. Was denkst du darüber?
Matthias: [00:48:41.01] Meinst du jetzt über Conventional Commits?
Alex: [00:48:42.69] Ja.
Matthias: [00:48:43.86] Finde ich eine, eine super Sache. Und haben sie mir mittlerweile sehr angewöhnt. Also ich benutze das eigentlich nur noch. Es hilft mir einfach bessere Commit Messages zu schreiben, weil ich meine, wie wir es jetzt schon häufiger heute erwähnt haben.
Matthias: [00:49:00.66] Es hilft einen zum einen, sich selber auch bewusster zu sein, welche Anpassungen man macht. Für mich werden die Commits kleiner, weil ich dadurch, dass ich ja schon weiß, dass ich alles besser beschreiben will, automatisch auch weniger. – Ja, also mir viel bewusster Änderungen vornehme, als ich es vorher gemacht habe.
Matthias: [00:49:25.59] In meinen Augen macht man sich dann auch außerdem natürlich viel mehr Gedanken über den Inhalt des Commits. Kann jetzt z.B. ein Unbeteiligter, der an der Aufgabe nicht mitgearbeitet hat, kann der aufgrund von der Commit Message nachvollziehen, was sich da verändert hat?
Matthias: [00:49:41.67] Und ja, Automatisierung. Ich bin ein großer Fan davon und Conventional Commits öffnen einen halt, eine Vielzahl an Möglichkeiten in der Hinsicht. Ich meine, wie gesagt auf semver werden wir dann noch ein bisschen eingehen. Dafür sind Conventional Commits halt wirklich ein sehr sehr mächtiges Tool.
Alex: [00:50:02.16] Was sagst du dann, wenn der Kollege kommt, oder wer auch immer kommt und sagt jeder: Das kostet aber ewig viel Zeit.
Matthias: [00:50:08.97] Es kostet halt auch ewig viel Zeit das Zeug nachzuvollziehen, wenn es keine gute Commit Message gibt. Und ja, es passiert nicht jeden Tag, dass man sich vielleicht durch die Commit Historie von dem gesamten Branch durcharbeiten muss, aber wie ich in der einleitenden Geschichte erzählt habe.
Matthias: [00:50:29.31] Mich hat zwei Tage gekostet. Und man kann einfach mal rechnen, was das kostet, wenn ein Entwickler zwei Tage nichts anderes macht, als Code Zeile für Zeile durchzugehen. Commit Messages zu versuchen, Sinn rauszuziehen. Also in meinen Augen spart das eher Geld auf lange Sicht.
Alex: [00:50:54.09] Ok. Eine andere Möglichkeit, die ich kenne für Leute, die tatsächlich sehr viele Commits machen oder die sagen für jede einzelne Commit, ist vielleicht das nicht zielführend, das zu machen, ist die Möglichkeit des squashen oder die Möglichkeit, bei Merge Requests die gesamte Commit-Nachrichten zusammenzufassen.
Alex: [00:51:16.71] In einen Merge Request packe ich mehrere Commit-Nachrichten oder mehrere Commits zusammen, um sie dann in einer anderen Branch zu mergen und dass wir dort, in dieser Merge Request, eine extra Nachricht verfasse, die diese Conventional Commits Konventionen macht und beachtet und nicht jede einzelne Commit damit belasten.
Alex: [00:51:37.14] Ich bin eher dafür, das in jedem Commit zu machen, aber ist auch eine Möglichkeit es handzuhaben, also alle Commits normal zu commiten und dann die Merge Requests so klein zu schneiden, dass wieder das tatsächlich thematisch nur eine einem Feature oder einen Fix oder in einem Bereich betreffen.
Alex: [00:51:55.83] Und dann diese Aufwand, die Informationen zusammenzufassen, detaillierter darzustellen, nur dort gemacht werden. Ich halte es für nicht so gut, weil wenn ich den Merge Request mache, sind manchmal Stunden oder ein, zwei Tage vergangen und ich hab 10 oder 15 Commits gemacht und das alles zusammenzufassen. Dauert manchmal länger, als wenn ich jede einzelne Commit entsprechend …
Matthias: [00:52:19.26] Sinnvoll mache.
Alex: [00:52:20.22] Ja hingestellt habe.
Matthias: [00:52:22.23] Sowieso kann das ja jeder handhaben, wie er möchte. Wir wollen und werden eigentlich auch nur unsere Erfahrungen teilen an der Stelle.
Alex: [00:52:30.21] Jawohl, natürlich. Aber Gut, das war so kurz eine Einführung in diese Conventional Commits und jetzt erzählt euch Matthias ein bisschen über semver oder Semantic Versioning. Was ist das?
Matthias: [00:52:42.99] Ja Semantic Versioning. Genau. Ja, es ist eigentlich ein ganz cooles System, wie man ja, Software, Libraries, was auch immer, versionieren kann. APIs letztendlich auch. Und gesehen hat es wahrscheinlich schon mal jeder, weil letztendlich sieht das ganz normal wie jede andere Versionsnummer auch aus.
Matthias: [00:53:04.44] Klassischerweise bestehen die aus drei Stellen, z.B. eine 1.0.0 sozusagen dieses klassische erste Major Release. Und jede Stelle, die durch einen Punkt getrennt ist, hat halt eine bestimmte Bedeutung. Die sind dann von links nach rechts. Also die erste Stelle beschreibt die Major Version.
Matthias: [00:53:27.42] Die mittlere Stelle beschreibt die Minor Version und die letzte Stelle beschreibt die Patch Version. Und je nachdem, was für eine Anpassung ich an meine Software durchführe, werde ich dann bei einem Release die entsprechende Versionsnummer hochzählen.
Matthias: [00:53:47.61] Habe ich jetzt z.B. eben ein Bugfix, was ja hin und wieder mal vorkommt, dann werde ich die letzte Stelle der Versionsnummer hochzählen. Dann wird aus 1.0.0, wird dann ein 1.0.1.
Matthias: [00:54:03.93] Wenn ich neue Funktionalität zu meiner Software hinzufüge, die keinen Fehler behebt, sondern wirklich neue Funktionalität hinzufügt, aber keine Breaking Changes beinhaltet, dann werde ich die mittlere, die Minor Version, erhöhen. Also dann würde aus dem 1.0.1 würde dann ein 1.1.1 werden.
Matthias: [00:54:28.08] Und die Major Version, die erhöhe ich, wenn ich Funktionalität hinzufüge, die Breaking Changes beinhaltet, bedeutet meine offene Schnittstelle nach außen, also das Public Interface verändert sich so dramatisch, dass Clients, die meine Software benutzen, kaputt gehen werden.
Matthias: [00:54:49.41] Das ist jetzt mal so die der grobe Überblick.
Alex: [00:54:54.16] Okay, lass mir mal kurz zusammenfassen. Also die Versionsnummer wird aus drei Zahlen durch Punkte getrennt dargestellt. Major Punkt Minor Punkt Patch und abhängig von den Änderungen, die ich im Code durchgeführt habe, setze ich eine von diesen Zahlen hoch.
Alex: [00:55:14.83] Wie du gesagt hast, bin ich Bugfixes mach dann der Patch Version, wenn ich neue Features hinzufüge, Minor Version und wenn ich Breaking Changes oder Änderungen an meinem öffentlichen Interface gemacht habe, dann die Major Version.
Alex: [00:55:30.40] Richtig. Hab ich das richtig …?
Matthias: [00:55:31.48] Exakt.
Alex: [00:55:32.35] Und was ich wenn ich mehrere von diese Änderungen …, also ich bringe jetzt ein Release eine Release-Version raus und ich habe 10 Bugfix korrigiert, ein Feature hinzugefügt und dann auch noch ein zusätzlichen Feature, die aber eine Änderung der Interface bedeutet hat.
Alex: [00:55:49.81] Was mache ich da? Muss ich alle drei hochsetzen?
Matthias: [00:55:53.11] Also ich würde in dem Fall den du gerade beschrieben hast eine 2.0.0 veröffentlichen.
Alex: [00:55:58.36] Alles klar. Also. Wir nehmen immer die größere. Sozusagen.
Alex: [00:56:02.14] Genau. Also sobald Breaking Changes vorhanden sind, muss ich die Major Version hoch setzen. Und so gesehen ist es ja eine eigenständige Version meiner Software.
Matthias: [00:56:15.51] Also ich könnte ja beide Versionen weiterführen und dann wird es keinen Sinn machen, nur weil ich mit dem 2.0 Release auch einen Patch gefixt habe, da gleich ein 2.0.1 draus zu machen, weil letztendlich das ist ja ein neues, ja, neues Release sozusagen, Major Release.
Alex: [00:56:35.88] Heißt also wenn ich ein Release mache und z.B. die Major Version anpassen muss, weil ich Breaking Changes hatte und ich bin bei der Version 1.5.7, ist meine nächste Version, die 2.0.0
Matthias: [00:56:50.40] Würde ich so sagen.
Alex: [00:56:51.57] Okay, also ich setze der Major Version hoch und dann alle andere wieder, fange ich von 0 an. Und wenn ich mit der Minor Version das mache zum Beispiel von 1.5.7, wäre die nächste Minor Version 1.6.0.
Matthias: [00:57:08.40] Genau. Auch wenn mit diesem 1.6.0 Release ein Bug gefixt wird, der in 1.5.7 existiert hat.
Alex: [00:57:17.31] Alles klar, ok, verstanden.
Matthias: [00:57:19.35] Weil wieder, ich könnte ja rein theoretisch. Also will nicht sagen, dass das die Regel ist. Aber ich könnte ja rein theoretisch auch eine 1.5.8 veröffentlichen, weil aus welchem Grund auch immer, Leute das weiter benutzen wollen, die 1.5 Version aber dieser Patch so dringend ist, weil es zum Beispiel ein Sicherheitsloch stopft. Das heißt, ich will ja auf mehreren Versionen unterschiedliche Aktionen durchführen, unter Umständen.
Alex: [00:57:49.20] Alles klar, ja. Hast du sonst irgendetwas von semver?
Matthias: [00:57:53.28] Naja also es war jetzt quasi das wie und jetzt ist halt dann noch so die Frage des Warum. Also warum will ich das machen oder warum will ich das andere das machen? Weil ist ja nicht nur so, dass ich den Benutzern meiner Software quasi die Vorzüge von Semantic Versioning geben will, sondern ich will ja unter Umständen das auch nutzen.
Matthias: [00:58:17.61] Und wenn ich weiß, dass jetzt eine Software, die ich selber in meinem Projekt nutze, Semantic Versioning benutzt und auch durchzieht, dann bringt mir das halt insofern Mehrwert, dass ich z.b., wenn eine neue Version veröffentlicht wird, ich auf Anhieb sehen kann, um was für eine Art von Änderungen handelt es sich.
Matthias: [00:58:36.75] Also muss ich mit Breaking Changes rechnen, wenn ich dieses Update einspiele, kann ich es vielleicht, wenn es einfach nur Minor Update ist, einfach relativ sorgenfrei einspielen oder muss ich es einspielen, weil es sich um eine Patch Version handelt? Oder sollte ich es einspielen? Ich mein, muss ist so ein starkes Wort aber sollte ich es einspielen.
Alex: [00:58:59.70] Du meinst, wenn ich jetzt das richtig verstehe, das anhand der Versionsnummer oder die neue Versionsnummer, die ich bekomme, kann ich auf Anhieb sehen, wie sehr ich aufpassen muss bei dem Update.
Matthias: [00:59:14.55] Genau. Also ich kann ungefähr abschätzen, wie groß der Aufwand sein wird, dieses Update einzuspielen. Also es gibt ja durchaus Tools, die einem unterstützen bei seinen Projekten herauszufinden: gibt es für Libraries, die ich z.B. einsetze, neue Versionen.
Matthias: [00:59:34.44] Diese Tools können unter Umständen einem, was weiß ich, eine E-Mail schreiben, mit: „Hier für folgende Pakete gibt es neue Versionen“ Und dann kann ich halt z.B. mir diese Liste anschauen und sehe relativ leicht,
Matthias: [00:59:48.75] also vorausgesetzt, eben die Semantic Versioning wird dann auch entsprechend durchgesetzt, wie gefährlich ein Update ist oder wie unproblematisch es sein wird. Oder, eben auch, im Falle von, von Patch oder Bugfixes wie wichtig.
Matthias: [01:00:06.72] Also beides ist halt unter Umständen nicht so wichtig. Ein neue Minor Version einzuspielen, weil jetzt das Feature, dass da dazugekommen ist, mir überhaupt nichts bringt. Ich würde es eh nicht benutzen, also hab ich keinen Grund von Version 1.5.0 z.B. auf 1.6.0 hoch zu gehen, weil ich benutze es eh nicht.
Matthias: [01:00:28.20] Ist es aber von 1.5.0 auf 1.5.1, ist es halt relativ wahrscheinlich, dass der Bugfix mich betrifft und dann will ich, will ich das wahrscheinlich einspielen.
Alex: [01:00:42.48] Okay. Ja, mach Sinn, klingt sinnvoll. Und in welchem Zusammenhang steht das alles mit unseren Conventional Commits?
Matthias: [01:00:51.96] Naja, wenn wir uns überlegen, wie wir die Conventional Commits aufgebaut haben, kann man aus diesen Conventional Commits herauslesen, um was für eine Änderung es sich handelt.
Matthias: [01:01:05.64] Also jetzt mal als ganz simples Beispiel, wenn ich in einer Commit Message, die Information finde, dass es Breaking Change gibt, ist es ein Major Release, das daraus resultieren muss, weil es gibt Breaking Changes.
Matthias: [01:01:23.07] Fängt meine Commit Message mit fix an, wie wir ja vorhin gesagt haben. Gleich das erste Zeichen in der Betreffzeile, wäre ja dann, das erste Wort wäre dann fix. Das würde für eine Patch Version sprechen.
Matthias: [01:01:36.72] Im Gegensatz dazu dann natürlich das Keyword Feature oder feat für möglicherweise Minor, solange nicht in Zusammenhang mit Breaking Change, also man sieht schon, man kann aus so einer Conventional Commit Message sehr viel rauslesen und gerade im Bezug auf Semantic Versioning da auch sehr viel automatisieren.
Matthias: [01:01:58.96] Also es gibt auch libs, die einen da unterstützen wieder, mal für alles was es so gibt, hat wahrscheinlich schon irgendwer irgendwas entwickelt. Die eben genau das machen und aufgrund von Conventional Commit Messages automatisch, also das ist jetzt in dem Beispiel, die mir bekannt ist JavaScript und dann eben in der package.json automatisch die Version entsprechend setzen.
Alex: [01:02:24.33] Ja, klingt wie eine tolle Sache.
Matthias: [01:02:26.73] Ja, es ist auch, ist ziemlich cool.
Alex: [01:02:30.73] Jetzt steht dir nicht mehr im Weg, um Commit-Nachrichten mit super Qualität zu schreiben. Sie werden dir und dein Team helfen, die Historie leichter zu verstehen und als extra Geschenk bekommst du dazu eine Dokumentation über das Leben deines Projekts.
Alex: [01:02:45.73] Es ist echt eine coole Sache, was man da alles rauslesen kann. Wenn, wenn man ordentliche Commit-Nachrichten hat. Das alleine ist schon nicht zu vernachlässigen, aber dazu können wir anhand von dieser Historie zusätzliche Mehrwerte erzielen.
Alex: [01:03:02.56] Für uns, für die Entwickler, indem wir z.B. Changelogs, man kann ein Parser verwenden, die dir ein Changelog generiert. Für ein Release, halt sich alle Commit-Nachrichten anzeigt und die entsprechend ordentlich aufbereitet.
Alex: [01:03:19.33] Oder auch, wie wir gerade gesehen haben. Für die Versionsnummer-Vergabe, dass diese Versionsnummer-Änderungen automatisch passiert, im Hintergrund, anhand der Inhalten von unsere Conventional Commit Nachrichten. Meiner Meinung nach lohnt sich der Aufwand, das alles zu betreiben.
Matthias: [01:03:39.77] Failure-Rates ist auch so eine Geschichte. Da kann man wirklich viel mit machen.
Alex: [01:03:46.84] Das wäre eigentlich für Heute. Ich hoffe, ihr hattet Spaß dabei und habt was gelernt über Commit und Commit-Nachrichten und warum sie wichtig sind.
Matthias: [01:03:55.97] Ja, und wir hoffen natürlich, dass wir euch beim nächsten Mal wieder begrüßen dürfen.
Alex: [01:04:01.24] In drei Wochen ist unsere nächste Folge. Wir wissen noch nicht genau, was wir machen werden. Aber seid versichert, es wird irgendetwas, was mit Softwareentwicklung zu tun, was uns qualitativ weiterbringt.
Alex: [01:04:13.99] Wenn euch das, was wir erzählen, alles interessiert und keine Folgen verpassen wollt, abonniert einfach den Podcast. Ich wünsche euch noch viel Spaß. Eine schöne Zeit und bis bald.
Matthias: [01:04:24.46] Ciao
Off: [01:04:29.10] Die Macht der Kraft arbeitet für dich.