Essentiële informatie over Git en GitHub

Overzicht

Als inzender van Docs-inhoud werkt u met meerdere hulpmiddelen en processen. Hiermee kunt u gelijktijdig met andere inzenders aan hetzelfde project te werken, mogelijk aan precies dezelfde inhoud of zelfs op hetzelfde moment. Dit wordt allemaal mogelijk gemaakt door Git- en GitHub-software.

Git is een open source-versiebeheersysteem. Hiermee is dit soort samenwerking aan een project mogelijk door middel van gedistribueerd versiebeheer van bestanden in opslagplaatsen. Git maakt het in feite mogelijk dat stromen werkzaamheden van meerdere inzenders in een tijdsbestek voor een bepaalde opslagplaats worden geïntegreerd.

GitHub is een hostingwebservice voor Git-opslagplaatsen, zoals de opslagplaatsen die worden gebruikt om inhoud van docs.microsoft.com op te slaan. GitHub host voor projecten de hoofdopslagplaats waaruit inzenders kopieën voor hun eigen werk kunnen maken. (Meer informatie hierover vindt u in Instellen van een lokale opslagplaats.) Het OPS-platform haalt gegevens op uit diverse Docs-hoofdopslagplaatsen wanneer er inhoud naar docs.microsoft.com wordt gepubliceerd.

Git

Als u vertrouwd bent met gecentraliseerde versiebeheersystemen (zoals Team Foundation Server, SharePoint of Visual SourceSafe), zult u merken dat Git een unieke bijdragewerkstroom en terminologie voor de ondersteuning van het gedistribueerde model heeft. Zo worden bijvoorbeeld bestanden niet vergrendeld wat normaal wel het geval is bij uit- en incheckbewerkingen. Bij Git wordt op een veel gedetailleerder niveau naar wijzigingen gekeken, waarbij bestanden byte voor byte met elkaar worden vergeleken.

Ook wordt bij Git een gelaagde structuur gebruikt om inhoud voor een project op te slaan en te beheren:

  • Opslagplaats: dit is de hoogste opslageenheid en wordt ook wel een repository of repo genoemd. Een opslagplaats bevat een of meer vertakkingen.
  • Vertakking: een opslageenheid met de bestanden en mappen die gezamenlijk de inhoudsset van een project vormen. Vertakkingen zorgen voor de scheiding van werkstromen (meestal versies genoemd). Bijdragen worden altijd gemaakt voor en toegewezen aan een specifieke vertakking. Alle opslagplaatsen bevatten een standaardvertakking (meestal de hoofdvertakking genoemd) en een of meer vertakkingen die bedoeld zijn om later te worden samengevoegd met de hoofdvertakking. De hoofdvertakking fungeert als de huidige versie en 'de enige vertrouwde bron' voor het project. Alle andere vertakkingen in de opslagplaats worden hiervan afgeleid.

Inzenders werken met Git om opslagplaatsen op zowel lokaal als op GitHub-niveau te updaten en bewerken:

  • Lokaal via hulpmiddelen zoals de Git Bash-console waarmee Git-opdrachten voor het beheer van lokale opslagplaatsen en de communicatie met GitHub-opslagplaatsen kunnen worden gegeven.
  • Via www.github.com, waarmee Git wordt geïntegreerd om bijdragen in de hoofdopslagplaats samen te voegen.

GitHub

Notitie

Hoewel de Docs-richtlijnen zijn gebaseerd op het gebruik GitHub, gebruiken sommige teams Visual Studio Team Services om Git-opslagplaatsen te hosten. De Visual Studio Team Explorer-client biedt een gebruikersinterface voor interactie met Team Services-opslagplaatsen. Deze interface kunt u gebruiken om Git-opdrachten via een opdrachtregel in te voeren.
Ook zijn veel van de volgende richtlijnen ontwikkeld als aanbevolen procedures op basis van jaren ervaring in het hosten van Azure-service-inhoud in GitHub. Deze zijn mogelijk vereist in bepaalde Docs-opslagplaatsen.

Alle werkstromen beginnen en eindigen op GitHub-niveau waar de hoofdopslagplaats voor een bepaald Docs-project is opgeslagen. De exemplaren die inzenders voor hun eigen gebruik maken, worden op meerdere computers gedistribueerd. Deze exemplaren worden uiteindelijk weer overgebracht naar de belangrijkste GitHub-opslagplaats van het project.

Conventies en aanbevolen procedures voor opslagplaatsen

Bij veel projecten waarbij naar docs.microsoft.com wordt gepubliceerd, wordt gebruikgemaakt van een aparte privé-GitHub-opslagplaats voor interne inzenders en een gerepliceerde openbare GitHub-opslagplaats voor externe inzenders. Voor een privé-opslagplaats wordt meestal dezelfde naam gebruikt als voor de bijbehorende openbare opslagplaats, maar dan met het achtervoegsel -pr.

Wanneer een team geen ondersteuning biedt voor privé-opslagplaatsen, worden alle bijdragen ingezonden naar de enige openbare opslagplaats. Maar interne inzenders moeten hun bijdragen altijd naar de privé-opslagplaats sturen als die beschikbaar is. De privé-opslagplaats wordt uiteindelijk via gewone synchronisatie samengevoegd met de openbare versie.

