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 | Azure DevOps Server 2020
Ihr Git-Repository sollte über eine Infodatei verfügen, damit Die Benutzer wissen, was Ihr Code tut und wie er mit der Verwendung beginnen kann. Ihre Infodatei sollte mit den folgenden Zielgruppen sprechen:
- Benutzer, die nur 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 Infodatei in Markdown anstelle von Nur-Text. Markdown erleichtert das Formatieren von Text, das Einfügen von Bildern und den Link nach Bedarf zu weiteren Dokumentationen aus Ihrer Infodatei.
Hier sind einige großartige Lesevorgänge, die dieses Format verwenden und zu allen drei Publikumsgruppen sprechen, 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. – Legen Sie Verzweigungs- oder Repositoryberechtigungen fest: Berechtigungen für die Verzweigung oder das Repository verwalten . - Standardverzweigung ändern: Bearbeiten von Richtlinienberechtigungen für das Repository. - Importieren eines Repositorys: Mitglied der Sicherheitsgruppe "Projektadministratoren " oder "Git-Projektebene Repository erstellen"-Berechtigungssatz auf "Zulassen". 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 Infodatei mit einer kurzen Erläuterung, die Ihr Projekt beschreibt. Fügen Sie einen Screenshot oder animierte GIF in Ihrer Einführung 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. Apps und Tools, die nur auf bestimmten Plattformen ausgeführt werden, sollten die unterstützten Betriebssystemversionen in diesem Abschnitt der Infodatei enthalten.
Helfen Sie Ihren Benutzern bei den ersten Schritten
Führen Sie Die Benutzer durch das Einrichten und Ausführen Ihres Codes auf ihrem eigenen System im nächsten Abschnitt Ihrer Infodatei. 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 Einrichtungsschritte ausführen, dokumentieren Sie diese außerhalb Ihrer Infodatei, und verknüpfen Sie sie.
Verweisen Sie darauf, wo Sie die neueste Version Ihres Codes abrufen. Ein binäres Installationsprogramm oder Anweisungen zur Verwendung ihres Codes über Pakettools ist 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 anzeigt, und zeigen Sie die Beispielausgabe für den Code in diesem Codeausschnitt an.
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:
- 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 in einer separaten Seite in Ihrer Dokumentation, und verknüpfen Sie sie bei Bedarf mit ihr.
- 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 der Entwickler, der sich auf diese Anweisungen stützt, möglicherweise einige Zeit lang nicht an einem Projekt arbeitet.
Stellen Sie die Befehle bereit, 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 unterbrechen, wenn sie Änderungen vornehmen. Gute Testfälle dienen auch als Beispiele, mit denen Entwickler beim Hinzufügen neuer Funktionen eigene Testfälle erstellen können.
Unterstützen von Benutzern bei der Mitwirkung
Der letzte Abschnitt Ihrer Infodatei hilft Benutzern und Entwicklern, sich an der Berichterstattung von Problemen zu beteiligen 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.