Open-Source Software mit GitHub weiterentwickeln

Was ist Open-Source Software?

Open-Source Software verbinden viele mit Software, die für alle möglichen Zwecke heruntergeladen und gratis benutzt werden kann. Open-Source Software ist jedoch viel mehr als das. Für mich steht vor allem der transparente und gemeinschaftliche Ansatz der Softwareentwicklung im Zentrum. Es geht darum, als Community gemeinsam Probleme zu lösen und vom gegenseitigen Know-how zu profitieren. Das Ergebnis wird dann unter einer freien Lizenz der Allgemeinheit zur Verfügung gestellt. Daran geknüpft ist immer die Hoffnung, dass die Nutzer eines solchen Softwareprojekts sich auch aktiv an diesem beteiligen. Gerade in meinem beruflichen Umfeld rund um DevOps, System- und Netzwerkadministration, gibt es viele Leute, die täglich mit Open-Source Software arbeiten. Sie passen die Software für Ihre Zwecke an, korrigieren kleinere oder grössere Unzulänglichkeiten oder erweitern deren Funktionsumfang mit interessanten Features. Leider finden diese lokalen Änderungen aber nicht immer ihren Weg zurück zu den ursprünglichen Autoren.

Wieso fliessen lokale Anpassungen nicht zurück zu den entsprechenden Projekten?

Ich sehe für das Problem vor allem folgende Ursachen:

  • Mein Code ist für das Projekt nicht von Interesse. In der Regel schreibt man ja eigenen Code weil man damit ein Problem lösen will. Dass ich wirklich der Einzige mit dem Problem bin ist dann doch eher unwahrscheinlich. Natürlich kann es sein, das meine Änderungen nicht den Anforderungen oder dem abgesteckten Funktionsumfang eines Projekts entsprechen. Ich habe jedoch bisher nicht erlebt, dass Änderungen komplett abgelehnt werden. Dass mal die eine oder andere Anpassung gefordert wird, ist hingegen durchaus üblich und hilft in der Regel, die Qualität des eigenen Codes zu verbessern.
  • Mein Code ist nicht gut genug. Oft gehört, auch bei uns in der Firma. Der Code entspricht nicht den eigenen Anforderungen an Qualität, Stil etc. Man will sich damit nicht blamieren. Es gibt natürlich Code, der im Rahmen von Projekten entsteht, der nicht über alle Zweifel erhaben ist. In der Regel ist der Zeitaufwand, den Code auf ein akzeptables Niveau zu bringen jedoch überschaubar und in Hinblick auf die Wartbarkeit der Software auch gut investierte Zeit.
  • Mir fehlt die Zeit. Meist eine Ausrede; oft zumindest nicht zu Ende gedacht. Früher oder später muss ich meinen lokalen Code aktualisieren, meist dann, wenn im ursprünglichen Projekt neue Funktionen hinzukommen oder mehr oder weniger kritische Fehler beseitigt wurden. Wenn ich mir von Anfang an die Zeit nehme, meinen Code zurückzuführen, wird dieser automatisch von der Community mitgepflegt. Ich spare also unter dem Strich Zeit.
  • Ich weiss nicht so recht wie das mit Git, GitHub, Issues und Pull Requests funktioniert. Viele Projekte setzen mittlerweile auf GitHub als zentrale Entwicklungs- und Kollaborationsplattform. Daher müssen wir uns zwangsweise mit den Abläufen vertraut machen, wenn wir uns in die Entwicklung einbringen möchten. Dazu möchte ich im weiteren Verlauf dieses Blogposts ein kurze Einführung geben.

How do I GitHub?

GitHub ist eine webbasierte Softwareentwicklungs- und Kollaborationsplatform, die von vielen Open-Source Projekten als zentrale Anlaufstelle für Nutzer und Entwickler eingesetzt wird. Die Platform unterstützt bei:

  • Verteilung der Software; Basis hierzu ist das Versionskontrollsystem Git.
  • Verwaltung von Feature Requests und Bug Reports
  • Soziale Netzwerk-Komponenten wie das Folgen von Projekten.

GitHub setzt auch ganz gezielt auf möglichst einfache Kollaboration.

Issues

