Grundlegende Informationen zu Git und GitHub für die Microsoft Learn-Dokumentation

  • Artikel

Übersicht

Wer an der Microsoft Learn-Dokumentation mitwirkt, interagiert mit mehreren Tools und Prozessen. Sie arbeiten mit anderen Mitwirkenden parallel an demselben Projekt zusammen – teilweise sogar an denselben Inhalten und zur selben Zeit. Möglich wird all dies durch die Software Git und GitHub.

Git ist ein Open-Source-System für die Versionskontrolle. Es ermöglicht derartige Projektzusammenarbeiten durch verteilte Versionskontrolle der in den Repositorys enthaltenen Dateien. Im Wesentlichen können mit Git Streams integriert werden, die im Laufe der Zeit von verschiedenen Mitwirkenden für ein bestimmtes Repository erstellt wurden.

GitHub ist ein webbasierter Hostingdienst für Git-Repositorys, die beispielsweise zum Speichern von Inhalten der Microsoft Learn eingesetzt werden. GitHub hostet für alle Projekte das Hauptrepository, über das Mitwirkende Kopien für Ihre eigene Arbeit erstellen können.

In diesem Artikel werden wichtige Begriffe aus dem Microsoft Learn-Workflow definiert. Außerdem gibt der Artikel eine Übersicht über Git- und GitHub-Repositorys und erläutert, wie Inhalte für die technische Dokumentation von Microsoft organisiert werden.

Verzweigung

Branches werden zur Trennung der Streams (in der Regel als Versionen bezeichnet) verwendet. Beiträge werden immer für einen bestimmten Branch erstellt und diesem zugeordnet.

Mit der Isolation zugehöriger Änderungen in einem bestimmten Branch können Sie diese Änderungen unabhängig steuern und einführen. 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.

Alle Repositorys enthalten eine Standardbranch („Main“) und eine oder mehrere Branches in Bearbeitung (die wir als „Arbeitsbranches“ bezeichnen), die noch nicht in die Standardbranch integriert wurden. 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.

Immer dann, wenn Sie mehrere neue logisch verknüpfte Änderungen vornehmen, sollten Sie einen Arbeitsbranch erstellen, um Ihre Änderungen zu verwalten. Wir raten davon ab, Änderungen direkt an der Standardbranch vorzunehmen.

Fork

Dieser Begriff 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. Dieser Begriff wird manchmal als Verb verwendet, wie in „You must fork the repository first.“ (Sie müssen das Repository zuerst forken).

Git

Wenn Ihnen die Arbeit mit zentralen Versionskontrollsystemen (z. B. Team Foundation Server, SharePoint oder Visual SourceSafe) bekannt ist, werden Sie feststellen, dass Git über einen einzigartigen Beitragsworkflow verfügt und eine spezifische Terminologie zur Unterstützung des verteilten Modells verwendet. So ist beispielsweise keine Dateisperrung verfügbar, die bei Auscheck-/Eincheckvorgängen üblich ist. Bei Git werden stattdessen Änderungen sogar noch ausführlicher behandelt, indem Dateien byteweise miteinander verglichen werden.

Git basiert ebenfalls auf einer mehrstufigen Struktur zur Speicherung und Verwaltung von Inhalten für ein Projekt:

  • Repository: Dies ist die größte Speichereinheit. Ein Repository enthält mindestens einen Branch.
  • Branch: Diese Speichereinheit enthält die Dateien und Ordner, die den gesamten Inhalt eines Projekts bilden. Weitere Informationen zu Branches finden Sie im Abschnitt Branch dieses Artikels.

Mit Git aktualisieren und bearbeiten Mitwirkende Repositorys auf der lokalen und der GitHub-Ebene:

  • Lokal mit Tools wie der Git Bash-Konsole, die Git-Befehle für die Verwaltung lokaler Repositorys und die Kommunikation mit GitHub-Repositorys unterstützt.
  • Über die Website www.github.com, welche Git zum Verwalten des Abgleichs von Beiträgen integriert, die an das Hauptrepository zurückgeführt werden.

GitHub

Hinweis

Die Anweisungen in der Dokumentation beziehen sich zwar auf die Verwendung von GitHub, jedoch hosten einige Teams Git-Repositorys mithilfe von Visual Studio Team Services. Der Visual Studio Team Explorer-Client enthält eine GUI für die Interaktion mit Team Services-Repositorys, die eine Alternative zur Verwendung von Git-Befehlen über eine Befehlszeile darstellen.
Zudem wurden viele der folgenden Richtlinien als bewährte Methoden basierend auf jahrelangen Erfahrungen beim Hosting von Azure-Dienstinhalten in GitHub entwickelt. Sie sind in einigen Microsoft Learn-Repositories möglicherweise erforderlich.

Alle Workflows beginnen und enden auf GitHub-Ebene, auf der das Hauptrepository für jedes Dokumentationsprojekts gespeichert ist. Die von den Mitwirkenden erstellten Kopien werden über mehrere Computer hinweg verteilt. Diese Kopien werden letztendlich mit dem GitHub-Hauptrepository in Einklang gebracht.

