GitHub-Beitragsworkflow für größere oder langfristige Änderungen

Wichtig

Für alle Repositorys, die in „docs.microsoft.com“ veröffentlichen, gilt der Verhaltenskodex von Microsoft Open Source oder von .NET Foundation (beide in englischer Sprache). Weitere Informationen finden Sie in den häufig gestellten Fragen zum Verhaltenskodex. Wenden Sie sich mit Ihren Fragen oder Kommentaren alternativ an opencode@microsoft.com oder conduct@dotnetfoundation.org.

Für kleinere Korrekturen oder Klarstellungen zu Dokumentation und Codebeispielen in öffentlichen Repositorys gelten die Nutzungsbestimmungen zu docs.microsoft.com. Neue oder signifikante Änderungen haben einen Kommentar im Pull Request zur Folge, in dem Sie gebeten werden, online eine Lizenzvereinbarung für Beiträge (Contribution License Agreement, CLA) zu akzeptieren. Dies gilt, wenn Sie kein Mitarbeiter von Microsoft sind. Sie müssen das Onlineformular ausfüllen, damit wir Ihren Pull Request zusammenführen können.

Übersicht

Dieser Workflow eignet sich für Mitwirkende, die eine größere Änderung vornehmen müssen oder häufig an einem Repository mitwirken werden. Häufig Mitwirkende befassen sich in der Regel mit laufenden (langfristigen) Änderungen, die vor der Genehmigung des Pull Requests und Zusammenführung der Änderungen mehrere Build-/Validierungs-/Stagingzyklen durchlaufen oder sich über mehrere Tage erstrecken.

Zu den Beispielen für diese Arten von Beiträgen zählen:

  • Tragen Sie Wesentliches bei. Sie können beispielsweise Beiträge (Hinzufügungen, Änderungen oder Löschungen) einreichen, die mehrere Artikel betreffen, müssen als eine Arbeitseinheit in einem einzigen Pull Request committet oder getestet werden.
  • Einen neuen Artikel erstellen oder veröffentlichen, was normalerweise einen robusteren lokalen Editor erfordert.
  • Neue Bilder hinzufügen oder Bilder aktualisieren, erfordert in der Regel die gleichzeitige Erstellung eines neuen media-Unterverzeichnisses, Bilddateien, Updates für Bildverknüpfungen in Artikeln und das Anzeigen einer Vorschau von Markdowndateien in einem lokalen Editor, um Bildrendering zu testen.
  • Einen Artikel vor der Veröffentlichung über einen Zeitraum von Tagen aktualisieren. In diesen Fällen müssen Sie normalerweise eine reguläre Integration anderer Änderungen durchführen, die in diesem Standardbranch vorkommen. Diese Integration lässt sich leichter über Git Bash oder durch lokale Bearbeitung vornehmen. Es besteht dabei auch das Risiko, Ihre Änderungen zu verlieren, falls Sie diesen Prozess mithilfe der GitHub-Benutzeroberfläche durchführen. Warten Sie, bevor Sie für die Änderungen ein Commit ausführen.
  • Fortwährende Updates für denselben Artikel durchführen, nachdem ein Pull Request geöffnet wurde (es sei denn, Sie möchten dies lieber über die GitHub-Benutzeroberfläche tun). Die GitHub-Benutzeroberfläche hat das Potential, mehrere herausragende Pull Requests für die gleiche Datei zu erstellen, was zu einem Konflikt mit einer anderen führen kann.

Terminologie

Bevor Sie beginnen, betrachten wir einige der in diesem Workflow verwendeten Git-/GitHub-Begriffe und Moniker. Es macht nichts, wenn Sie sie jetzt noch nicht verstehen. Sie werden sie kennenlernen. Und sollten Sie einmal eine Definition überprüfen wollen, können Sie auf diesen Abschnitt zurückgreifen.

