Wichtige Änderungen an der Microsoft Learn-Dokumentation vornehmen

Artikel
02/01/2024

Wichtig

Für alle Repositories, die auf Microsoft Learn veröffentlichen, gelten die Open-Source-Verhaltensregeln von Microsoft oder die Verhaltensregeln der .NET Foundation. Weitere Informationen finden Sie unter Häufig gestellte Fragen zum Verhaltenskodex. Wenden Sie sich mit Ihren Fragen oder Kommentaren alternativ an opencode@microsoft.com oder conduct@dotnetfoundation.org.

Kleinere Korrekturen oder Klarstellungen an Dokumentation und Codebeispielen in öffentlichen Repositorys werden durch die Nutzungsbedingungen von learn.microsoft.com abgedeckt. Jegliche Ä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.

Dieser Artikel zeigt Ihnen, wie Sie einen Microsoft Learn-Artikel mit lokalen Tools ändern können. Er eignet sich für Mitarbeiter, die eine wichtige Änderung vornehmen müssen oder häufig zu einem Repository beitragen werden. Häufig Mitwirkende haben in der Regel laufende oder lang andauernde Änderungen, die mehrere Build-/Validierungs-/Staging-Zyklen durchlaufen oder sich über mehrere Tage erstrecken, bevor sie ihren Pull Request (PR) abzeichnen.

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

Tragen Sie Wesentliches bei. Ihre Beiträge (Ergänzungen, Änderungen oder Löschungen) können sich beispielsweise über mehrere Artikel hinweg erstrecken und müssen als eine Arbeitseinheit in einem einzigen PR übermittelt und getestet werden.
Einen neuen Artikel erstellen oder veröffentlichen, was normalerweise einen robusteren lokalen Editor erfordert.
Neue Bilder hinzufügen oder Bilder aktualisieren, was in der Regel erfordert, dass Sie gleichzeitig ein neues media-Unterverzeichnis anlegen, Bilddateien erstellen, Bildverknüpfungen in Artikeln aktualisieren und eine Vorschau von Markdown-Dateien in einem lokalen Editor anzeigen, um die Darstellung von Bildern 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-Web Editor durchführen. Warten Sie, bevor Sie für die Änderungen ein Commit ausführen.
Kontinuierliche Aktualisierungen desselben Artikels, nachdem ein PR eröffnet wurde Sie können zwar den GitHub-Web-Editor für diesen Zweck verwenden, aber Sie sollten auch mehrere ausstehende PRs für dieselbe Datei erstellen, die miteinander in Konflikt geraten könnten.

Voraussetzungen

Identifizieren Sie das GitHub-Repository, in dem die Dokumentation gespeichert ist, die Sie bearbeiten möchten.
Erstellen Sie ein GitHub-Konto, wenn Sie noch keines besitzen.
Installieren Sie die Git- und Markdown-Tools
Richten Sie ein lokales Git-Repository ein
Arbeiten Sie die Grundlagen von Git und GitHub durch (optional)

Erstellen und Auschecken Ihres Arbeitsbranchs

Erstellen Sie zunächst einen neuen Arbeitszweig in Ihrem lokalen Repository, um die vorgeschlagenen Änderungen zu erfassen. Weitere Hintergrundinformationen zu Verzweigungen finden Sie unter Git- und GitHub-Grundlagen.

Diese Anleitung verwendet Git Bash und Visual Studio Code, aber Sie können jeden beliebigen Git-Client und -Editor verwenden.

