Contributor Guide

So shippst du deinen ersten Pull Request

Der kürzeste verlässliche Weg vom einsteigerfreundlichen Issue bis zum gemergten maintainer-ready Pull Request.

Hier starten

Wähle dein Startlevel

Nutze diese Karten als statischen Selector. Wähle die Karte, die zu deinem aktuellen Stand passt, und folge danach denselben Phasen unten.

Kompletter Einsteiger

Starte mit Tools, Vokabular und einer reinen Dokumentationsänderung. Dein Ziel ist, eine sichere Schleife abzuschließen.

Erste PR überhaupt

Wähle ein winziges, aktuelles Issue und halte den Diff fokussiert. Frag nach Bestätigung, bevor du codest.

Wiederkehrender Contributor

Nutze das Playbook als Checkliste und stecke den Großteil deiner Energie in Reproduktion und Tests des Fixes.

Phase 0

Basistools installieren

Du brauchst nur genug lokale Tools, um das Repository zu clonen, einen Branch zu erstellen, Projektchecks auszuführen und deine Arbeit zu pushen.

git

Git verfolgt deine Arbeit und lässt Maintainer exakt reviewen, was sich geändert hat.

git --version

gh

GitHub CLI hilft dir beim Forken, Clonen, Authentifizieren und Öffnen von Pull Requests, ohne das Terminal zu verlassen.

gh auth login
gh repo fork OWNER/REPO --clone --remote

editor

Nutze einen Editor, der das ganze Repository durchsuchen, Formatter ausführen und geänderte Dateien klar anzeigen kann.

code .

Phase 1

Das richtige Issue wählen

Ein gutes first issue ist nicht nur klein. Es ist aktuell, verständlich und von jemandem reviewbar, der das Projekt bereits maintained.

Gute Signale

  • Das Issue ist aktuell oder hat eine Maintainer-Antwort.
  • Das Repository hat Setup-Anweisungen, die noch funktionieren.
  • Die erwartete Änderung passt in einen kleinen Pull Request.
  • Tests oder manuelle Verifikationsschritte sind beschrieben.

Warnsignale

  • Mehrere Personen arbeiten bereits am selben Issue.
  • Das Issue ist vage, alt oder durch Design-Diskussion blockiert.
  • Die Änderung berührt Security, Billing, Datenbankmigrationen oder Release-Automation.
  • Das Projekt hat keine aktuelle Maintainer-Aktivität.

Entscheidungsbaum

  1. Kannst du den Request in einem Satz erklären?
  2. Kannst du das Problem lokal reproduzieren oder verifizieren?
  3. Kann die Änderung klein und isoliert bleiben?
  4. Wenn alle drei Antworten ja sind, frag, ob du das Issue übernehmen kannst.

Phase 2

Das 6-Schritte-Playbook

Halte die Schleife langweilig und vorhersehbar. Kleine Pull Requests sind leichter zu reviewen, leichter zu fixen und leichter zu mergen.

1

Übernehmen

Hinterlasse einen kurzen Kommentar, der das konkrete Issue nennt und fragt, ob der Scope noch Sinn ergibt.

2

Regeln lesen

Lies CONTRIBUTING, README, offene Pull Requests, Testbefehle und Code-Style-Hinweise, bevor du Code änderst.

3

Fork + Branch

Erstelle deine eigene Kopie und arbeite auf einem Branch, der nach dem Task benannt ist, nicht auf main.

4

Setup + Reproduktion

Installiere Dependencies, reproduziere das Problem und notiere den Befehl oder Screen, auf dem du es gesehen hast.

5

Winzigen Diff shippen

Ändere so wenig Code wie nötig. Vermeide Drive-by-Refactors, Dependency-Upgrades und unrelated Formatting.

6

PR öffnen

Erkläre, was sich geändert hat, wie du getestet hast und welche Grenzen es gibt. Mach den ersten Review-Durchgang leicht.

gh repo fork OWNER/REPO --clone --remote
cd REPO
git checkout -b docs/fix-install-note
pnpm install
pnpm test
git status
gh pr create --fill

Templates

Copy-paste Templates

Passe die Formulierung an, bleib konkret und verspreche nicht mehr, als du fertigstellen kannst.

Übernahme-Kommentar

Hi! I'd like to work on this issue.

I plan to keep the change scoped to:
- ...

Does that approach sound right before I start?

PR-Beschreibung

## What changed
- ...

## How I tested
- ...

## Notes
- This is my first contribution to this repository, so feedback is welcome.

Stopppunkte

Warnsignale, bevor du mehr Zeit investierst

Früh zu stoppen ist besser, als einen Pull Request zu erzwingen, der nicht reviewbar ist.

  • Du kannst das Projekt nach dem dokumentierten Setup nicht lokal ausführen.
  • Der Fix erfordert, Produktverhalten ohne Maintainer-Input zu erraten.
  • Das Issue verlangt ein großes Feature, Redesign, eine Migration oder Architekturentscheidung.
  • Ein Maintainer hat First-Time Contributors gebeten, nicht an diesem Bereich zu arbeiten.

Referenz

Glossar

Fork
Deine persönliche Kopie eines Repositorys. Du pushst deinen Branch dorthin, bevor du einen Pull Request öffnest.
Branch
Eine bewegliche Arbeitslinie. Nutze einen Branch pro Issue, damit deine Änderungen reviewbar bleiben.
Pull request
Eine Anfrage an Maintainer, deinen Branch zu reviewen und in das Projekt-Repository zu mergen.
Diff
Die kleinste sinnvolle Änderungsmenge, die das Issue löst, ohne unrelated Cleanup.
CONTRIBUTING
Eine projektspezifische Checkliste für Setup, Style, Tests und Pull-Request-Erwartungen.

FAQ

Häufige Fragen zur ersten PR

Was, wenn der Maintainer seit einer Woche nicht geantwortet hat?

Poste ein kurzes Follow-up mit deinem aktuellen Stand und einer direkten Frage. Wenn weiterhin keine Antwort kommt, wähle ein anderes Issue, statt unbegrenzt zu warten.

Was soll ich tun, wenn das Setup fehlschlägt?

Sag, was du versucht hast, füge den exakten Fehler ein, nenne Betriebssystem und Tool-Versionen und frag nach dem nächsten Debugging-Schritt.

Kann meine erste PR nur Dokumentation sein?

Ja, wenn das Repository Dokumentationsänderungen begrüßt. Klare Docs, Beispiele, Tippfehler und defekte Links sind legitime Beiträge.

Nach dem ersten Merge

Aus einem Beitrag eine wiederholbare Gewohnheit machen

Bedanke dich beim Reviewer, notiere die Befehle, die funktioniert haben, speichere die Projektkonventionen und suche das nächste Issue, das nur etwas schwieriger ist als das letzte.