Grundlæggende om Git og GitHub i forbindelse med Docs

Oversigt

Som bidragyder til Docs-indhold arbejder du med forskellige værktøjer og processer. Du arbejder parallelt med andre bidragydere på det samme projekt, og muligvis også på nøjagtigt det samme indhold og endda på samme tid. Git- og GitHub-softwaren gør dette muligt.

Git er et open source-system til versionsstyring. Det muliggør denne type projektsamarbejde gennem distribueret versionsstyring af filer, der lever i lagre. Git integrerer ganske enkelt strømme af arbejde fra forskellige bidragydere over tid for et givet lager.

GitHub er en webbaseret hostingtjeneste for Git-lagre, herunder dem som bruges til lagring af indhold på docs.microsoft.com. Alle projekter har et centralt lager på GitHub, så bidragydere kan oprette kopier til deres eget arbejde.

Git

Hvis du er fortrolig med systemer til centraliseret versionsstyring (f.eks. Team Foundation Server, SharePoint, eller Visual SourceSafe), vil du straks bemærke, at Git har en unik arbejdsproces for bidrag og en unik terminologi, som understøtter den distribuerede model. Der er f.eks. ikke nogen fillåsning, sådan som det kendes fra almindelige tjek ud-/tjek ind-handlinger. Git registrerer rent faktisk ændringer på et endnu finere niveau og sammenligner filer byte for byte.

Git har også en niveauinddelt struktur til lagring og administration af indhold for et projekt:

• Lager: Også kaldet et repository, er den største lagringsenhed. Et lager indeholder en eller flere forgreninger.
• Forgrening: en lagerenhed, der indeholder de filer og mapper, der udgør et projekts indholds gruppe. Forgreninger adskiller arbejdsstrømme (typisk kaldet versioner). Bidrag og bidragsomfang oprettes altid til en bestemt forgrening. Alle lagre indeholder en standardforgrening (normalt kaldet "Main") og én eller flere forgreninger, der skal flettes tilbage til standard forgreningen. Standard forgreningen bruges som den aktuelle version og "enkelt kilde til sand" for projektet. Den er den stamme, som alle lagerets øvrige forgreninger oprettes ud fra.

Bidragydere bruger Git til at opdatere og manipulere lagre både lokalt og på GitHub-niveauer:

• Lokalt ved hjælp af værktøjer, som Git Bash-konsollen, der understøtter Git-kommandoer til administration af lokale lagre og kommunikation med GitHub-lagre.
• Via www.github.com, som integrerer Git til at administrere afstemning af bidrag, som flyder tilbage til det centrale lager.

GitHub

Alle arbejdsprocesser begynder og slutter på GitHub-niveau, hvor det centrale lager for alle Docs-produkter er gemt. De kopier, som bidragydere opretter til eget brug, distribueres på tværs af computere. Kopierne afstemmes til sidst med projektets centrale GitHub-lager.

Organisering af mapper

Som nævnt tidligere, bruges et projekts standardforgrening som den aktuelle version af indholdet for projektet. Indholdet i standard forgreningen og de grene, der er oprettet ud fra det, justeres udløses i forhold til organiseringen af artiklerne på de tilsvarende dokumentsider. Undermapper bruges til at adskille tilsvarende indhold (f.eks. tjenester), medieindhold (f.eks. billedfiler) og "include"-filer (som gør det muligt at genbruge indhold).

En central articles-mappe findes typisk i roden af lageret. Mappen med artikler indeholder forskellige undermapper. Artiklerne i undermapperne er formateret som Markdown-filer, der bruger en .md-udvidelse. Nogle lagre, som understøtter flere tjenester, bruger en generisk /articles-undermappe, f.eks. /articles-lageret. Andre bruger muligvis et tjenestespecifikt navn, f.eks. IntuneDocs-lageret, som bruger .

I roden af denne mappe kan du finde generelle artikler om den overordnede tjeneste eller produktet. Du kan typisk også finde en række andre undermapper svarende til funktionerne/tjenesterne eller almindelige scenarier. Artiklen om den "virtuelle maskine" i Azure findes f.eks. i undermappen /virtual-machines, og artikler om at forstå og udforske Intune findes i undermappen /understand-explore.

Medieundermappe

Alle mapper med artikler har en /media-undermappe til tilhørende mediefiler. Mediefiler indeholder billeder, som bruges i artikler med referencer til billeder.

Medtagelse af undermapper

Alt indhold, der skal genbruges og deles på tværs af to eller flere artikler, placeres i en /includes-undermappe uden for den centrale articles-mappe. Der oprettes en "include"-udvidelse for referencepunktet i Markdown-filen, der bruger "include"-filen.

Se Markdown reference: omfatter yderligere retningslinjer.

Skabelon for Markdown-filer

Af praktiske grunde indeholder rodmappen for hvert lager typisk en Markdown-skabelonfil med navnet template.md. Du kan bruge skabelonfilen som "startfil", hvis du vil oprette en ny artikel, der skal sendes til lageret. Filen indeholder følgende:

• En -metadataoverskrift øverst i filen, afgrænset af to linjer med tre bindestreger. Den indeholder de forskellige koder, der bruges til at spore oplysninger i relation til artiklen. Artikelmetadata muliggør visse funktioner, f.eks. forfattere, bidragydere, brødkrummer og artikelbeskrivelser. De indeholder også SEO-optimering og -rapporteringsprocesser, som Microsoft anvender til at vurdere indholdets effektivitet. Så metadata er vigtige!
• Et metadataafsnit, som beskriver de forskellige metadatakoder og -værdier. Hvis du er usikker på, hvilke værdier der skal bruges i metadataafsnittet, kan du lade dem være tomme eller kommentere dem med et foranstillet hashtag (#), som derefter gennemgås af validatoren for lagerets pullanmodninger.
• Forskellige eksempler på at bruge Markdown til at formatere elementer i en artikel.
• Generelle instruktioner i brugen af Markdown-udvidelser, som du kan bruge til forskellige typer beskeder.
• Eksempler på at integrere video ved hjælp af en iframe.
• Generelle instruktioner om brugen af docs.microsoft.com-udvidelser, som du kan bruge som specielle kontrolelementer, f.eks. knapper og selektorer.

Pull-anmodninger

En pullanmodning gør det nemt for en bidragyder at foreslå ændringer, der skal anvendes på standardforgreningen. Ændringerne (også kaldet bekræftelser) gemmes i en bidragyders forgrening, så effekten af at flette dem med standardforgreningen først kan modelleres i GitHub. En pullanmodning er samtidig en mekanisme, som bruges til at give bidragyderen feedback fra en build-/valideringsproces eller fra validatoren af pullanmodningen, så potentielle problemer eller spørgsmål kan løses, før ændringerne flettes med standardforgreningen.

Afhængigt af omfanget af dine ændringer kan du bidrage med pullanmodninger på to måder. Det vil vi komme nærmere ind på i afsnittet om arbejdsprocessen for GitHub i denne vejledning.