Wenn man ein Fehlverhalten (Bug Report) der Software festgestellt hat oder sich eine neue Funktion (Feature Request) wünscht, bietet es sich an, dafür ein Issue zu eröffnen. Vor allem wenn man noch keine Lösung bereit hat. Bei Bug Reports ist es immer wichtig, möglichst viele Informationen zum Nachvollzug des Fehlverhaltens zur Verfügung zu stellen. Dazu gehört die Version der eingesetzten Komponenten, welche Aktionen zum Fehlverhalten führten (Shell Kommandos, Screenshots / Screencasts, Schritt-für-Schritt Anleitungen) sowie Auszüge von relevanten Logdateien. Oft wird erwartet, dass das Fehlverhalten mit der aktuellsten Version der Software getestet wird.

Forks / Pull-Requests

Möchte man einen Schritt weitergehen und selber Code, Dokumentation oder allfällige Übersetzungen beisteuern, macht man sich eine lokale Kopie des entsprechenden Projekts. In der GitHub-Terminologie ist dies ein Fork und den erstellt man mit einem Klick auf die entsprechende Schaltfläche oben rechts. Diese Kopie ist ein vollwertiges Git Repository, auf dem wir uneingeschränkt arbeiten können. Es empfiehlt sich, den master branch nicht für die aktive Entwicklung zu benutzen, sondern für die einzelnen Features und Bugfixes eigene Branches zu erstellen. Dies erleichtert später das Nachführen von Änderungen des Upstream-Repositories, also des Projekts, von dem wir ursprünglich den Fork gezogen haben. Auf unserem Feature oder Bugfix Branch können wir nun entwickeln, und sobald wir mit dem Ergebnis oder dem Fortschritt zufrieden sind, ein sogenannten Pull-Request erstellen. Damit bitten wir sozusagen die Autoren des Upstream-Repositories unsere Änderungen einzupflegen.

Ein GitHub Workflow-Beispiel

Ich habe ein interessantes Projekt auf GitHub entdeckt: https://github.com/vshn/tikapy-icinga, gemäss Beschreibung eine Sammlung von Nagios/Icinga Plug-ins zur Überwachung von Mikrotik-Geräten. Mein Wunsch: Ich möchte die Anzahl der aktuell verbundenen WLAN Clients auslesen. Leider fehlt das Plugin mit entsprechender Funktionalität, sodass ich mich entscheide, dieses selber beizusteuern. Ich mache also einen Fork des Projekts.

Nach einem Klick auf die entsprechende Schaltfläche und ein paar Sekunden Geduld habe ich nun meine Kopie des Projekts. Davon ziehe ich nun lokal eine Kopie.

$ git clone git@github.com:andrekeller/tikapy-icinga.git 

Zusätzlich erstelle ich einen Feature Branch für meine geplanten Änderungen.

$ cd tikapy-icinga
$ git checkout -b feature_wlan_clients
Switched to a new branch 'feature_wlan_clients'

Als nächstes schreibe ich den entsprechenden Code in die Datei check_tikapy_wlan_clients.py. Sobald ich damit fertig bin, checke ich die Änderungen ein (Git Commit) und pushe diese auf mein Repository (Git Push):

$ git add check_tikapy_wlan_clients.py
$ git commit -m 'Add new script to check clients connected to a specific WLAN.' check_tikapy_wlan_clients.py
$ git push origin feature_wlan_clients

Wenn es sich um eine grössere Änderung handelt, ist es normal, dass sich hier der eine oder andere Commit ansammelt. Sobald man das Gefühl hat, die Änderung ist soweit, dass man dafür einen Pull-Request öffnen kann, empfiehlt es sich, den Branch zu rebasen. Upstream-Projekte sehen es oft nicht gerne, wenn zusammengehörende Änderungen auf mehrere Commits verteilt sind, da alle Commits beim Akzeptieren des Merge-Requests in das Upstream-Projekt übertragen werden und die History entsprechend unübersichtlich machen können.

Also schauen wir rasch in das Git Log bevor wir den Pull-Request erstellen:

$ git log --pretty=oneline --abbrev-commit
2c10f7b Fix bug about foobar...
1750568 Add some more functionality...
ff7d064 Add new script to check clients connected to a specific WLAN.
665a71e Support lookup by name instead of ip.
30c7787 Package release 0.1.1.
...

In diesem Fall gehören die obersten drei Commits zu unserer Änderung, daher rebasen wir diese in einen einzigen Commit:

$ git rebase -i 665a71e

Dies öffnet einen Editor:

enter image description here

