Erstellen einer INFO-Datei für Ihr Repository

  • Artikel

Azure DevOps Services | Azure DevOps Server 2022 | Azure DevOps Server 2019

Ihr Git-Repository sollte über eine Infodatei (Readme) verfügen, damit die Benutzer wissen, was Ihr Code tut und wie sie mit seiner Verwendung beginnen können. Ihre Infodatei sollte folgende Benutzergruppen ansprechen:

  • Benutzer, die Ihren Code nur ausführen möchten.
  • Entwickler, die Ihren Code erstellen und testen möchten. Entwickler sind auch Benutzer.
  • Mitwirkende, die Änderungen an Ihrem Code übermitteln möchten. Mitwirkende sind sowohl Entwickler als auch Benutzer.

Schreiben Sie Ihre Infodatei in Markdown anstatt „Nur-Text“. Markdown erleichtert das Formatieren von Text, das Einfügen von Bildern und ggf. das Verlinken zu weiteren Dokumentationen aus Ihrer Infodatei.

Hier sehen Sie zu Referenz- und Inspirationszwecken einige großartige Infodateien, die dieses Format verwenden und sich an alle drei Benutzergruppen wenden:

Erstellen einer Einführung

Beginnen Sie Ihre Infodatei mit einer kurzen Erläuterung, die Ihr Projekt beschreibt. Fügen Sie ihrer Einführung einen Screenshot oder ein animiertes GIF hinzu, wenn Ihr Projekt über eine Benutzeroberfläche verfügt. Wenn Ihr Code auf einer anderen Anwendung oder Bibliothek basiert, stellen Sie sicher, dass Sie diese Abhängigkeiten in der Einführung oder direkt darunter angeben. Für Apps und Tools, die sich nur auf bestimmten Plattformen ausführen lassen, sollten in diesem Abschnitt der Infodatei die unterstützten Betriebssystemversionen angegeben werden.

Ihren Benutzern bei den ersten Schritten helfen

Führen Sie Benutzer im nächsten Abschnitt Ihrer Infodatei durch das Einrichten und Ausführen ihres Codes auf ihrem eigenen System. Konzentrieren Sie sich dabei auf die wichtigsten Schritte, um mit Ihrem Code loslegen zu können. Verlinken Sie die erforderlichen Versionen jeglicher vorausgesetzter Software, damit Benutzer diese problemlos erhalten können. Wenn bei Ihnen komplexe Einrichtungsschritte vorkommen, dokumentieren Sie diese außerhalb Ihrer Infodatei, und verlinken Sie diese.

Weisen Sie darauf hin, wo das neueste Release Ihres Codes zu erhalten ist. Ein binäres Installationsprogramm oder Anweisungen zur Verwendung Ihres Codes über Paketerstellungstools sind am besten geeignet. Wenn es sich bei Ihrem Projekt um eine Bibliothek oder eine Schnittstelle zu einer API handelt, fügen Sie einen Codeausschnitt ein, der die grundlegende Verwendung demonstriert, und zeigen Sie eine Beispielausgabe für den Code in diesem Codeausschnitt.

Bereitstellen von Buildschritten für Entwickler

Verwenden Sie den nächsten Abschnitt Ihrer Infodatei, um Entwicklern zu zeigen, wie Sie Ihren Code aus einem neuen Klon des Repositorys erstellen und alle enthaltenen Tests ausführen. Gehen Sie folgendermaßen vor:

  • Teilen Sie Details zu den Tools mit, die zum Erstellen des Codes erforderlich sind, und dokumentieren Sie die Schritte, um sie so zu konfigurieren, dass man einen sauberen Build erhält.
  • Brechen Sie dichte oder komplexe Buildanweisungen auf eine separate Seite in Ihrer Dokumentation heraus, und verlinken Sie diese bei Bedarf.
  • Führen Sie die Anweisungen durch, während Sie sie schreiben, um zu überprüfen, ob die Anweisungen für einen neuen Mitwirkenden funktionieren würden.

Denken Sie daran, dass der Entwickler, der auf diese Anweisungen angewiesen ist, Sie selbst sein können, nachdem Sie für einige Zeit nicht mehr an einem Projekt gearbeitet haben.

Geben Sie die Befehle an, um alle Testfälle auszuführen, die mit dem Quellcode bereitgestellt werden, nachdem der Build erfolgreich war. Entwickler stützen sich auf diese Testfälle, um sicherzustellen, dass sie Ihren Code nicht beschädigen, wenn sie Änderungen vornehmen. Gute Testfälle dienen außerdem als Beispiele, die Entwickler verwenden können, um ihre eigenen Testfälle zu erstellen, wenn sie neue Funktionen hinzufügen.

Benutzer bei der Mitwirkung unterstützen

Der letzte Abschnitt Ihrer Infodatei hilft Benutzern und Entwicklern, sich an der Meldung von Problemen zu beteiligen und Verbesserungsvorschläge zu Ihrem Code zu unterbreiten. Benutzer sollten mit Kanälen verknüpft werden, über die sie Fehler öffnen, Features anfordern oder Hilfe zur Verwendung Ihres Codes erhalten können.

Entwickler müssen wissen, welche Regeln sie befolgen müssen, um Änderungen beizutragen, z. B. Programmier-/Testrichtlinien und Pull Request-Anforderungen. Wenn Sie eine Mitwirkungsvereinbarung verlangen, um Pull Requests anzunehmen, oder Verhaltensregeln für die Community erzwingen, sollte dieser Prozess in diesem Abschnitt verlinkt oder dokumentiert werden. Geben Sie an, unter welcher Lizenz der Code freigegeben wird, und verlinken Sie den vollständigen Text der Lizenz.