GitHub – Eine praktische Einführung. Anke Lederer
Commit-Nachrichten bei GitHub bestehen aus zwei Teilen: dem Titel und einer (optionalen) detaillierteren Beschreibung. Den Titel solltest du immer aussagekräftig befüllen, damit jede und jeder (und auch du in ein paar Monaten) weiß, was du mit dem Commit bewirken wolltest. GitHub selbst gibt dazu folgende Empfehlungen, ergänzt um meine Tipps:
Der Commit-Titel sollte nicht mit einem Punkt aufhören, da es sich um eine Überschrift handelt.
Der Titel sollte nicht aus mehr als 50 Zeichen bestehen (Leerzeichen mitgezählt), siehe Abbildung 3-11.12 Für detailliertere Informationen dient darunter das Feld extended description (»erweiterte Beschreibung«).
Benutze aktive Sprache, keine passive, also »füge hinzu« anstatt »hinzugefügt« (im Englischen »add« anstatt »added«). Am einfachsten ist es, wenn man sich den Commit-Titel wie einen Befehl ans System denkt: »Ändere dies!«
Versuche, mit dem Titel deine Absicht auszudrücken.
Versuche, das Was und Warum zu beschreiben (z.B.: »Restrukturiere Modul A für bessere Lesbarkeit«).
Schreibe die Nachricht so, dass auch du sie in fünf Jahren noch verstehen kannst.
Abbildung 3-11: Wer mehr als 50 Zeichen eintippt, bekommt von GitHub einen entsprechenden Hinweis.
Ein schönes Zitat, das gut verdeutlicht, wieso präzise und klare Commit-Nachrichten so wichtig sind, ist Folgendes:
Jedes Softwareprojekt ist ein gemeinschaftliches Projekt. Es hat mindestens zwei Entwickler, den ursprünglichen Entwickler und den ursprünglichen Entwickler ein paar Wochen oder Monate später, wenn der Gedankengang längst den Bahnhof verlassen hat.
– Who-T, On commit messages, unter https://who-t.blogspot.com/2009/12/on-commit-messages.html (Übersetzung von deepl.com)
Nachdem du alle Änderungen dem Projekt hinzugefügt (bzw. committet) hast, gehe auf die Startseite des Projekts und bewundere das neue Erscheinungsbild. Genieße diesen Augenblick! Nichts ist so toll wie der erste Commit, der sofort auch optisch etwas verändert. Wenn du die README.md erneut anklickst, bekommst du noch ein paar Zusatzinformationen, wie beispielsweise die Anzahl der Mitwirkenden oder die Dateigröße (siehe Abbildung 3-12).
Abbildung 3-12: Durch Anklicken einer Datei erhält man weitere Zusatzinformationen.
SLOC
Vielleicht ist dir in Abbildung 3-12 die Zeile oben links aufgefallen:
6 lines (5 sloc) | 161 Bytes
Während die Angaben 6 lines (Anzahl der Zeilen) und 161 Bytes (Größe der Datei) vermutlich noch relativ eingängig sind, erscheinen die 5 sloc doch erst einmal ominös, oder? SLOC ausgeschrieben bedeutet Source Lines of Code (»Quellcodezeilen« oder auch »Anzahl der Programmzeilen«) und ist eine Metrik, um Software zu vermessen. Wenn du dir unseren Markdown-Text oben noch mal anschaust, siehst du, dass wir sechs Zeilen benutzt haben, aber nur in fünf Zeilen auch wirklich Inhalte (Source Lines) stehen. Das sind unsere SLOC.
SLOC werden häufig genutzt, um ein Gefühl für die Größe und Komplexität einer Software zu bekommen. Beispielsweise hat Windows XP 40 Millionen SLOC, der Linux-Kernel über 25 Millionen.13
SLOC sind übrigens kein Maßstab für Qualität oder Produktivität, auch wenn sie in Softwareprojekten hin und wieder als Messung für den Fortschritt angewendet werden. Gute Softwareentwicklung zeichnet sich unter anderem auch dadurch aus, dass Codezeilen vereinfacht (»umgeräumt«) oder auch mal entfernt werden14 und dass nicht nur immer mehr Code hinzugefügt wird. Das nachfolgende Zitat beschreibt das in meinen Augen ganz gut:
»Die Verwendung von SLOC zur Messung des Softwarefortschritts ist wie die Verwendung von kg zur Messung des Fortschritts bei der Flugzeugherstellung.«
– Autor*in unbekannt, angeblich Bill Gates
Wenn du dich genug an deinem Tun ergötzt hast, sollten wir einen Blick auf die Statistik für unser Projekt werfen (siehe Abbildung 3-13).
Vielleicht hast du schon bemerkt, dass sich die Anzahl der Commits auf deinem Projekt erhöht hat. Kein Wunder, du hast ja auch gerade deinen ersten gemacht. Eventuell wunderst du dich aber, dass da die Zahl 2 steht – schließlich war es ja gerade dein erster und nicht bereits der zweite Commit. Wir erinnern uns: Beim Anlegen des Repositorys haben wir GitHub gesagt, es möge für uns doch eine README.md anlegen – das war der erste Commit auf deinem Repo.15
Abbildung 3-13: Auf der Startseite eines Projekts ist die Gesamtanzahl aller Commits zu finden.
Herzlichen Glückwunsch, du hast dein erstes Repository angelegt und auch schon die erste Änderung vorgenommen. Jetzt wollen wir uns Issues und den Umgang damit anschauen.
Den ersten Ablauf üben – Issue anlegen und bearbeiten
Wir wissen aus Abschnitt »Informationen finden (interessierte Anwenderin)« auf Seite 13 in Kapitel 2 bereits, dass Issues Handlungsbedarf aufzeigen sollen (Fehler, Anfragen nach weiteren Funktionen – sogenannte Feature-Requests –, Anmerkungen etc.). Ich habe sie als eine Art offener Brief bezeichnet. Ein Issue ist aber viel mehr als ein einfacher Brief. Stell ihn dir als einen Zettel an einer Pinnwand vor – alle können diesen lesen und auch eigene Kommentare anbringen. Häufig entstehen rege Diskussionen in einem Issue, zum Beispiel über das Für und Wider einer neuen Funktion.
Der größte Vorteil ist, dass Issues als eine Art Dokumentation für alle (auch für zukünftige Teammitglieder) dienen können, da dort optimalerweise alle Informationen zu einem bestimmten Thema zusammenlaufen, z.B. wieso eine Entscheidung so getroffen wurde, wie sie getroffen wurde.
Issues können von dir selbst angelegt werden, in vielen Projekten werden sie aber auch häufig von anderen Menschen (Contributoren) angelegt. Einen Issue schließen können die Projekteignerin, die Maintainerin oder der Contributor, der den Issue erstellt hat.
Um den Umgang damit zu üben, legen wir mal einen Issue an, in dem wir aufschreiben, dass uns eine wichtige Information auf der Startseite fehlt. Es kann dir durchaus passieren, dass andere Menschen auf dein Projekt stoßen und ihnen irgendwelche Informationen fehlen. In der Regel werden sie dies über einen Issue kundtun. Aber auch wenn du selbst Themen findest, die du noch bearbeiten und nicht vergessen möchtest, ist das Anlegen eines Issues eine gute Sache (in Kapitel 10, Abschnitt »Eigene Projektboards – mit Projects den Überblick behalten« auf Seite