Den ersten Commit übernehmen wir, möchten dazu aber noch einen ausführlichere Commit Message schreiben. Dazu markieren wir den Commit mit reword. Die beiden anderen beiden Commits integrieren wir in den ersten, die Commit Messages brauchen wir nicht. Wir markieren die beiden Commits also mit fixup:

enter image description here

Sobald wir die Datei speichern und den Editor schliessen, öffnet sich der Editor erneut und gibt uns die Möglichkeit, die Commit Message anzupassen:

enter image description here

Danach schauen wir nochmals in das Commit Log.

$ git log --pretty=oneline --abbrev-commit
7aed10a Feature: Add new script to check clients connected to a specific WLAN.
665a71e Support lookup by name instead of ip.
30c7787 Package release 0.1.1.

Hat geklappt, wir haben nun einen einzigen Commit. Da wir die History unseres Branches damit geändert haben, müssen wir nun einen Force Push machen. Force Pushs sollten nur auf einem Feature Branch gemacht werden, niemals auf dem Master!

$ git push -f origin feature_wlan_clients

Der nächste Schritt ist nun, ein Pull-Request zu erstellen. Dafür gehen wir zurück zu unserem Fork auf GitHub.

enter image description here

Wie auf dem Screenshot zu sehen ist, hat GitHub gemerkt, dass wir eine Änderung auf einen Branch gepusht haben und bietet uns sogleich an einen Pull-Request zu erstellen:

enter image description here

GitHub übernimmt hier automatisch die Message aus dem Commit. Wir können den Request also unverändert mit einem Klick auf Create Pull Request absetzen. Nun heisst es warten, bis die Autoren des Upstream Projekts reagieren. Das kann mitunter ein paar Tage dauern. Leider kommt es auch vor, dass Projekte einfach aufgegeben werden und gar keine Antwort zurückkommt. Erkennen kann man das auch daran, dass bereits diverse unbearbeitete Pull-Requests für das Projekt vorhanden sind. Es lohnt sich also, vorher rasch zu prüfen, wie es um ein Projekt steht.

Weiter kommt es natürlich vor, dass man einen entsprechenden Kommentar erhält, mit der Bitte, noch kleinere oder grössere Anpassungen zu machen. In dem Fall machen wir die Änderungen in unserem Branch, committen, rebasen und pushen diese. Der Pull-Request wird bei jedem Push auf den Branch automatisch aktualisiert. Im Idealfall wird dann die Änderung nach der einen oder anderen Iteration gemerged: Das heisst, die Commits werden in das Upstream-Repository eingepflegt und der Pull-Request wird damit automatisch geschlossen. Wir kriegen eine entsprechende Benachrichtigung und wenn wir uns den geschlossenen Pull-Request noch einmal anschauen, sehen wir:

enter image description here

Das bedeutet, unsere Änderungen sind nun Teil vom Upstream Projekt. Yay!

Haben wir Lust auf das nächste Feature, aktualisieren wir unseren Fork und legen für das nächste Feature einen Branch an. Den alten Feature Branch brauchen wir nicht mehr, es bietet sich also an, diesen zu entfernen.

# zurückwechseln zu master branch
$ git checkout master
# upstream änderungen abholen (URL vom Upstream Projekt, nicht unserem Fork!)
$ git remote add upstream git@github.com:vshn/tikapy-icinga.git
$ git fetch upstream

# upstream änderungen einpflegen
$ git rebase -p upstream/master
# lokalen wlan clients feature branch löschen
$ git branch -d feature_wlan_clients

# remote wlan clients feature branch löschen
$ git push origin :feature_wlan_clients
# neuen feature branch erstellen
$ git checkout -b feature_new_feature

Forks in denen keine offenen Pull-Requests oder andere lokale Änderungen pendent sind, sollte man via GitHub-Webseite löschen. Damit trägt man zu mehr Übersicht, zum Beispiel in den Suchergebnissen, bei. Will man später noch weitere Änderungen vornehmen, kann man jederzeit einen neuen Fork ziehen.

Fazit

Wenn man sich initial ein bisschen Zeit nimmt und sich mit Git und GitHub etwas auseinandersetzt, sind die Hürden, an einem Open-Source Projekt mitzuarbeiten, schnell überwunden. Somit steht einem nichts mehr im Weg, die eigenen Ideen zu verwirklichen und mit der Open-Source Community zu teilen.