Es ist wieder soweit. Github und Digitalocean haben das Hacktoberfest ausgerufen. Wenn man bei beliebigen Github-Repositories im Oktober mindestens drei Pull-Requests erstellt gibt’s ein „Ich-War-Dabei“-T-Shirt. Ob man zum Code oder zu Dokumentation beiträgt spielt keine Rolle.

An sich eine hübsche Aktion, um Opensource-Beteiligung zu fördern. Vor dem Hintergrund möchte ich hier noch mal erläutern, wie man bei Github an Projekten mitarbeitet. Für Gitlab/Gitea/Bitbucket usw. gelten die Hinweise natürlich auch. Inspiration ist Davide Coppola’s großartiger Artikel zum Thema.

1. Follow the rules

Die meisten Projekte haben Regeln dazu, wie und in welcher Form man Code (oder Dokumentation) beisteuern kann. Diese finden sich meist in einer CONTRIBUTING.md oder ansonsten direkt in der README. Das sollte man sich wenigstens mal kurz angeschaut haben. Danach kann man in den bestehenden Issues und Pull-Requests schauen, ob vielleicht schon jemand an dem Problem arbeitet.

Bevor man mit einem größeren Unterfangen beginnt ist es oft auch sinnvoll kurz in einem Issue nachzufragen, ob dies überhaupt erwünscht oder sinnvoll ist. Damit erspart man sich den Ärger viel Arbeit zu leisten, die am Ende abgelehnt wird weil der Autor z.B. selbst eine noch nicht veröffentlichte Lösung für das Problem geschrieben hat.

2. Fork it!

Der eigene Beitrag beginnt immer mit einem Fork. Dazu klickt man auf der Projekt-Seite oben rechts auf den Fork-Button. Das Projekt wird nun in den eigenen Namespace (unter den eigenen Nutzernamen) kopiert. Man wird automatisch auf die eigene Github-Seite umgeleitet.

3. Clone it

Als nächstes will man das Repository auf den eigenen Rechner klonen. Die Adresse dazu bekommt man mit einem Klick auf den grünen Clone-Button. Wichtig ist, dass man hier gleich SSH auswählt. Dazu muss man bei seinem Github-Konto ebenfalls einen SSH-Schlüssel hinterlegt haben (darauf gehe ich hier nicht näher ein, beantworte aber gern Fragen).

git clone git@github.com:USERNAME/PROJECTNAME.git

Nun hat man das Repository lokal auf dem Rechner und verbunden mit dem Fork auf Github. Für spätere Updates ist es eine gute Idee, auch eine Verbindung zum Ursprungs-Projekt (upstream) anzulegen. Diese Verbindungen nennt man remotes.

git remote add upstream git@github.com:PROJECT_USERNAME/PROJECTNAME.git

Der Remote-Name ist frei wählbar, upstream ist jedoch eine gängige Konvention für die ursprüngliche Quelle während das remote auf dem man selbst arbeitet origin genannt wird. Zur Kontrolle lassen wir uns die remotes noch mal anzeigen:

git remote -v

origin    git@github.com:USERNAME/PROJECTNAME.git (fetch)
origin    git@github.com:USERNAME/PROJECTNAME.git (push)
upstream  git@github.com:PROJECT_USERNAME/PROJECTNAME.git (fetch)
upstream  git@github.com:PROJECT_USERNAME/PROJECTNAME.git (push)

4. Branch erstellen

Bei kleinen Änderungen kann man diesen Schritt auch überspringen. Besonders, wenn man ansonsten nichts weiter zu dem Projekt beiträgt und das Repository ohnehin bald wieder vom Rechner löscht. Man sollte es sich trotzdem gleich richtig angewöhnen, so viel Mehraufwand ist es auch nicht:

git checkout -b BRANCH_NAME

Als BRANCH_NAME wählt man etwas beschreibendes wie fix-menu-error oder issue-12345. Die lokalen branches und die aktuell aktive branch kann man sich mit git branch anzeigen lassen.

5. hackhackhack

Nun kann man in der eigenen branch am Problem oder am neuen Feature werkeln. Dabei ist jedoch eines zu beachten. Wärend der eigenen Arbeit kann es gut sein, dass am Hauptprojekt weitergearbeitet wird. In der Regel wird gefordert, dass neue Beiträge immer auf dem aktuellsten Commit des Projekts basieren. Man hört dann Dinge wie „please rebase to upstream master“.

Das geht so und sollte mindestens kurz vor dem Pull-Request ein mal gemacht werden:

git pull --rebase upstream master

Was passiert kann man sich in der Git-Dokumentation in Grafiken anschauen. Kurzgesagt: Die eigenen Commits werden kurz beiseite gelegt. Es werden die neuen commits aus upstream/master eingepflegt (so dass die Reihenfolge die gleiche wie im upstream ist) und dann die eigenen commits wieder eingespielt. Diese sind nun wieder „am Ende der Kette“.

6. Pull-Request

Die fertige (oder auch unfertige) Arbeit kann man mit

git push origin BRANCH_NAME

in das eigene Github Repository hochladen. Öffnet man dieses im Browser kann man dort den Pull-Request erstellen.

7. Abwarten, Abändern

Die Maintainer werden über den Pull-Request informiert. Kommentare dazu bekommt man per Mail und auf Github. Sollen noch Änderungen eingepflegt werden macht man das ganz einfach lokal und pusht sie wie vorher in das Github Repository. Sie tauchen dann direkt im Pull-Request auf. Man kann beim Erstellen des Pull-Requests den Entwicklern auch die Möglichkeit geben direkt selbst Änderungen an diesem vorzunehmen.

8. Aufräumen

Wenn der Pull-Request angenommen (oder abgelehnt) wurde, kann man die lokale und die remote Branch löschen:

git checkout master
git branch -D BRANCH_NAME
git push origin --delete BRANCH_NAME

Updaten

Will man den Fork lokal und auf Github behalten, sollte man ihn regelmäßig mit upstream synchronisieren:

# die Upstream-Änderungen holen
git fetch upstream master
# lokal zu master wechseln
git checkout master
# die lokale master branch auf upstream/master updaten
git merge upstream/master

So, nun loslegen und viel Spass beim Hacktoberfest!