Wie man zu einem Open-Source-Projekt beiträgt

Das Folgende wird etwas meinungsbasiert sein und zielt darauf ab, jemanden auf seinem Weg in den Open-Source-Bereich zu begleiten. Voraussetzung ist eine grundlegende Vertrautheit mit der Kommandozeile und Git. Wenn Sie die Konzepte kennen und sich direkt in die Schritt-für-Schritt-Anleitung stürzen möchten, sehen Sie sich diesen Teil des Artikels an.

Es gibt wirklich keinen einzigen Weg, zu einem Open-Source-Projekt beizutragen, und beteiligt zu sein bedeutet oft mehr als nur Code zu schreiben. In diesem Artikel werden wir uns jedoch auf die Einzelheiten des Beitrags einer Pull-Anfrage (PR) zu einem fremden Projekt auf GitHub konzentrieren.

Lassen Sie uns die Bühne bereiten...

Sie stoßen auf das Projekt von jemandem auf Github und lieben es! Sie entscheiden sich vielleicht sogar, es in Ihrem eigenen Projekt zu verwenden. Aber Ihnen fällt eine kleine Sache auf... es könnte ein Fehler sein. Es könnte eine Verbesserung dessen sein, was bereits vorhanden ist. Vielleicht haben Sie den Code durchgesehen und eine schöne, optimierte Schreibweise gefunden, die etwas lesbarer ist, selbst wenn es nur eine zusätzliche Einrückung im Code ist.

Hier sind einige erste Vorschläge und Anweisungen, wie Sie von hier aus weiter vorgehen können.

Suchen Sie nach einem CONTRIBUTING.md Dokument oder einem Contributing Guide in der Dokumentation

Viele Open-Source-Projekte wissen, dass andere Leute beitragen möchten. Wenn sie sich immer wieder dieselbe Frage beantworten müssen, soll dieses Dokument es einfacher machen, alle auf den gleichen Stand zu bringen.

Einige Dinge, die Sie in einem Contributing Guide finden könnten

• Stilrichtlinien
• Voraussetzungen für die Einreichung einer PR
• Wie Sie Ihre Änderung zur Dokumentation hinzufügen
• Eine Checkliste für Beiträge
• Erläuterung der Projektarchitektur und -einrichtung

