Als Maintainer wirst du Pull Requests recht regelmäßig reviewen.
Dieses Dokument enthält einige Exercism-spezifische Richtlinien für das Review von Pull Requests.
Pull Requests zu Übungen reviewen
Einen Pull Request für eine Konzeptübung oder eine Praxisübung zu reviewen, kann angesichts der vielen Regeln für diese Übungsarten entmutigend sein.
Aus diesem Grund dauert ein erster Review-Durchgang eines Maintainers oft zwei bis drei Stunden und führt zu Dutzenden Kommentaren.
Bei Konzeptübungen gibt es außerdem Dateien mit ähnlichen Zielen/Inhalten (zum Beispiel die Übungs- und die Konzept-Einführung). Hier ist es wichtig, sich zuerst auf eine davon zu konzentrieren und sie perfekt zu machen, bevor du dich zu weit verzweigst.
Um diesen Workflow zu optimieren, haben wir die folgenden Empfehlungen entwickelt.
Empfehlung: Nur ein erfahrener Maintainer übernimmt den ersten Review-Durchgang
Die Gründe dafür, dass genau ein erfahrener Maintainer den ersten Review-Durchgang übernimmt, sind:
- Es wird keine Review-Arbeit doppelt gemacht
- Contributor und Maintainer arbeiten als Paar am Pull Request, was dem Contributor hoffentlich das Gefühl gibt, damit nicht allein zu sein
- Es gibt keine widersprüchlichen Review-Kommentare von anderen Maintainern
Empfehlung: mit dem Status wip mergen
Sobald Contributor und Maintainer beide mit der Übung zufrieden sind, sollte die Übung gemergt werden, wobei ihr status auf wip (work-in-progress) gesetzt wird.
Übungen mit diesem Status stehen Lernenden nicht zur Verfügung, können aber von unseren Top-Mentoren angesehen werden (sobald wir das irgendwann in der Zukunft umgesetzt haben).
Diese Nutzer mit hoher Reputation können die Übung dann testen und Issues oder Pull Requests erstellen, um die Übung zu reparieren oder zu verbessern.
Die wichtigsten Vorteile dieses Ansatzes sind:
- Es nimmt dem ursprünglichen Contributor-Maintainer-Paar die Last, alles perfekt machen zu müssen
- Es führt nicht zu riesigen Pull-Request-Zyklen mit vielen Stimmen (die wirklich schwer zu steuern sind)
Pull Requests zu Praxisübungen reviewen
Empfehlung: prüfe, ob die Änderung wirklich zu problems-specifications gehört
Einige Inhalte einer Praxisübung (zum Beispiel ihre Einführung) stammen aus ihren (gemeinsamen) Metadaten, wie sie im problems-specifications-Repository definiert sind.
Wenn du einen Pull Request reviewst, der solche Inhalte ändert, überlege, ob die Änderung auch anderen Tracks zugutekommen könnte.
Wenn ja, schlage dem Contributor vor, einen Pull Request für die entsprechende Datei im problems-specifications-Repository zu öffnen.
Allgemeine Empfehlungen zum Reviewen
Empfehlung: ein Haupt-Reviewer pro Pull Request
Jeder Pull Request sollte einen Haupt-Reviewer haben (welcher Maintainer ihn auch übernimmt).
Andere Maintainer und/oder Community-Mitglieder sollten eine zweitrangige Rolle übernehmen.
Es gibt zwei wichtige Arten, wie jemand in einer zweitrangigen Rolle zu einem Review beitragen kann:
- Rechtschreibung/Grammatik Korrektur lesen, aber erst, nachdem der Haupt-Reviewer seinen ersten Durchgang gemacht hat.
Für Contributoren kann es frustrierend sein, wenn sie ein Rechtschreib-/Grammatik-Review bekommen, es umsetzen, und dann kommt ein Maintainer daher und bittet sie um grundlegendere Änderungen.
Anders gesagt: Korrekturlesen machst du nachdem die grundlegenden Änderungen geklärt sind (oder vielleicht in einem Folge-Pull-Request).
- Dinge so ansprechen, dass der Reviewer nicht zum Handeln aufgefordert wird.
Wenn du etwas kommentierst, worüber der Haupt-Reviewer nachdenken sollte oder was er übersehen haben könnte, formuliere deinen Kommentar bitte als Meinungsäußerung oder als Frage.
Damit ist für den Contributor klar, dass du ihn nicht um Änderungen bittest, was die Sache für ihn weniger verwirrend macht.
Außerdem sinkt die Chance, dass sich der Haupt-Reviewer „untergraben“ fühlt.
Empfehlung: kommentiere nichts, was nicht dazugehört
Wenn du einen Pull Request reviewst, kommentiere nur Dinge, die direkt mit dem Pull Request zu tun haben.
Für alles andere öffne bitte ein Issue oder erstelle einen separaten (Folge-)Pull-Request.
Empfehlung: verlinke die Dokumentation
Wenn möglich, verlinke immer die Dokumentation, die den Grund dafür erklärt, warum du etwas kommentierst.
Das hilft sehr dabei, dass Diskussionen nicht in Streit ausarten.
Empfehlung: hol dir Hilfe von anderen Teams
Wenn du Hilfe beim Reviewen eines Pull Requests möchtest, kannst du zwei bestimmte Teams anpingen:
-
@exercism/reviewers: für allgemeine Reviews
-
@exercism/github-actions: für alle Fragen zu GitHub Actions