Name Description
Fork Wird beim Verweis auf eine Kopie des GitHub-Repositorys normalerweise als Substantiv verwendet. Praktisch ist ein Fork einfach ein anderes Repository. Aber das Besondere daran ist, dass GitHub eine Verbindung zurück zum Haupt-/übergeordneten Repository aufrechterhält. Der Begriff wird manchmal als Verb verwendet, wie in „Sie müssen zuerst das Repositorys forken“.
Remote Eine benannte Verbindung mit einem Remoterepository, wie ein „Origin“- oder „Uppstreamremote“. Git bezeichnet diese als „Remotes“, weil sie zum Verweis auf ein Repository verwendet wird, das auf einem anderen Computer gehostet wird. In diesem Workflow ist ein Remote immer ein GitHub-Repository.
Origin Der Name der Verbindung zwischen Ihrem lokalen Repository und dem Repository, von dem es geklont wurde. In diesem Workflow stellt Origin die Verbindung mit Ihrem Fork dar. Er wird manchmal als Moniker für das Ursprungsrepository selbst verwendet, wie in „Denken Sie daran, Ihre Änderungen an Origin zu pushen“.
Upstream Wie Originremote ist Upstream eine benannte Verbindung mit einem anderen Repository. In diesem Workflow stellt Upstream die Verbindung zwischen Ihrem lokalen Repository und dem Hauptrepository dar, aus dem Ihr Fork erstellt wurde. Der Begriff wird manchmal als Moniker für das Upstreamrepository selbst verwendet, wie in „Denken Sie daran, Ihre Änderungen vom Upstream zu pullen.“

Workflow

Wichtig

Falls nicht bereits geschehen, müssen Sie die im Bereich Setup beschriebenen Schritte ausführen. Dieser Abschnitt führt Sie durch die Einrichtung Ihres GitHub-Kontos, wobei Git Bash und ein Markdown-Editor installiert, ein Fork erstellt und Ihr lokales Repository eingerichtet wird. Wenn Sie mit Git- und GitHub-Konzepten wie Repository oder Branch nicht vertraut sind, lesen Sie bitte zuerst Git and GitHub essentials (Git- und GitHub-Grundlagen).

In diesem Workflow fließen Änderungen in einen Wiederholungszyklus ein. Vom lokalen Repository Ihres Geräts fließen sie zurück zu Ihrem GitHub-Fork, in das GitHub-Hauptrepository und wieder zum lokalen Repository zurück, während Sie Änderungen anderer Mitwirkender einbeziehen.

Verwenden des GitHub-Flows

In Git- und GitHub-Grundlagen haben Sie gelernt, dass ein Git-Repository einen Standardbranch sowie einige zusätzliche Branches in Bearbeitung enthält, die nicht in den Standardbranch integriert wurden. Immer dann, wenn Sie mehrere logisch verknüpfte Änderungen vornehmen, sollten Sie einen Arbeitsbranch erstellen, um Ihre Änderungen über den Workflow zu verwalten. Hier wird die Bezeichnung „Arbeitsbranch“ verwendet, weil es sich um einen Arbeitsbereich zum Durchlaufen bzw. Optimieren von Änderungen handelt, bis diese wieder in den Standardbranch integriert werden können.

Mit der Isolation zugehöriger Änderungen in einem bestimmten Branch können Sie diese Änderungen unabhängig steuern und einführen und zu einem bestimmten Zeitpunkt im Veröffentlichungszyklus freigeben. Sie könnten abhängig vom Typ Ihrer Arbeit mühelos über mehrere Arbeitsbranches in Ihrem Repository verfügen. Es ist nicht ungewöhnlich, mit mehreren Branches gleichzeitig zu arbeiten, wobei jeder Branch für ein Projekt steht.

Tipp

Es ist keine bewährte Methode, Änderungen im Standardbranch vorzunehmen. Stellen Sie sich vor, Sie verwenden den Standardbranch, um mehrere Änderungen für die Freigabe von Features zu einem bestimmten Zeitpunkt einzuführen. Sie schließen die Änderungen ab und warten auf ihre Freigabe. Dann erhalten Sie in der Zwischenzeit die dringende Anfrage, ein Problem zu beheben, also nehmen Sie die Änderung an einer Datei im Standardbranch vor und veröffentlichen dann die Änderung. In diesem Beispiel veröffentlichen Sie unabsichtlich die Problembehebung und die Änderungen, die Sie zur Freigabe zu einem bestimmten Datum zurückgehalten haben.