Dieses Dokument kann so einfach sein wie ein paar Notizen oder so umfangreich, dass es eine Weile dauert, es vollständig zu lesen (wie zum Beispiel Atom's Contributing guide).

Bei größeren Projekten ist es sinnvoll, die Beitragsrichtlinien im Voraus zu kommunizieren, da sich PRs und Issues stapeln und die Zeit eines Maintainers stark belasten können, wenn Beiträge sortiert werden müssen, die möglicherweise nicht im Geltungsbereich des Projekts liegen. Nehmen Sie sich auf jeden Fall etwas Zeit, um diesen Leitfaden zu lesen, falls er existiert, da Ihre PR auch etwas Zeit des Maintainers beanspruchen wird.

Durchsuchen Sie die vorhandenen Issues und PRs

Bevor Sie ein neues Issue erstellen oder eine PR einreichen, ist es ratsam zu prüfen, was bereits vorhanden ist. Möglicherweise stellen Sie fest, dass jemand bereits dasselbe Problem angesprochen oder etwas Ähnliches eingereicht hat. Sie können die Suchleiste des Projekts nutzen – ich suche normalerweise sowohl nach offenen als auch nach geschlossenen Issues, da es wichtig ist zu wissen, ob mein Anliegen bereits angesprochen wurde und der Maintainer vielleicht einen anderen Weg eingeschlagen hat. Auch hier geht es darum, sowohl Ihnen als auch dem Maintainer Zeit zu sparen.

Ein Issue einreichen

Das Einreichen von Issues ist ein Kernbestandteil des PR-Einreichungsprozesses. Sie bieten die Möglichkeit, die Situation zu artikulieren, Kontext dazu zu schaffen und ein Diskussionsforum bereitzustellen, das an die PR selbst angehängt werden kann.

Wenn ich ein Issue einreiche, schreibe ich gerne auf, was mein Anliegen ist, und lese es dann so, als wäre ich auf der Empfängerseite. Menschen sind Menschen – auch wenn das, was Sie sagen, technisch korrekt ist, werden Sie wahrscheinlich keine Zustimmung für Ihre Idee erhalten, wenn Ihr Ton abstoßend ist. Bedenken Sie: Sie bitten möglicherweise jemanden, in seiner Freizeit viel Arbeit zu leisten. Wenn Sie jemand bittet, an einem Samstag zu arbeiten, werden Sie dies eher tun, wenn er Sie respektvoll und ohne Herablassung bittet? Sie verstehen, worauf ich hinauswill.

Stellen Sie beim Einreichen eines Issues sicher, dass Sie alle Details angeben, die zur Erledigung der Arbeit benötigt werden. Einige Dinge, die Sie notieren könnten

• Wenn es ein Fehler ist, in welcher Umgebung sehen Sie das Problem? Ist es Entwicklung oder Produktion? Vielleicht irgendwo anders?
• Wenn es eine Funktionsanfrage ist, erklären Sie das Problem. Manchmal kann es hilfreich sein, dies aus der Perspektive des Endbenutzers in Form von User Stories darzustellen, sowohl um die Situation zu konzeptualisieren als auch um sie von persönlichen Gefühlen zu abstrahieren.
• Wenn es eine allgemeine Frage ist, geben Sie dies gleich zu Beginn an, damit der Maintainer keine Zeit damit verschwenden muss herauszufinden, ob Sie nach einem Fehler oder einer Funktion fragen.
• Wenn Sie eine PR einreichen möchten, um das Issue zu verbessern, erwähnen Sie, dass Sie dies tun möchten, und bitten Sie dann um Erlaubnis fortzufahren (da Maintainer manchmal andere Dinge geplant haben, die Ihnen möglicherweise nicht bekannt sind).

Erwägungen vor Arbeitsbeginn

Zu diesem Zeitpunkt sind Sie wahrscheinlich schon gespannt darauf, mit Ihrer PR zu beginnen. Aber zuerst gibt es noch ein paar übliche Dinge zu erledigen, bevor Sie sich daran machen.

Zuerst fragen

Ich bin ein großer Fan davon, dass Leute in einem Issue fragen, ob eine PR sinnvoll ist, bevor sie daran arbeiten. Ich halte es nicht für eine strenge Regel, aber manchmal kann ich ihnen viel Zeit und den falschen Weg sparen, wenn wir gemeinsam klären können, was wir wollen. Es hilft auch anderen zu wissen, dass sie dasselbe nicht implementieren müssen (vorausgesetzt, sie schauen sich ebenfalls offene und geschlossene PRs an).

Labels verwenden

Wenn Sie ein Issue einreichen und alle zustimmen, dass eine PR eine gute Idee ist, dann ist es schön, wenn Sie (oder der Besitzer des Repos) das Label in progress hinzufügen. Sie können nach Labels suchen, sodass für alle klar ersichtlich ist, dass Sie daran arbeiten.

In kleinen Häppchen arbeiten!

Als Maintainer ist es frustrierend, wenn jemand viel Arbeit investiert und eine riesige PR einreicht, die 10 verschiedene Dinge tut. Sie ist sehr schwer zu überprüfen und zwangsläufig macht sie sechs Dinge, die Sie wollen, und vier, die Sie nicht wollen. Nicht nur das, sie ist meist über mehrere Dateien verteilt, was schwer zu entwirren ist. Ich habe definitiv PRs mit hochwertigem Code geschlossen, den ich mochte, nur weil es ewig dauern würde, ihn zu überprüfen und zu verwalten. (Ich kommuniziere, dass dies das Problem ist, wenn sie die Arbeit als separate PRs erneut einreichen möchten.)

Meiner Meinung nach haben Sie eine 1.000% höhere Chance, dass Ihre PR gemerged wird und Ihre investierte Zeit gewürdigt wird, wenn Sie die Dinge auf mehrere, kleinere PRs aufteilen. Ich liebe es, wenn Leute eine PR pro Thema einreichen. Und es kann nett sein, nicht erforderlich, wenn jede Einreichung auch etwas zeitlich auseinander liegt, um die kognitive Überlastung zu reduzieren.

Ihre PR einreichen

Dies sind die Schritte, die ich persönlich verwende, um eine PR einzureichen. Sie können dies natürlich auch auf andere Weise tun, aber ich habe festgestellt, dass die folgenden Schritte in meiner Erfahrung wirksam waren. Außerdem sind alle Angaben in den Befehlen, die in GROSSBUCHSTABEN geschrieben sind, Informationen, die Sie für Ihre Zwecke ändern müssen.

Gehen Sie zuerst zum Repository und forken Sie eine Kopie des Projekts auf Ihr persönliches GitHub-Konto. Klonen Sie es lokal und wechseln Sie mit cd in das Verzeichnis, in dem es sich befindet. (Ich verwende HTTPS, aber SSH ist ebenfalls völlig in Ordnung.)

git clone https://github.com/YOUR-USERNAME/YOUR-FORKED-REPO.git
cd into/cloned/fork-repo

Als nächstes fügen Sie einen Upstream-Remote zur ursprünglichen Branch hinzu. Das bedeutet, dass sie eine Verbindung zur ursprünglichen Branch haben wird, damit Sie synchron bleiben und alle Aktualisierungen des Projekts abrufen können, wenn sie auftreten.

git remote add upstream https://github.com/ORIGINAL-DEV-USERNAME/REPO-YOU-FORKED-FROM.git
git fetch upstream

Jetzt können Sie eine neue Branch erstellen und ihr einen Namen geben, der sich auf das PR-Thema bezieht. Beachten Sie, dass ein Maintainer möglicherweise eine spezifische Benennungskonvention hat, die im Repository dokumentiert ist.

git checkout -b GOOD-FORKIN-NAME

Gehen Sie vor und arbeiten Sie an Ihren Änderungen. Stellen Sie sicher, dass Sie unterwegs gute Commit-Nachrichten schreiben.

git add -A
git commit -m “ADDING IN A TACO DISPENSER”
git push origin GOOD-FORKIN-NAME

GitHub erkennt den neuen Fork und fordert Sie auf, die PR zu erstellen, was eine nette, hilfreiche Geste ist. Sie klicken auf die Schaltfläche und füllen die Details aus: Welches Issue wird geschlossen? Sie können darauf mit seiner Nummer verweisen und GitHub wird es automatisch zuordnen.

Auf der PR

PR” />

Im Issue

Was sind einige Dinge, die man in der PR beachten sollte? Diese Details helfen dem Maintainer, den Kontext zu verstehen. Das können alle vorgenommenen Änderungen sein, sie können auch größere strategische oder kontextbezogene Informationen sein.

Und Sie sind auf dem besten Weg! 🎉

Möglicherweise stellen Sie fest, dass Sie Ihren Fork mit dem Remote synchron halten müssen und deren Änderungen in Ihren pullen müssen. Um dies zu tun, würden Sie diesen Befehl ausführen

git pull upstream master

Lob geht an Christina Solana für ihren Gist, den ich seit vielen Jahren als Referenz verwende.

Denken Sie immer daran: Maintainer sind oft überlastet und opfern Nächte und Wochenenden, um Open-Source-Projekte aktiv und aktuell zu halten. Respektvoll zu sein, sowohl in Bezug auf ihre Zeit als auch im Ton, kann Ihnen zum Erfolg beim Beitrag verhelfen.

---

Open Source kann äußerst lohnend sein! Zu wissen, dass andere Menschen von etwas profitieren und direkt etwas nutzen, das Sie beigetragen haben, kann eine großartige Möglichkeit sein, sich in die Community einzubringen und zu lernen.