Hinweis
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, sich anzumelden oder das Verzeichnis zu wechseln.
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, das Verzeichnis zu wechseln.
Azure DevOps Services | Azure DevOps Server | Azure DevOps Server 2022
Ihr Git-Repository sollte über eine README-Datei verfügen, damit Benutzer wissen, was Ihr Code tut und wie sie mit der Verwendung beginnen können. Ihre README-Datei sollte mit den folgenden Zielgruppen sprechen:
- Benutzer, die Ihren Code 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 Entwickler und Benutzer.
Schreiben Sie Ihre README-Datei in Markdown anstelle von Nur-Text. Markdown erleichtert das Formatieren von Text, das Einschließen von Bildern und einen Link zu weiteren Dokumentationen aus der README-Datei.
Hier sind einige README-Dateien, die dieses Format verwenden und mit allen drei Zielgruppen sprechen. Verwenden Sie sie für Referenz und Inspiration:
Voraussetzungen
| Kategorie | Anforderungen |
|---|---|
| Projektzugriff | Mitglied eines Projekts. |
| Erlaubnisse | - Code in privaten Projekten anzeigen: Mindestens einfacher Zugriff. - Klonen oder Mitwirken an Code in privaten Projekten: Mitglied der Sicherheitsgruppe "Mitwirkende" oder entsprechende Berechtigungen im Projekt. - Verzweigungs- oder Repository-Berechtigungen festlegen: "Berechtigungen verwalten" sind Berechtigungen für die Verzweigung oder das Repository. - Standard-Branch ändern: Bearbeitungsrichtlinien sind Berechtigungen für das Repository. - Importieren eines Repositorys: Mitglied der Sicherheitsgruppe "Projektadministratoren" oder Git-Projektebene-Berechtigung "Repository erstellen" auf "Zulassen" gesetzt. Weitere Informationen finden Sie unter Festlegen von Git-Repositoryberechtigungen. |
| Dienste | Repos aktiviert. |
| Werkzeuge | Wahlfrei. Verwenden Sie az repos Befehle: Azure DevOps CLI. |
Hinweis
In öffentlichen Projekten haben Benutzer mit Stakeholder-Zugriff vollzugriff auf Azure Repos, einschließlich Anzeigen, Klonen und Beitragen zu Code.
| Kategorie | Anforderungen |
|---|---|
| Projektzugriff | Mitglied eines Projekts. |
| Erlaubnisse | - Code anzeigen: Mindestens einfacher Zugriff. - Klonen oder Zum Code beitragen: Mitglied der Sicherheitsgruppe "Mitwirkende " oder entsprechende Berechtigungen im Projekt. |
| Dienste | Repos aktiviert. |
Erstellen einer Einführung
Beginnen Sie Ihre README-Datei mit einer kurzen Erläuterung, die Ihr Projekt beschreibt. Fügen Sie in Ihrer Einführung einen Screenshot oder animierte GIF hinzu, wenn Ihr Projekt über eine Benutzeroberfläche verfügt. Wenn Ihr Code auf einer anderen Anwendung oder Bibliothek basiert, müssen Sie diese Abhängigkeiten in der Einführung oder direkt darunter angeben. Apps und Tools, die nur auf bestimmten Plattformen ausgeführt werden, sollten die unterstützten Betriebssystemversionen in diesem Abschnitt der README-Datei enthalten.
Helfen Sie Ihren Benutzern bei den ersten Schritten
Führen Sie im nächsten Abschnitt Ihrer README-Datei die Benutzer durch das Einrichten und Ausführen ihres Codes auf ihrem eigenen System. Konzentrieren Sie sich auf die wesentlichen Schritte, um mit Ihrem Code zu beginnen. Verknüpfen Sie die erforderlichen Versionen jeder erforderlichen Software, damit Benutzer sie ganz einfach erreichen können. Wenn Sie komplexe Setupschritte ausführen, dokumentieren Sie diese Schritte außerhalb Der README-Datei, und verknüpfen Sie sie.
Informieren Sie Leser, wo die neueste Version zu erhalten ist. Stellen Sie eines der folgenden Elemente bereit:
- Eine Verknüpfung mit einem Binärinstallationsprogramm oder einem vordefinierten Paket.
- Installationsanweisungen mithilfe eines Paket-Managers (z. B. npm install, pip install, or dotnet add package).
Wenn Es sich bei Ihrem Projekt um eine Bibliothek oder einen API-Wrapper handelt, fügen Sie einen minimalen Codeausschnitt ein, der die grundlegende Verwendung anzeigt, gefolgt von der erwarteten Ausgabe. Diese Informationen helfen Lesern, ihre Einrichtung zu überprüfen und zu verstehen, was die Bibliothek auf einen Blick tut.
Bereitstellen von Buildschritten für Entwickler
Verwenden Sie den nächsten Abschnitt Ihrer README-Datei, um Entwicklern zu zeigen, wie Sie Ihren Code aus einem neuen Klon des Repositorys erstellen und alle enthaltenen Tests ausführen. Führen Sie die folgenden Schritte aus:
- Geben Sie Details zu den Tools an, die zum Erstellen des Codes erforderlich sind, und dokumentieren Sie die Schritte zum Konfigurieren, um einen sauberen Build zu erhalten.
- Unterteilen Sie dichte oder komplexe Buildanweisungen auf einer separaten Seite in Ihrer Dokumentation und verlinken Sie bei Bedarf darauf.
- Führen Sie die Anweisungen durch, während Sie sie schreiben, um zu überprüfen, ob die Anweisungen für einen neuen Mitwirkenden funktionieren.
Denken Sie daran, dass Sie möglicherweise der Entwickler sind, der diese Anweisungen verwendet, nachdem Sie noch einige Zeit nicht an einem Projekt gearbeitet haben.
Schließen Sie die Befehle ein, um Testfälle auszuführen, die nach einem erfolgreichen Build mit dem Quellcode bereitgestellt werden. Entwickler stützen sich auf diese Testfälle, um sicherzustellen, dass sie Ihren Code nicht unterbrechen, wenn sie Änderungen vornehmen. Gute Testfälle dienen auch als Beispiele, mit denen Entwickler eigene Testfälle erstellen können, wenn sie neue Funktionen hinzufügen.
Unterstützen von Benutzern bei der Mitwirkung
Der letzte Abschnitt Ihrer README-Datei hilft Benutzern und Entwicklern, probleme zu melden und Ideen vorzuschlagen, um Ihren Code besser zu gestalten. Benutzer sollten mit Kanälen verknüpft sein, in denen sie Fehler öffnen, Features anfordern oder Hilfe bei der Verwendung Ihres Codes erhalten können.
Entwickler müssen wissen, welche Regeln sie befolgen müssen, um Änderungen beizutragen, z. B. Codierungs-/Testrichtlinien und Pullanforderungsanforderungen. Wenn Sie eine Mitwirkendevereinbarung benötigen, um Pull-Anforderungen zu akzeptieren oder einen Community-Verhaltenskodex durchzusetzen, sollte dieser Prozess mit diesem Abschnitt verknüpft oder dokumentiert werden. Geben Sie an, unter welcher Lizenz der Code veröffentlicht wird, und verknüpfen Sie den vollständigen Text der Lizenz.