Nun erstellen wir einen neuen Arbeitsbranch in Ihrem lokalen Repository, um die von Ihnen vorgeschlagenen Änderungen zu erfassen. Wenn Sie Git Bash eingerichtet haben (Informationen finden Sie unter Installieren von Tools für die Inhaltsentwicklung), können Sie einen neuen Branch erstellen und diesen mit nur einem Befehl innerhalb Ihres geklonten Repositorys „auschecken“:

git checkout -b "branchname"

Jeder Git-Client ist anders, informieren Sie sich also in der Hilfe über die Anforderungen für Ihren bevorzugten Client. Eine Übersicht über den Prozess finden Sie im GitHub-Leitfaden unter GitHub-Flow (in englischer Sprache).

Durchführen von Änderungen

Da Sie nun eine Kopie („Klon“) des Microsoft-Repositorys besitzen und Sie einen Branch erstellt haben, können Sie in einem Text- oder Markdown-Editor beliebige Änderungen durchführen, von denen Sie denken, dass sie für die Community vorteilhaft sein könnten. Weitere Informationen hierzu finden Sie auf der Seite Installieren von Tools für die Inhaltsentwicklung. Sie können Ihre Änderungen lokal speichern und müssen sie nicht an Microsoft übermitteln, wenn Sie noch nicht fertig sind.

Speichern von Änderungen in Ihrem Repository

Bevor Sie Ihre Änderungen an den Autor übermitteln, müssen Sie sie zunächst in Ihrem GitHub-Repository speichern. Da sich alle Tools voneinander unterscheiden, sind nur ein paar einfache Schritte nötig, wenn Sie die Git Bash-Befehlszeile verwenden.

Sie müssen als Vorbereitung für den nächsten Commit zunächst innerhalb des Repositorys alle Ihre Änderungen stagen. Dies kann folgendermaßen geschehen:

git add --all

Als Nächstes müssen Sie Ihre gespeicherten Änderungen in Ihr lokales Repository übernehmen. Dies kann in Git Bash durchgeführt werden, indem Folgendes ausgeführt wird:

git commit -m "Short Description of Changes Made"

Nachdem Sie diesen Branch auf Ihrem lokalen Computer erstellt haben, müssen Sie schließlich den Fork in Ihrem GitHub.com-Konto darüber informieren. Wenn Sie Git Bash verwenden, kann dies folgendermaßen durchgeführt werden:

git push --set-upstream origin <branchname>

Sie haben es geschafft. Ihr Code ist jetzt in Ihrem GitHub-Repository verfügbar, und Sie können damit einen Pull Request erstellen.

Tipp

Obwohl Ihre Änderungen in Ihrem persönlichen GitHub-Konto sichtbar werden, wenn Sie sie pushen, besagt keine Regel, dass Sie sofort einen Pull Request übermitteln müssen. Wenn Sie zu einem späteren Zeitpunkt zurückkehren möchten, um zusätzliche Anpassungen vorzunehmen, ist das ebenfalls in Ordnung.

Müssen Sie etwas beheben, das Sie übermittelt haben? Kein Problem. Führen Sie Ihre Änderungen einfach im selben Branch durch, und führen Sie noch mal einen Commit und einen Pushvorgang durch (der Upstreamserver muss für nachfolgende Pushvorgänge vom selben Branch nicht festgelegt werden).

Durchführen der nächsten Änderung

Müssen Sie darüber hinaus weitere Änderungen durchführen? Kehren Sie zum Standardbranch zurück, führen Sie einen Pullvorgang aus dem Upstreamrepository durch, um sicherzustellen, dass Ihr Fork auf dem neuesten Stand ist, und checken Sie einen neuen Branch aus. Führen Sie in GitBash die folgenden Befehle aus:

git checkout main
git pull upstream main
git checkout -b "branchname"

Hinweis

Bei den obigen Befehlen wird davon ausgegangen, dass das Repository, mit dem Sie arbeiten, main als Standardbranch verwendet. Wenn beim ersten Befehl ein Fehler ausgegeben wird, liegt dies wahrscheinlich daran, dass der Standardbranch nicht umbenannt wurde. Ersetzen Sie main in den ersten beiden Befehlen durch master, um dies zu überprüfen.

Sie befinden sich nun in einem neuen Branch und sind auf dem besten Weg, ein kompetenter Mitwirkender zu werden.