Öffnen Sie in VS Code den Repository-Ordner Ihres lokalen Klons. Wählen Sie im Menü Datei die Option Ordner öffnen und navigieren Sie zu dem Ordner auf Ihrem Computer.
Wählen Sie im oberen Menü Ansicht und dann Terminal, um das integrierte Terminal zu öffnen.
Vergewissern Sie sich im integrierten Terminal, dass Sie sich im Repository-Ordner befinden.
Bevor Sie einen Arbeitsbranch erstellen, vergewissern Sie sich, dass Ihr lokaler Mainbranch und der Mainbranch des Produktions-Repositorys auf dem neuesten Stand sind. Diese Aufgabe stellt sicher, dass Ihr Arbeitsbranch alle Änderungen erfasst, die seit dem letzten Abgleich mit dem Produktions-Repository vorgenommen wurden.
1. Wechseln Sie zum Standardbranch in Ihrem lokalen Repository:
```
git checkout main 
```
2. Stellen Sie sicher, dass Ihr lokaler Standardbranch aktuell ist:
```
git pull upstream main 
```
Erstellen Sie einen lokalen Arbeitsbranch basierend auf dem Mainbranch:
```
git checkout -b <branch-name>
```
<branch-name> ist ein Platzhalter. Wenn Sie den Befehl ausführen, ersetzen Sie ihn durch einen eindeutigen und aussagekräftigen Namen für Ihren Branch, und entfernen Sie die eckigen Klammern.
Verschieben Sie den lokalen Arbeitsbranch in den Remotebranch in Ihrem GitHub-Fork:
```
git push origin <branch-name> -u
```
Die -u-Option verknüpft die lokalen und Remoteverzweigungen. Mit dieser Option können Sie Commits an Ihren Branch übertragen, indem Sie einfach git push anstelle von git push origin <branch-name> eingeben.

Suchen der Markdown-Quelldatei

Um einen Artikel zu bearbeiten, suchen Sie die Quelldatei für den Artikel im lokalen Repository-Klon. Greifen Sie in VS Code über den Datei-Explorer (ein Dokumentsymbol in der oberen linken Randleiste) auf die Markdown-Dateien des Repositorys zu. Der Datei-Explorer zeigt die Ordnerstruktur des Repositorys an, und Sie können zu der Datei navigieren, die Sie bearbeiten möchten.

Wenn Sie die Datei nicht finden können, besuchen Sie den Artikel in Microsoft Learn, und wählen Sie das Stiftsymbol Bearbeiten aus. Der relative Ordnerspeicherort im GitHub-Repository wird in der URL angezeigt. Hier ist ein Beispiel zum Bearbeiten der Link-URL:

   https://github.com/Microsoft/azure-docs/blob/main/articles/azure-functions/functions-overview.md

Hier ist ein Beispieldateispeicherort für diese URL.

   C:\GitHub\*\azure-docs\articles\azure-functions\functions-overview.md

Bearbeiten Sie die Datei .

Öffnen Sie die Datei in VS Code, indem Sie sie auswählen.
Nehmen Sie Ihre Änderungen vor.
Speichern Sie Ihre Änderungen durch Auswahl von Datei>Speichern. Verwenden Sie Alle speichern, um mehrere Dateien gleichzeitig zu speichern.

Bestätigen und Veröffentlichen Ihrer Änderungen

Wenn Sie wesentliche Änderungen vorgenommen oder einen Artikel auf Aktualität überprüft haben, aktualisieren Sie ms.date im Metadatenblock oben in der Datei. Das Datumsformat lautet MM/TT/JJJJ.

Sie können das VS Code-Terminal oder die VS-Codebenutzeroberfläche verwenden, um Ihre Änderungen zu übernehmen bzw. zu übertragen.

VS Code Terminal
VS-Codebenutzeroberfläche

Führen Sie den git status-Befehl aus, um zu überprüfen, ob nur die bearbeiteten Dateien in der Liste der geänderten Dateien angezeigt werden.
```
git status
```
Führen Sie den git add-Befehl gefolgt vom Dateipfad und Dateinamen aus, um die von Ihnen geänderte Datei bereitzustellen.
```
git add folder-name/file-name.md
```
Wenn Sie mehrere Dateien geändert haben, geben Sie für jede Datei einen git add-Befehl ein.

