Delen via

Git- en GitHub Essentials voor Microsoft Learn-documentatie

  • Artikel

Overzicht

Als inzender van Microsoft Learn-documentatie werkt u met meerdere hulpprogramma's 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 die worden gebruikt voor het opslaan van Microsoft Learn-inhoud . GitHub host voor projecten de hoofdopslagplaats waaruit inzenders kopieën voor hun eigen werk kunnen maken.

In dit artikel worden belangrijke termen gedefinieerd die deel uitmaken van de Microsoft Learn-werkstroom. Het biedt ook een overzicht van Git- en GitHub-opslagplaatsen en legt uit hoe inhoud is georganiseerd voor technische documentatie van Microsoft.

Vertakking

Vertakkingen zorgen voor de scheiding van werkstromen (meestal versies genoemd). Bijdragen worden altijd gemaakt voor en toegewezen aan een specifieke vertakking.

Door gerelateerde wijzigingen in een specifieke vertakking te isoleren, kunt u deze wijzigingen onafhankelijk beheren en introduceren. Afhankelijk van uw werkzaamheden, kunt u daardoor meerdere werkvertakkingen in uw opslagplaats hebben. Het is niet ongebruikelijk dat mensen tegelijkertijd in meerdere vertakkingen werken, die elk bij een ander project horen.

Alle opslagplaatsen bevatten een standaardvertakking (meestal 'main' genoemd) en een of meer werkvertakkingen (die we werkvertakkingen noemen) die nog niet zijn geïntegreerd in de standaardvertakking. De standaardbranch fungeert als de huidige versie en 'één bron van waarheid' voor het project. Alle andere vertakkingen in de opslagplaats worden hiervan afgeleid.

Telkens wanneer u een nieuwe set logisch gerelateerde wijzigingen introduceert, is het een aanbevolen procedure om een werkvertakking te maken om uw wijzigingen te beheren. Het is niet raadzaam om rechtstreeks wijzigingen aan te brengen in de standaardbranch.

Fork

Deze term wordt normaal gesproken gebruikt als zelfstandig naamwoord bij het verwijzen naar een kopie van een hoofdopslagplaats in GitHub. Een fork is in feite gewoon een opslagplaats. Het is echter een bijzondere opslagplaats in de zin dat GitHub een verbinding in stand houdt met de bovenliggende of hoofdopslagplaats. Deze term wordt soms gebruikt als een werkwoord, zoals in 'U moet eerst de opslagplaats splitsen'.

Git

Als u bekend bent met gecentraliseerde versiebeheersystemen (zoals Team Foundation Server, SharePoint of Visual SourceSafe), ziet u dat Git een unieke bijdragewerkstroom en terminologie heeft ter ondersteuning van het gedistribueerde model. Er is bijvoorbeeld geen bestandsvergrendeling die normaal gesproken is gekoppeld aan check-out-/check-inbewerkingen. In plaats daarvan maakt Git zich zorgen over wijzigingen op een nog nauwkeuriger niveau, waarbij bestanden byte byte worden vergeleken.

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

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

Notitie

Hoewel de documentatierichtlijnen zijn gebaseerd op het gebruik van 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.
Daarnaast zijn veel van de volgende richtlijnen ontwikkeld als best practices van jarenlange ervaring bij het hosten van Azure-service-inhoud in GitHub. Deze zijn mogelijk vereist in sommige Microsoft Learn-opslagplaatsen.

Alle werkstromen beginnen en eindigen op GitHub-niveau, waar de hoofdopslagplaats voor elk documentatieproject wordt 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

De standaardbranch van een project fungeert als de huidige versie van inhoud voor het project. De inhoud in de standaardvertakking, en vertakkingen die hierop zijn gemaakt, is losjes afgestemd op de organisatie van de artikelen op de bijbehorende Microsoft Learn-pagina's. Submappen worden gebruikt voor het scheiden van artikelen (zoals services), media-inhoud (zoals afbeeldingsbestanden) en 'include'-bestanden (die hergebruik van inhoud mogelijk maken).

Submap Artikelen

De hoofdmap articles bevindt zich meestal direct onder de hoofdmap van de opslagplaats. De articles map bevat een set submappen artikelen in de submappen zijn opgemaakt als Markdown-bestanden die een .md-extensie gebruiken. Sommige opslagplaatsen die ondersteuning bieden voor meerdere services, maken gebruik van een algemene /articles-submap, zoals de Azure-Docs-opslagplaats. Andere gebruiken misschien een servicespecifieke naam, zoals de IntuneDocs-opslagplaats, die gebruikmaakt van /IntuneDocs.

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-naslaginformatie: 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 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.
  • 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 voor technische documentatie van Microsoft, die u kunt gebruiken voor speciale besturingselementen, zoals knoppen en selectors.

Oorprong