Verarbeitung des Pull Requests

Im vorherigen Abschnitt wurden Sie durch den Prozess zur Übermittlung vorgeschlagener Änderungen durch Bündeln dieser Änderungen in einem neuen Pull Request (PR) geführt, der zur PR-Warteschlange des Zielrepositorys hinzugefügt wurde. Ein Pull Request aktiviert das Modell der Zusammenarbeit von GitHub, indem er anfordert, dass die Änderungen von Ihrem Arbeitsbranch mithilfe von Pull in einen anderen Branch übertragen und darin zusammengeführt werden. In den meisten Fällen ist dieser andere Branch der Standardbranch im Hauptrepository.

Überprüfen

Bevor Ihr Pull Request in seinem Zielbranch zusammengeführt werden kann, ist es möglicherweise notwendig, einen oder mehrere PR-Überprüfungsvorgänge zu durchlaufen. Überprüfungsprozesse können je nach Umfang der vorgeschlagenen Änderungen und den Regeln des Zielrepositorys variieren. Nachdem Ihr Pull Request übermittelt wurde, können Sie erwarten, dass eines der folgenden Ereignisse eintritt:

  • Zusammenführbarkeit: Zunächst wird ein grundlegender Test für GitHub durchgeführt, bei dem geprüft wird, ob das Zusammenführen möglich ist. Es wird überprüft, ob die vorgeschlagenen Änderungen in Ihrem Branch nicht in Konflikt mit dem Zielbranch stehen. Wenn der Pull Request darauf hinweist, dass der Test fehlgeschlagen ist, müssen Sie den Inhalt ausgleichen, der den Konflikt beim Zusammenführen verursacht, bevor die Verarbeitung fortgeführt werden kann.
  • CLA: Wenn Sie zu einem öffentlichen Repository beitragen und nicht bei Microsoft angestellt sind, werden Sie je nach Ausmaß der vorgeschlagenen Änderungen möglicherweise aufgefordert, eine kurze Lizenzvereinbarung für Mitwirkende (Contribution License Agreement, CLA) abzuschließen, wenn Sie das erste Mal einen Pull Request für dieses Repository absenden. Nachdem der CLA-Schritt gelöscht wurde, wird Ihr Pull Request verarbeitet.
  • Bezeichnungen: Bezeichnungen werden automatisch Ihrem Pull Request zugeordnet. Diese werden verwendet, um den Status Ihres Pull Requests anzugeben, wenn er den Validierungsworkflow durchläuft. Beispielsweise erhalten neue Pull Requests womöglich automatisch die Bezeichnung „do-not-merge“ (nicht zusammenführen), was anzeigt, dass der Pull Request die Schritte zur Validierung, Überprüfung und Abmeldung noch nicht abgeschlossen hat.
  • Validierung und Erstellung: Automatische Prüfungen verifizieren, ob Ihre Änderungen die Validierungstests bestehen. Die Validierungstests ergeben womöglich Warnungen oder Fehler. Sie müssen deshalb Änderungen an mindestens einer Datei in Ihrem Pull Request vornehmen, bevor dieser zusammengeführt werden kann. Die Testergebnisse der Validierung werden Ihrem Pull Request als Kommentar zur Überprüfung hinzugefügt und werden Ihnen möglicherweise auch via E-Mail übermittelt.
  • Staging: Die Artikelseiten, die von Ihren Änderungen betroffen sind, können bei erfolgreicher Validierung und Erstellung automatisch in einer Stagingumgebung zur Überprüfung bereitgestellt werden. Vorschau-URLs erscheinen in einem PR-Kommentar.
  • Automatisch zusammenführen: Der Pull Request wird möglicherweise automatisch zusammengeführt, wenn er die Validierungstests besteht und bestimmte Kriterien erfüllt. In diesem Fall sind keine weiteren Schritte nötig.

Überprüfen und Abmelden

Nachdem die gesamte PR-Verarbeitung abgeschlossen wurde, überprüfen Sie die Ergebnisse (PR-Kommentare, Vorschau-URLs usw.), um zu bestimmen, ob weitere Änderungen an diesen Dateien nötig sind, bevor Sie sich für die Zusammenführung abmelden. Wenn ein PR-Prüfer Ihren Pull Request überprüft hat, kann der Prüfer auch mithilfe von Kommentaren Feedback geben, falls es ausstehende Probleme bzw. Fragen vor dem Zusammenführen gibt.

