Essentiële informatie over Git en GitHub voor Docs

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 webhostingservice voor Git-opslagplaatsen, zoals de opslagplaatsen die worden gebruikt voor het opslaan docs.microsoft.com inhoud. GitHub host voor projecten de hoofdopslagplaats waaruit inzenders kopieën voor hun eigen werk kunnen maken.

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 die de bestanden en mappen bevat waar de inhoudsset van een project uit bestaat. 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 'main' genoemd) en een of meer vertakkingen die zijn bestemd om weer te worden samengevoegd met de standaardvertakking. De standaard branch fungeert als de huidige versie en 'single source of truth' 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 de afstemming van bijdragen die terugstromen naar de hoofdopslagplaats te beheren.

GitHub

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.

Organisatie van mappen

Zoals eerder vermeld, fungeert de standaardvertakking van een project als de huidige versie van de inhoud voor het project. De inhoud in de standaard branch (en vertakkingen die op basis van de vertakking zijn gemaakt) is losjes 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 algemene /articles-submap, zoals de /articles-opslagplaats. Andere gebruiken misschien een servicespecifieke naam, zoals de IntuneDocs-opslagplaats, die gebruikmaakt van .

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.

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 reference: Includes (Naslag voor Markdown: Bevat) voor aanvullende richtlijnen.

De 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 tags 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 die de verschillende metagegevenstags en -waarden beschrijft. 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.
• 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.