Machen Sie eine README
Vorschläge für eine gute README
Jedes Projekt ist anders, also überlegen Sie, welche dieser Abschnitte für Ihre gelten. Die in der Vorlage verwendeten Abschnitte sind Vorschläge für die meisten Open-Source-Projekte. Denken Sie auch daran, dass eine README-Datei zwar zu lang und detailliert sein kann, aber zu lang besser als zu kurz ist. Wenn Sie der Meinung sind, dass Ihre README zu lang ist, sollten Sie eine andere Form der Dokumentation in Betracht ziehen, anstatt Informationen auszuschneiden.
Name
Wählen Sie einen selbsterklärenden Namen für Ihr Projekt.,
Beschreibung
Lassen Sie die Leute wissen, was Ihr Projekt speziell tun kann. Geben Sie Kontext an und fügen Sie einen Link zu einer Referenz hinzu, mit der Besucher möglicherweise nicht vertraut sind. Eine Liste von Funktionen oder ein Unterabschnitt Hintergrund kann hier ebenfalls hinzugefügt werden. Wenn es Alternativen zu Ihrem Projekt gibt, ist dies ein guter Ort, um differenzierende Faktoren aufzulisten.
Badges
Bei einigen READMEs werden möglicherweise kleine Bilder angezeigt, die Metadaten übermitteln, z. B. ob alle Tests für das Projekt bestanden wurden oder nicht. Sie können Shields verwenden, um einige zu Ihrer README hinzuzufügen. Viele Dienste haben auch Anweisungen zum Hinzufügen eines Badges.,
Visuals
Je nachdem, was Sie machen, kann es eine gute Idee sein, Screenshots oder sogar ein Video aufzunehmen (Sie werden häufig GIFs anstelle von tatsächlichen Videos sehen). Tools wie ttygif können helfen,aber schauen Sie sich Asciinema für eine anspruchsvollere Methode.
Installation
In einem bestimmten Ökosystem kann es eine gängige Möglichkeit geben, Dinge zu installieren, z. B. Yarn, NuGet oder Homebrew. Berücksichtigen Sie jedoch die Möglichkeit, dass jeder, der Ihre README liest, ein Anfänger ist und mehr Anleitung wünscht., Das Auflisten bestimmter Schritte hilft dabei, Mehrdeutigkeiten zu beseitigen, und bringt die Benutzer so schnell wie möglich dazu, Ihr Projekt zu verwenden. Wenn es nur in einem bestimmten Kontext wie einer bestimmten Programmiersprachenversion oder einem bestimmten Betriebssystem ausgeführt wird oder Abhängigkeiten aufweist, die manuell installiert werden müssen, fügen Sie auch einen Unterabschnitt Anforderungen hinzu.
Verwendung
Verwenden Sie Beispiele großzügig und zeigen Sie die erwartete Ausgabe an, wenn Sie können. Es ist hilfreich, das kleinste Anwendungsbeispiel inline zu haben, die Sie demonstrieren können, während Links zu anspruchsvolleren Beispielen Bereitstellung, wenn sie zu lang sind vernünftigerweise in der README aufzunehmen.,
Support
Sagen Sie den Leuten, wohin sie gehen können, um Hilfe zu erhalten. Es kann eine beliebige Kombination aus einem Issue Tracker, einem Chatroom, einer E-Mail-Adresse usw. sein.
Roadmap
Wenn Sie Ideen für zukünftige Releases haben, ist es eine gute Idee, diese in der README aufzulisten.
Beitrag
Geben Sie an, ob Sie für Beiträge offen sind und welche Anforderungen Sie an deren Annahme stellen.
Für Leute, die Änderungen an Ihrem Projekt machen wollen, ist es hilfreich, einige Dokumentation zu haben, wie man loszulegen., Vielleicht gibt es ein Skript, das sie ausführen sollten, oder einige Umgebungsvariablen, die sie festlegen müssen. Machen Sie diese Schritte explizit. Diese Anweisungen könnten auch für Ihr zukünftiges Selbst nützlich sein.
Sie können auch Befehle dokumentieren, um den Code zu linten oder Tests auszuführen. Diese Schritte tragen dazu bei, eine hohe Codequalität sicherzustellen und die Wahrscheinlichkeit zu verringern, dass die Änderungen versehentlich etwas beschädigen. Anweisungen zum Ausführen von Tests sind besonders hilfreich, wenn eine externe Einrichtung erforderlich ist, z. B. das Starten eines Selenium-Servers zum Testen in einem Browser.,
Autoren und Anerkennung
Zeigen Sie Ihre Wertschätzung für diejenigen, die zum Projekt beigetragen haben.
Lizenz
Für Open-Source-Projekte, sagen, wie es lizenziert ist.
Projektstatus
Wenn Ihnen die Energie oder Zeit für Ihr Projekt ausgegangen ist, notieren Sie oben in der README-Datei, dass sich die Entwicklung verlangsamt oder vollständig gestoppt hat. Jemand kann sich dafür entscheiden, Ihr Projekt zu verzweigen oder freiwillig als Betreuer oder Eigentümer einzutreten, damit Ihr Projekt weiterlaufen kann. Sie können auch eine explizite Anfrage für Betreuer stellen.