Organisation von Verzeichnissen

Ein Standardbranch eines Projekts stellt die aktuelle Version der Projektinhalte dar. Der Inhalt im Standardbranch (und in den daraus erstellten Branches) wird mit der Organisation der Artikel auf den entsprechenden Microsoft Learn Seiten abgestimmt. Unterverzeichnisse werden zur Trennung von Artikeln (z. B. Diensten), Medieninhalten (z. B. Bilddateien) und „Include“-Dateien verwendet, die eine Wiederverwendung der Inhalte ermöglichen.

Artikel-Unterverzeichnis

Üblicherweise finden Sie ein articles-Hauptverzeichnis des Repositorystamms. Das articles-Verzeichnis enthält eine Reihe von Unterverzeichnissen: Artikel in den Unterverzeichnissen sind als Markdown-Dateien formatiert, die die Erweiterung .md verwenden. Einige Repositorys, die mehrere Dienste unterstützen, verwenden ein generisches /articles-Unterverzeichnis, z.B. das Repository Azure-Docs. Andere verwenden möglicherweise einen dienstspezifischen Namen, z.B. das Repository IntuneDocs, das /IntuneDocs verwendet.

Im Stamm dieses Verzeichnisses finden Sie allgemeine Artikel, die mit dem allgemeinen Dienst oder Produkt im Zusammenhang stehen. Zudem können Sie üblicherweise weitere Unterverzeichnisse finden, die zu Features bzw. Diensten oder allgemeinen Szenarios passen. Azure-Artikel zu virtuellen Computern befinden sich beispielsweise im Unterverzeichnis /virtual-machines, während die Intune-Artikel im Bereich „Understand and Explore“ („Verstehen und Erkunden“) im Unterverzeichnis /understand-explore enthalten sind.

Unterverzeichnis für Mediendateien

Jedes Artikelverzeichnis enthält ein Unterverzeichnis /media für entsprechende Mediendateien. Mediendateien enthalten Bilder, die von Artikeln mit Bildverweisen verwendet werden.

Unterverzeichnis für Includes

Wenn es wiederverwendbaren Inhalt gibt, der von mindestens einem Artikeln genutzt wird, wird dieser im Unterverzeichnis /includes des articles-Hauptartikelverzeichnisses abgelegt. In einer Markdowndatei, die die Includedatei verwenden soll, wird die entsprechende Markdownerweiterung „include“ an die Stelle platziert, an der auf die Includedatei verwiesen werden soll.

Weitere Anleitungen finden Sie unter Einbezogene Markdowndateien.

Markdown-Vorlagendatei