Deze term is de naam die is toegewezen aan de verbinding tussen uw lokale opslagplaats en de opslagplaats waaruit deze is gekloond. In de Microsoft Learn-werkstroom vertegenwoordigt de oorsprong de verbinding met uw fork. Deze term wordt soms gebruikt als moniker voor de oorspronkelijke opslagplaats zelf, zoals in 'Vergeet niet uw wijzigingen naar de oorsprong te pushen'.

Pull-aanvragen

Een pull-aanvraag (PR) is een aanvraag voor een inhoudseigenaar om uw wijzigingen in de officiële bron op te halen. Een pull-aanvraag maakt het samenwerkingsmodel van GitHub mogelijk door te vragen om de wijzigingen (ook wel doorvoeringen genoemd) uit uw werkbranch om te worden opgehaald en samengevoegd in een andere vertakking. In de meeste gevallen is die andere vertakking de standaardbranch in de hoofdopslagplaats.

Een pull-aanvraag fungeert ook als mechanisme om de inzender feedback te geven van de validatieprocessen van Microsoft Learn en de revisor voor pull-aanvragen om problemen of vragen op te lossen voordat de wijzigingen worden samengevoegd in de standaardbranch.

Extern

Een externe verbinding is een benoemde verbinding met een externe opslagplaats, zoals de externe 'origin' of 'upstream'. Git verwijst ernaar als een externe omdat deze wordt gebruikt om te verwijzen naar een opslagplaats die wordt gehost op een andere computer. In de Microsoft Learn-werkstroom is een externe opslagplaats altijd een GitHub-opslagplaats.

Upstream

Net als de externe oorsprong is upstream een benoemde verbinding met een andere opslagplaats. In de Microsoft Learn-werkstroom vertegenwoordigt de upstream de verbinding tussen uw lokale opslagplaats en de hoofdopslagplaats waaruit uw fork is gemaakt. Deze term wordt soms gebruikt als moniker voor de upstream-opslagplaats zelf, zoals in 'Vergeet niet om de meest recente wijzigingen op te halen uit de upstream'.

Meer informatie

Als u niet bekend bent met Git of GitHub, kunnen deze resources u helpen om te leren, productief te zijn of vragen te beantwoorden.

Git-bronnen voor broncodebeheer

GitHub-informatiebronnen

Veelgestelde vragen

Wat is Git?

Git helpt wijzigingen bij te houden wanneer veel mensen samen aan computercode werken. Het is net een tijdmachine voor code, dus u kunt zien wat er is gewijzigd en zo nodig teruggaan.

Waarom Git gebruiken?

Het is geweldig voor teamwerk. Git maakt het voor veel mensen gemakkelijk om aan hetzelfde project te werken zonder elkaars werk te verpesten. Het helpt ook om fouten eenvoudig op te lossen.

Hoe werkt Git?

Git slaat alle versies van de code van een project op. Wanneer u wijzigingen aanbrengt, maakt Git een afbeelding (zoals een momentopname) van wat er anders is. U kunt verschillende versies tegelijkertijd zonder problemen maken.

Wat zijn vertakkingen in Git?

Vertakkingen zijn hetzelfde als verschillende paden in een project. Ze laten mensen aan nieuwe dingen werken zonder het hoofdproject te wijzigen. Later kunnen ze deze wijzigingen terugbrengen in het hoofdproject.

Wat is een doorvoering in Git?

Een doorvoering lijkt op een opslagpunt. Het is een manier om wijzigingen vast te leggen die u hebt aangebracht. Elke doorvoering heeft een unieke id en een opmerking over wat er is gewijzigd.

Wat is GitHub?

GitHub is een website waar u uw Git-projecten kunt opslaan. Het is net een grote hub voor het delen en samenwerken aan code met anderen. Het helpt ook bij te houden wie wat heeft gewijzigd.

Hoe verschilt GitHub van Git?

Git is het hulpprogramma voor het bijhouden van wijzigingen, terwijl GitHub de plek is om uw projecten op te slaan en samen te werken. GitHub gebruikt Git om de magie uit te voeren.

Is GitHub gratis?

Ja, voor projecten die iedereen kan zien. Maar voor privéprojecten (alleen u en uw team) moet u mogelijk betalen. Ze bieden verschillende abonnementen met extra functies.

Wat zijn pull-aanvragen in GitHub?

Pull-aanvragen zijn vergelijkbaar met het vragen om uw wijzigingen in het hoofdproject te plaatsen. Mensen de wijzigingen kunnen bekijken en bespreken voordat ze worden toegevoegd.

Hoe veilig is GitHub?

GitHub zorgt voor goede beveiliging. Ze gebruiken speciale codes en regels om ervoor te zorgen dat alleen de juiste personen uw code kunnen openen en wijzigen. U kunt ook extra beveiligingslagen toevoegen, zoals tweeledige verificatie, voor meer veiligheid.