Alternativ dazu können Sie auch git add . (beachten Sie den Punkt nach add) ausführen, um alle von Ihnen vorgenommenen Änderungen automatisch zu übernehmen. Diese Methode ist schneller, kann jedoch Probleme verursachen, indem versehentlich vorgenommene Änderungen miteinbezogen werden.
Führen Sie git status erneut aus, um zu bestätigen, um zu bestätigen, welche Änderungen vorgenommen wurden.
Führen Sie den git commit-Befehl gefolgt von einer Commitnachricht aus, um die Änderungen in Ihrem lokalen geklonten Repository zu speichern.
```
git commit -m "your commit message"
```
Führen Sie den git push-Befehl aus, um Ihre Änderungen zu übertragen.
```
git push
```

Sie können mit den Git-Integrationsfunktionen von VS Code einen Commit erstellen und veröffentlichen. Denken Sie daran, ihre Arbeit auf demselben Computer fortzusetzen. Wenn Sie Computer wechseln, verfügen Sie nicht über die neueste Version der Arbeitsbranches, um fortfahren zu können.

Vergewissern Sie sich, dass Ihr lokales Repository immer noch denselben Arbeitsbranch ausgecheckt hat. In der VS Code-Benutzeroberfläche wird der Zweig links unten angezeigt. Der Branchname dient auch als Schaltfläche zum Switchen zwischen Zweigen.
Wählen Sie in der linken Seitenleiste von VS Code das Fork-Tool, um den Bereich Quellcodeverwaltung: Git anzuzeigen.

Die von Ihnen bearbeitete Datei erscheint unter Änderungen mit einem M auf der rechten Seite, um anzuzeigen, dass sie geändert wurde. Neue Dateien werden mit einem U (für „Unverfolgt“) und gelöschte Dateien mit einem D gekennzeichnet.
Nehmen Sie die Änderungen vor. Bewegen Sie den Mauszeiger über die Zeile Änderungen, bis ein +-Symbol erscheint. Das entsprchende Bearbeitensymbol auswählen Diese Aktion entspricht dem git add-Befehl. Die Datei erscheint nun im Bereich Gestagete Änderungen.
Geben Sie in das Textfeld Nachricht eine Commit-Nachricht ein, z. B. „Datum der Aktualisierung der Metadaten“, und setzen Sie das Häkchen.
Lösen Sie das Committen aus. Wählen Sie die Schaltfläche Änderungen synchronisieren aus, die unterhalb des Commit-Nachrichtenblocks angezeigt wird.

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

Müssen Sie etwas beheben, das Sie übermittelt haben? Es ist ganz leicht! Wiederholen Sie einfach die obigen Schritte, beginnend mit Die Datei bearbeiten, um Änderungen im selben Zweig vorzunehmen und dann erneut zu committen und zu pushen (es ist nicht nötig, den Upstream-Server bei nachfolgenden Pushes desselben Zweigs zu setzen). Im Allgemeinen werden Branches verwendet, um Arbeitsströme zu trennen. Sie müssen also nur dann einen neuen Branch erstellen, wenn Sie an etwas anderem arbeiten möchten.

Durchführen Ihrer nächsten Änderung

Sind Sie bereit, eine weitere Änderung vorzunehmen, die nichts mit dieser zu tun hat? Kehren Sie zum Standardbranch zurück, führen Sie einen Pullvorgang aus dem Upstreamrepository durch, um Ihr Fork zu aktualisieren, 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"
git push origin <branch-name> -u

Sie befinden sich nun in einem neuen Branch, der mit Ihrem Remotebranche verknüpft ist, und sind bereit, weitere Änderungen vorzunehmen. Sie sind auf dem besten Weg, ein Experte zu werden!

Nächste Schritte

Wenn Sie die obigen Schritte durchgeführt haben, ist es nun an der Zeit, einen PR zu öffnen, um Ihre Änderungen in den Mainbranch einzubringen.
Wenn Sie mehr über Themen wie die Syntax von Markdown und Markdown-Erweiterungen erfahren möchten, lesen Sie die Markdown-Referenz.