Organisatie van mappen

Zoals eerder genoemd, dient de standaardvertakking ('hoofdvertakking') als de huidige versie van de inhoud voor het project. De inhoud van de hoofdvertakking (en vertakkingen die op basis van de hoofdvertakking zijn gemaakt) wordt globaal afgestemd op de organisatie van de artikelen op de bijbehorende Docs-pagina's. Submappen worden gebruikt om soortgelijke inhoud (zoals services), media-inhoud (zoals afbeeldingsbestanden) en include-bestanden voor hergebruik van inhoud te scheiden.

De hoofdmap articles bevindt zich meestal direct onder de hoofdmap van de opslagplaats. De map articles bevat een reeks submappen. Artikelen in de submappen zijn opgemaakt als Markdown-bestanden met de extensie .md. Sommige opslagplaatsen die ondersteuning bieden voor meerdere services, maken gebruik van een generieke submap /articles (bijvoorbeeld de opslagplaats https://github.com/microsoft/Azure-Docs). Andere gebruiken misschien een servicespecifieke naam, zoals de opslagplaats https://github.com/microsoft/IntuneDocs, die /IntuneDocs gebruikt.

Direct in deze hoofdmap vindt u algemene artikelen die betrekking hebben op de algehele service of het algehele product. De hoofdmap bevat meestal ook enkele submappen die horen bij de functies/services of bij algemene scenario's. Zo staan de Azure-artikelen over virtuele machines in de submap /virtual-machines, de Intune-artikelen uit de sectie Begrijpen en verkennen in de submap /understand-explore, enzovoort.

Submap voor media

Elke artikelmap bevat een submap /media voor de overeenkomstige mediabestanden. Mediabestanden bevatten afbeeldingen die worden gebruikt voor artikelen die verwijzingen naar afbeeldingen bevatten.

Zie Adding static art to your content (Statische illustraties toevoegen aan uw inhoud) voor aanvullende richtlijnen.

Map met include-bestanden

Wanneer er herbruikbare inhoud is die wordt gedeeld door twee of meer artikelen, wordt deze inhoud opgeslagen in een submap /includes buiten de hoofdmap articles. In een Markdown-bestand waarvoor het include-bestand wordt gebruikt, wordt een overeenkomende Markdown-extensie include geplaatst op de locatie waar de verwijzing naar het include-bestand moet worden gebruikt.

Zie Markdown gebruiken: Includes voor aanvullende richtlijnen.

Sjabloon voor Markdown-bestanden

Voor het gemak bevat de hoofdmap van elke opslagplaats meestal een sjabloon voor Markdown-bestanden met de naam template.md. U kunt deze sjabloon gebruiken als basis voor een nieuw artikel dat u wilt verzenden naar de opslagplaats. Het bestand bevat:

  • Een koptekst met metagegevens boven aan het bestand, afgebakend door twee regels met drie afbreekstreepjes, en verschillende labels die worden gebruikt voor het bijhouden van informatie met betrekking tot het artikel. De metagegevens van het artikel maken bepaalde functies mogelijk, zoals toekenning aan auteur, toekenning aan inzender, breadcrumbs, artikelbeschrijvingen en zoekmachineoptimalisatie. Ook worden de metagegevens gebruikt voor rapportageprocessen waarmee Microsoft de prestaties van de inhoud kan evalueren. De metagegevens zijn dus belangrijk.
  • Een sectie met metagegevens met de beschrijving van de verschillende labels en waarden voor de metagegevens. Als u niet zeker weet welke waarden u moet gebruiken in de sectie voor metagegevens, kunt u de sectie leeg laten of de waarden markeren als commentaar door er een hashtag (#) voor te plaatsen. De waarden worden dan beoordeeld/voltooid door de revisor van de pull-aanvraag voor de opslagplaats. Dit wordt gedetailleerd behandeld in How to write metadata (Metagegevens schrijven).
  • Verschillende voorbeelden van het gebruik van Markdown voor het indelen van de elementen van een artikel.
  • Algemene instructies voor het gebruik van Markdown-extensies die u kunt gebruiken voor diverse waarschuwingstypen.
  • Voorbeelden van het insluiten van video's met behulp van een iframe.
  • Algemene instructies voor het gebruik van extensies van docs.microsoft.com die u kunt gebruiken voor speciale besturingselementen, zoals knoppen en selectors.

Pull-aanvragen

Een pull-aanvraag biedt een handige manier voor een inzender om een set wijzigingen voor te stellen die op de standaardvertakking moet worden toegepast. De wijzigingen (ook wel doorvoeracties genoemd) worden opgeslagen in de vertakking van de inzender, zodat GitHub eerst de impact van het samenvoegen van deze wijzigingen met de standaardvertakking kan verwerken. Een pull-aanvraag dient ook als mechanisme om de inzender feedback te verschaffen van een build-/validatieproces, de revisor van de pull-aanvraag, om mogelijke problemen op te lossen of vragen te beantwoorden voordat de wijzigingen met de hoofdvertakking worden samengevoegd.

Er zijn twee manieren om bij te dragen via een pull-aanvraag, afhankelijk van de grootte van de wijzigingen die u wilt voorstellen. Dit wordt later in de secties GitHub-werkstroom van deze gids gedetailleerd besproken.