Der Einfachheit halber enthält das Stammverzeichnis jedes Repositorys üblicherweise eine Markdownvorlagendatei namens template.md. Sie können diese Vorlagendatei als Ausgangsdatei nutzen, wenn Sie einen neuen Artikel für die Übermittlung an das Repository erstellen müssen. Die Datei enthält Folgendes:

  • Einen Metadatenheader am Anfang der Datei, der durch zwei Zeilen mit drei Bindestrichen getrennt wird. Er enthält die verschiedenen Tags, die zur Nachverfolgung von Informationen verwendet werden, die im Zusammenhang mit dem Artikel stehen. Metadaten zu Artikeln sind Voraussetzungen für bestimmte Funktionen wie die Zuordnung von Autoren und Mitwirkenden, die Brotkrümelnavigation und Beschreibungen von Artikeln. Zudem enthalten Sie SEO-Optimierungen und Vorgänge zur Berichterstattung, die Microsoft verwendet, um die Leistung eines Inhalts zu bewerten. Daher sind die Metadaten wichtig.
  • Den Abschnitt „Metadaten“, in dem die verschiedenen Metadatentags und Werte beschrieben werden. Wenn Sie nicht sicher sind, welche Werte in den Metadatenabschnitt gehören, können Sie sie leer lassen oder mit einem führenden Hashtag (#) kommentieren. Der Prüfer des Pull Requests für das Repository überprüft bzw. vervollständigt diese anschließend.
  • Verschiedene Beispiele für die Verwendung des Markdownformats zum Formatieren der Elemente eines Artikels.
  • Allgemeine Anweisungen für die Verwendung von Markdownerweiterungen, die für verschiedene Arten von Benachrichtigungen verwendet werden können
  • Beispiele für das Einbetten von Videos mithilfe eines IFrames
  • Allgemeine Anweisungen für die Verwendung von Erweiterungen für die technische Microsoft-Dokumentation, die Sie für spezielle Steuerelemente wie Schaltflächen und Selektoren verwenden können.

Ursprung

Dieser Begriff ist der Name der Verbindung zwischen Ihrem lokalen Repository und dem Repository, von dem es geklont wurde. Im Microsoft Learn-Workflow stellt der Ursprung die Verbindung zu Ihrem Fork dar. Dieser Begriff wird manchmal als Moniker für das Ursprungsrepository selbst verwendet, wie in „Remember to push your changes to the origin“ (Denken Sie daran, Ihre Änderungen auf den Origin zu pushen).

Pullanforderungen

Ein Pull Request (PR) ist eine Anforderung für einen Inhaltsbesitzer, Ihre Änderungen in die offizielle Quelle zu übertragen. Ein PR (Pull Request) aktiviert das Modell der Zusammenarbeit von GitHub, indem er anfordert, dass die Änderungen (auch bekannt als Commits) von Ihrem Arbeitsbranch in einen anderen Branch gepullt und darin zusammengeführt werden. In den meisten Fällen ist dieser andere Branch der Standardbranch im Hauptrepository.

Ein PR dient auch als Methode dazu, dem/der Mitwirkenden Feedback über den Validierungsprozess von Microsoft Learn und vom PR-Prüfer bereitzustellen. Damit sollen vor der Zusammenführung der Änderungen im Standardbranch mögliche Probleme behoben bzw. Fragen geklärt werden.

Remote

Ein Remote ist eine benannte Verbindung mit einem Remoterepository, z. B. dem „Origin“- oder „Upstream“-Remote. Git bezeichnet diese als ein „Remote“, weil sie zum Verweis auf ein Repository verwendet wird, das auf einem anderen Computer gehostet wird. Im Microsoft Learn-Workflow ist ein Remote immer ein GitHub-Repository.

Upstream

Wie Originremote ist Upstream eine benannte Verbindung zu einem anderen Repository. Im Microsoft Learn-Workflow stellt Upstream die Verbindung zwischen Ihrem lokalen Repository und dem Hauptrepository dar, aus dem Ihr Fork erstellt wurde. Dieser Begriff wird manchmal als Moniker für das Upstreamrepository selbst verwendet, wie in „Remember to pull the latest changes from the upstream“ (Denken Sie daran, Ihre Änderungen vom Upstream zu pullen).

Weitere Informationen

Wenn Sie mit Git oder GitHub noch nicht vertraut sind, können Ihnen diese Ressourcen helfen, Git und GitHub kennen zu lernen und produktiv einzusetzen und Fragen zu beantworten (diese Ressourcen liegen in englischer Sprache vor).

Ressourcen für die Git-Quellcodeverwaltung

GitHub-Ressourcen

Häufig gestellte Fragen

Was ist Git?

Git hilft, Änderungen nachzuverfolgen, wenn viele Personen gemeinsam an Computercode arbeiten. Es ist wie eine Zeitmaschine für Code, damit Sie sehen können, was sich geändert hat, und bei Bedarf zurückgehen können.

Gründe für die Verwendung von Git

Es eignet sich hervorragend für Teamarbeit. Mit Git können viele Leute an einem Projekt arbeiten, ohne die Arbeit der anderen zu beschädigen. Es hilft auch, Fehler einfach zu beheben.

Wie funktioniert Git?

Git speichert alle Versionen des Codes eines Projekts. Wenn Sie Änderungen vornehmen, nimmt Git ein Bild (z. B. eine Momentaufnahme) davon, was geändert wurde. Sie können verschiedene Versionen gleichzeitig ohne Problem erstellen.

Was sind Verzweigungen in Git?

Verzweigungen sind wie unterschiedliche Pfade in einem Projekt. Sie ermöglichen es den Mitarbeitenden, an neuen Dingen zu arbeiten, ohne das Hauptprojekt zu verändern. Später können sie diese Änderungen in das Hauptprojekt zurückführen.

Was ist ein Commit in Git?

Ein Commit ist wie ein Speicherpunkt. Es ist eine Möglichkeit, Änderungen aufzuzeichnen, die Sie vorgenommen haben. Jeder Commit verfügt über eine eindeutige ID und eine Notiz darüber, was geändert wurde.

Was ist GitHub?

GitHub ist eine Website, auf der Sie Ihre Git-Projekte speichern können. Es ist wie ein großer Hub zum Teilen und Zusammenarbeiten an Code mit anderen. Außerdem hilft es dabei, nachzuverfolgen, wer was geändert hat.

Wie unterscheidet sich GitHub von Git?

Git ist das Tool zum Nachverfolgen von Änderungen, während GitHub der Ort ist, an dem Ihre Projekte gespeichert und zusammenarbeiten können. GitHub verwendet Git, um seine Magie zu entfalten.

Ist GitHub kostenlos?

Ja, für Projekte, die jeder sehen kann. Aber für private Projekte (nur Sie und Ihr Team) müssen Sie möglicherweise bezahlen. Sie bieten verschiedene Pläne mit zusätzlichen Features.

Was sind Pull Requests in GitHub?

Pull Requests sind wie die Aufforderung, Ihre Änderungen in das Hauptprojekt einzufügen. Andere können die Änderungen überprüfen und besprechen, bevor sie hinzugefügt werden.

Wie sicher ist GitHub?

GitHub kümmert sich um die Sicherheit. Sie verwenden spezielle Codes und Regeln, um sicherzustellen, dass nur die richtigen Personen auf Ihren Code zugreifen und ihn ändern können. Sie können auch zusätzliche Sicherheitsebenen wie die zweistufige Authentifizierung hinzufügen, um mehr Sicherheit zu erreichen.