Wichtige Änderungen an der Microsoft Learn-Dokumentation vornehmen

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 video2.skills-academy.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

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.

  1. Ö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.

  2. Wählen Sie im oberen Menü Ansicht und dann Terminal, um das integrierte Terminal zu öffnen.

  3. Vergewissern Sie sich im integrierten Terminal, dass Sie sich im Repository-Ordner befinden.

  4. 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 
      
  5. 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.

  6. 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 .

  1. Öffnen Sie die Datei in VS Code, indem Sie sie auswählen.
  2. Nehmen Sie Ihre Änderungen vor.
  3. 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.

  1. 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
    
  2. 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.

  3. Führen Sie git status erneut aus, um zu bestätigen, um zu bestätigen, welche Änderungen vorgenommen wurden.

  4. 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"
    
  5. Führen Sie den git push-Befehl aus, um Ihre Änderungen zu übertragen.

    git push
    

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.