Grundlagen zum Mitwirken an Microsoft Learn

  • 6 Minuten

Es gibt einige Begriffe, die Sie kennen sollten, um den Mitwirkungsprozess zu verstehen und umzusetzen. Sie müssen nicht alles wissen, was unter der Haube passiert, aber eine allgemeine Übersicht über den Mitwirkungsprozess hilft Ihnen dabei, zu verstehen, warum er auf diese Weise gestaltet wurde.

Grundlagen zu Microsoft Learn und GitHub

Microsoft Learn enthält Tausende von Artikeln, Schulungsmodulen, Webseiten und mehr, die gespeichert und regelmäßig von Mitwirkenden aufgerufen werden müssen. Microsoft Learn verwendet GitHub, um einen Großteil dieser Inhalte zu speichern. GitHub ist eine Plattform, die das verteilte Versionskontrollsystem Git verwendet, um Projekte zu speichern und die Zusammenarbeit von mehreren Beteiligten mit verschiedenen Projektzielen und Zeitplänen zu erleichtern. Die Git- und GitHub-Software ermöglichen es Ihnen, parallel mit anderen Mitwirkenden am selben Projekt zu arbeiten, möglicherweise sogar gleichzeitig an identischen Inhalten, ohne unbeabsichtigt die Arbeit anderer zu beeinträchtigen.

Inhalte werden in Dateien in Git-Repositorys (Repos) gespeichert, die auf GitHub gehostet werden. Ein Repository ist eine Speichereinheit, die die Dateien und den Dateirevisionsverlauf eines Projekts enthält. Repositorys können öffentlich oder privat sein, und Microsoft Learn besteht aus einer Mischung aus beiden. Jede*r mit einem GitHub-Konto kann an öffentlichen Repositorys mitwirken. Private Repositorys sind nur für Mitwirkende verfügbar, die Microsoft-Mitarbeiter*innen sind oder denen besondere Berechtigungen erteilt wurden.

Vornehmen von Änderungen an Microsoft Learn-Inhalten, die in einem GitHub-Repository gespeichert werden

Für jedes Projekt hostet GitHub das Mainrepository und alle Forks. Ein Fork ist eine Kopie des Mainrepositorys, die ein*e Mitwirkende*r für seine oder ihre eigene Arbeit erstellt. Ein Fork ist eine der Methoden von GitHub, um die veröffentlichten Inhalte zu schützen. Anstatt Inhalte direkt im veröffentlichten Livebranch des Mainrepositorys zu bearbeiten, erstellt GitHub eine Momentaufnahme dieser Inhalte für Ihren Fork, sodass Sie dort Ihre Änderungen vornehmen können.

GitHub-Repositorys enthalten einen oder mehrere Branches. Ein Branch ist eine Speichereinheit, die die Dateien und Ordner enthält, aus denen der Inhalt eines Projekts besteht. Alle Repositorys, unabhängig davon, ob es sich um das Mainrepository oder einen Fork handelt, enthalten einen Standardbranch (in der Regel „Mainbranch“ genannt) und einen oder mehrere Branches, die später mit dem Standardbranch gemergt werden sollen. Der Standardbranch dient für das Projekt als aktuelle und allgemeingültige Version. Er ist der übergeordnete Branch, aus dem alle anderen Branches in dem Repository erstellt werden.

Diagram showing a working branch off of the main branch in a GitHub repo. Changes are made in the working branch then merged back to main.

Das Bearbeiten eines Dokumentationsartikels in einem öffentliches Repository mag erscheinen, als ob es mit dem Auswählen einer Schaltfläche beginnen würde, aber geschieht einiges hinter der Kulisse. Wenn Sie den browserbasierten Bearbeitungsprozess starten, wird ein Fork des Repositorys erstellt (sofern noch keiner vorhanden ist) und für Ihre Änderungen verwendet. Sie nehmen die Bearbeitungen innerhalb eines Branches Ihres Forks vor, der später mit dem Livebranch des Mainrepositorys gemergt wird, damit Ihre Änderungen für alle verfügbar sind.

Erstellen eines Pull Requests

Wie läuft ein Merge ab? Sie müssen GitHub – insbesondere den Besitzer*innen des Mainrepositorys und den Autor*innen des Artikels – mitteilen, dass Ihre Bearbeitungen abgeschlossen und für die Überprüfung und Veröffentlichung bereit sind. Hierfür erstellen und übermitteln Sie einen Pull Request.

Ein Pull Request (PR) ist ein Vorschlag, dass Ihre Änderungen aus dem Branch in Ihrem Fork mit dem Standardbranch bzw. Mainbranch des Liverepositorys gemergt werden sollen. Wenn Sie in einem öffentlichen Repository arbeiten, werden Ihre Pull Requests immer von einem oder einer menschlichen Reviewer*in überprüft, bevor sie gemergt werden. Möglicherweise gibt es auch einige automatisierte Überprüfungen, z. B. für Mergekompatibilität und Buildvalidierung. Sobald diese Reviews abgeschlossen sind und alle Probleme behoben wurden, werden Ihre Änderungen mit dem Livebranch zusammengeführt und sind auf Microsoft Learn verfügbar.

Workflow für kleinere Beiträge zur Dokumentation

Zusammenfassend befolgen Sie diese allgemeinen Schritte, wenn Sie kleine Änderungen an der Microsoft-Dokumentation mithilfe des Web-Editors in GitHub vornehmen:

Diagram of the contribution process for contributing to open source documentation on Microsoft Learn.

  1. Wenn Sie eine Datei in Ihrem Browser zum Bearbeiten öffnen, wird automatisch ein Fork der öffentliches Repository für Sie erstellt. Außerdem wird ein Branch in Ihrem Fork erstellt, der häufig als Patchbranch bezeichnet wird.
  2. Nehmen Sie Ihre Änderungen an der Datei vor.
  3. Erstellen Sie einen Pull Request, um vorzuschlagen, dass Ihre Änderungen überprüft und gemergt werden.
  4. Ihr PR darf keine Probleme aufweisen und muss alle Reviews bestehen.
  5. Ihr PR wird mit dem Mainbranch des Liverepositorys gemergt, und Ihre Änderungen werden auf Microsoft Learn veröffentlicht.

Als Nächstes sehen wir uns die einzelnen Schritte genauer an, um zu veranschaulichen, wie diese ablaufen.