Projektleitfäden

GitHub-README-Vorlage für ein Open-Source-Projekt

Ein hilfreiches GitHub-README beantwortet schnell vier Fragen: Was macht dieses Projekt, für wen ist es gedacht, wie probiere ich es aus und wo bekomme ich Hilfe? Verwende die folgende Markdown-Vorlage als Ausgangspunkt und ersetze jeden Platzhalter durch Informationen, die du anhand deines Projekts überprüft hast.

GitHubStart-Redaktion · Aktualisiert

Diese Markdown-README-Vorlage kopieren

Dies ist eine redaktionell erstellte Einstiegsvorlage, kein funktionierendes Softwarebeispiel. Ersetze den Text in eckigen Klammern, prüfe, ob die genannten Dateien existieren, und entferne unzutreffende Abschnitte. Die folgenden Installations- und Ausführungszeilen sind Kommentare, damit Platzhalterbefehle nicht versehentlich ausgeführt werden.

# [Projektname]

[Ein Satz: das Problem, die Zielgruppe und das Ergebnis.]

## Beispiel
[Zeige eine kleine Eingabe und die erwartete Ausgabe oder ergänze einen Screenshot.]

## Schnellstart
Voraussetzungen: [Laufzeitumgebung/Version und erforderliche Dienste].

```sh
# Durch deinen geprüften Installationsbefehl ersetzen.
# Durch den kleinsten Befehl ersetzen, der ein nützliches Ergebnis erzeugt.
```

Erwartetes Ergebnis: [was der Leser sehen sollte].

## Konfiguration
[Erforderliche Einstellungen, sichere Beispielwerte und Speicherort für Geheimnisse.]

## Einsatzmöglichkeiten
- [Ein konkreter Anwendungsfall]
- [Ein zweiter Anwendungsfall]

## Einschränkungen
[Nicht unterstützte Eingaben, Reifegrad sowie Leistungs- oder Plattformgrenzen.]

## Dokumentation und Hilfe
[Verlinke die Dokumentation und erkläre, wo Fragen gestellt werden können.]

## Mitwirken
Siehe [CONTRIBUTING.md](CONTRIBUTING.md).
Melde ein reproduzierbares Problem über den Issues-Tab des Repositorys.

## Lizenz
Siehe [LICENSE](LICENSE).

Das Beispiel an den Repository-Typ anpassen

Zeige für ein Kommandozeilenwerkzeug eine Eingabedatei, den Befehl und eine kurze Ausgabe. Zeige für eine Bibliothek das kleinste vollständige Beispiel aus Import und Aufruf einschließlich des erwarteten Rückgabewerts. Zeige für eine Webanwendung den Hauptablauf und erkläre, ob eine gehostete Demo oder eine lokale Einrichtung verfügbar ist.

Verwende einen Screenshot nicht als einzige Erklärung einer API: Leser sollten den Code kopieren können. Umgekehrt kann eine visuelle Anwendung von einem Screenshot profitieren, der klar beschreibt, was der Nutzer tut. Verwende echte Beispiele aus der derzeit veröffentlichten Version.

  • Bibliothek: Installation, unterstützte Laufzeitumgebung und ein vollständiger Funktionsaufruf.
  • CLI: Eingabe, Befehl, Ausgabe und Art der Fehlermeldung.
  • Webanwendung: Demolink oder lokale Einrichtung, Konfiguration und Screenshot der Hauptaufgabe.
  • Datensatz: Herkunft, Format, Lizenz und ein kleiner Beispieldatensatz.

Das README vor dem Teilen prüfen

Probiere den Schnellstart in einer sauberen Umgebung aus, nicht auf einem bereits für die Entwicklung eingerichteten Rechner. Prüfe, ob ein nicht genanntes globales Paket, eine private Registry oder eine lokale Datei benötigt wird. Wenn die Einrichtung ein Konto oder einen kostenpflichtigen Dienst voraussetzt, erwähne das vor dem ersten Befehl.

Öffne Dokumentations- und Bildlinks von der Repository-Seite aus. Prüfe, ob die Dateinamen für Beiträge und Lizenz zu deinem Repository passen, und entferne defekte Links. Ein kurzes, zutreffendes README ist besser als eine beeindruckend aussehende Vorlage voller noch nicht umgesetzter Versprechen.

  • Entferne Platzhalter und unbelegte Aussagen.
  • Verwende keine echten Tokens, Passwörter oder privaten URLs in Beispielen.
  • Prüfe, ob die erwartete Ausgabe zur veröffentlichten Version passt.
  • Erkläre Lesern, welche Angaben sie beim Melden eines Problems machen sollen.

Das README als Grundlage für die Veröffentlichung nutzen

Ziehe nach dem Ausfüllen der Vorlage eine kurze Vorstellung daraus: einen Satz zum Problem, ein Beispiel für das Ergebnis und einen Link zum Ausprobieren. Das ist der Ausgangspunkt für einen Community-Beitrag. Behalte das ursprüngliche README als ausführliche Quelle und passe jede Vorstellung an die Leser an, statt überall denselben Werbeabsatz zu wiederholen.

Häufige Fragen

Ist dies ein Repository-README oder ein Profil-README?

Diese Vorlage ist für ein Software-Repository gedacht. Ein Profil-README stellt eine Person vor und benötigt andere Abschnitte, etwa zu ihrer Arbeit und ihren Kontaktwünschen.

Sollte ich oben Sterne-Badges ergänzen?

Nur, wenn sie den Lesern helfen. Stelle Zweck und Schnellstart gut sichtbar dar. Ein Badge ersetzt nicht die Erklärung, was das Projekt macht.

Kann ich diese Vorlage für ein privates Projekt verwenden?

Ja. Ersetze öffentliche Supportlinks durch die tatsächlichen Hilfekanäle deines Teams, erkläre die Zugangsvoraussetzungen und halte Zugangsdaten aus dem Dokument heraus.

Quellen