Durch die Kommentarautomatisierung können Benutzer mit Leserechten (Benutzer, die keine Schreibrechte für ein Repository haben) eine Aktion mit Schreibrechten durchführen, indem Sie die entsprechende Bezeichnung einem Pull Request zuweisen. Wenn Sie in einem Repository arbeiten, in dem die Kommentarautomatisierung implementiert wurde, verwenden Sie die Hashtagkommentare, die in der folgenden Tabelle aufgeführt sind, um Bezeichnungen zuzuweisen, zu ändern, oder um einen Pull Request zu schließen. Microsoft-Mitarbeiter werden auch per E-Mail über die Überprüfung und Freigabe öffentlicher Repository-Pull Requests informiert, wenn Änderungen für Artikel vorgeschlagen werden, für die Sie der Autor sind.

Hashtagkommentar Funktionsbeschreibung Repository-Verfügbarkeit
#sign-off Wenn der Autor eines Artikels den Kommentar #sign-off in den Kommentarstream eingibt, wird die Bezeichnung ready-to-merge zugewiesen. Diese Bezeichnung lässt die Bearbeiter im Repository wissen, wann ein Pull Request zur Überprüfung bzw. zum Zusammenführen bereit ist.

Wenn ein Mitwirkender, der nicht der aufgelistete Autor ist, versucht, einen öffentlichen Pull Request mithilfe des Kommentars #sign-off zu genehmigen, wird eine Nachricht im Pull Request angezeigt, dass nur der Autor diese Bezeichnung zuweisen kann.
Öffentlich und privat
#hold-off Autoren können #hold-off in einen PR-Kommentar eingeben, um die Bezeichnung ready-to-merge zu entfernen, im Fall, dass sie ihre Meinung geändert oder einen Fehler gemacht haben. Im privaten Repository wird die Bezeichnung do-not-merge zugewiesen. Öffentlich und privat
#please-close Autoren können #please-close in den Kommentarstream eingeben, um den Pull Request zu schließen, wenn sie sich dazu entscheiden, die Änderungen nicht zu mergen. Öffentlich

Wenn der Pull Request fehlerfrei und abgemeldet ist, werden Ihre Änderungen von einem übergeordneten Branch zusammengeführt, und der Pull Request wird geschlossen.

Veröffentlichung

Denken Sie daran, dass Ihr Pull Request von einem PR-Prüfer zusammengeführt werden muss, bevor die Änderungen im nächsten geplanten Veröffentlichungsdurchlauf eingeschlossen werden können. Pull Requests werden normalerweise in der Reihenfolge überprüft bzw. zusammengeführt, in der sie übermittelt wurden. Wenn Ihr Pull Request eine Zusammenführung für einen bestimmten Veröffentlichungsdurchlauf erfordert, müssen Sie mit Ihrem PR-Prüfer vorzeitig daran arbeiten, um sicherzustellen, dass die Zusammenführung vor der Veröffentlichung ausgeführt wird.

Nachdem Ihre Beiträge genehmigt und zusammengeführt wurden, werden Sie vom Veröffentlichungsprozess von docs.microsoft.com übernommen. Die Veröffentlichungszeiten können je nach Team, das das Repository verwaltet, zu dem Sie beitragen, variieren. Artikel, die unter folgenden Pfaden veröffentlicht werden, werden normalerweise um 10:30 Uhr und 15:30 Uhr (UTC) von Montag bis Freitag veröffentlicht.

Es kann bis zu 45 Minuten dauern, bis Artikel nach der Veröffentlichung online erscheinen. Nachdem Ihr Artikel veröffentlicht wurde, können Sie Ihre Änderungen unter folgender URL überprüfen: https://docs.microsoft.com/<path-to-your-article-without-the-md-extension>.

Nächste Schritte

Das ist alles! Sie haben einen Beitrag zum Inhalt von docs.microsoft.com geleistet!

  • Navigieren Sie zum Artikel Markdownreferenz, um mehr über Themen wie Markdown und Markdownerweiterungssyntax zu erfahren.