Information om Git och GitHub för Docs

Översikt

Som deltagare som bidrar till Docs-innehåll använder du flera olika verktyg och processer. Du arbetar parallellt med andra deltagare i samma projekt, eventuellt med exakt samma innehåll, och precis samtidigt. Allt detta görs möjligt via programvaran Git och GitHub.

Git är ett versionskontrollsystem med öppen källkod. Det möjliggör den här typen av projektsamarbete via distribuerad versionskontroll av filer som inhyses i lagringsplatser. I stort gör Git det möjligt att interagera strömmar av arbete som görs av flera deltagare över tid, för en given lagringsplats.

GitHub är en webbaserad värdtjänst för Git-lagringsplatser som de som används för att lagra docs.microsoft.com-innehåll. För alla projekt är GitHub värd åt huvudlagringsplatsen, från vilken deltagare kan göra kopior för sitt eget arbete.

Git

Om du är bekant med centraliserade versionskontrollsystem (såsom Team Foundation Server, SharePoint eller Visual SourceSafe), kommer du att märka att Git har ett unikt bidragsarbetsflöde och terminologi som stöd för sin distribuerade modell. Det finns t.ex. ingen fillåsning, vilket normalt associeras med utcheckningar/incheckningar. Det är till och med så att Git tar hänsyn till ändringar på en ännu finare precisionsnivå, och jämför filer på byte per byte.

Git använder en nivåindelad struktur för att lagra och hantera innehåll för ett projekt:

• Lagringsplats: Också känt som en repo, det här är den högsta lagringsenheten. En lagringsplats innehåller en eller flera grenar.
• Gren:En lagringsenhet som innehåller de filer och mappar som utgör ett projekts innehållsuppsättning. Grenar separerar arbetsströmmar (kallas oftast versioner). Bidrag görs alltid i en viss gren. Alla lagringsplatsen innehåller en standardgren (vanligtvis kallad "main") och en eller flera grenar som ska sammanfogas tillbaka till standardgrenen. Standardgrenen fungerar som den aktuella versionen och "enskild sanningskälla" för projektet. Den är den överordnade grenen från vilken alla andra grenar i lagringsplatsen skapas.

Deltagare interagerar med Git för att uppdatera och ändra lagringsplatser på både lokal nivå och på GitHub-nivå:

• Lokalt via verktyg som Git Bash-konsolen som har stöd för Git-kommandon för att hantera lokala lagringsplatser och kommunicera med GitHub-lagringsplatser.
• Via www.github.com, som integrerar Git för att hantera avstämningen av bidrag som flödar tillbaka till huvudlagringsplatsen.

GitHub

Alla arbetsflöden börjar och slutar på GitHub-nivån, där huvudlagringsplatsen för alla Docs-projekt förvaras. De kopior som deltagare skapar för sin egen användning distribueras på flera datorer. Dessa kopior stäms så småningom av mot projektets huvudsakliga GitHub-lagringsplats.

Organisering av katalog

Som tidigare nämnts fungerar ett projekts standardgren som den aktuella versionen av innehållet för projektet. Innehållet i standardgrenen – och grenar som skapats från den – är löst justerat med organisationen av artiklarna på motsvarande Docs-sidor. Underkataloger används för separation av innehåll (såsom tjänster), mediainnehåll (såsom bildfiler) och "inkluderar" filer (som gör det möjligt att återanvända innehåll).

Du hittar normalt en articles-huvudkatalogen vid lagringsplatsens rot. Artikelkatalogen innehåller en uppsättning underkataloger. Artiklar i underkatalogerna är formaterade som Markdown-filer som använder ett MD-tillägg. Vissa lagringsplatser som har stöd för flera tjänster använder en allmän /articles-underkatalog, t.ex. lagringsplatsen /articles. Andra kan använda ett tjänstespecifikt namn, t.ex. lagringsplatsen IntuneDocs som använder .

I den här katalogens rot hittar du allmänna artiklar som relaterar till den allmänna tjänsten eller produkten. Normalt kan du sedan hitta ytterligare en serie underkataloger som matchar funktioner/tjänster eller vanliga situationer. Exempelvis finns Azure-artiklarna om virtuella datorer i /virtual-machines-underkatalogen, de beskrivande Intune-artiklarna i /understand-explore-underkatalogen, o.s.v.

Underkatalog för media

Varje artikelkatalog innehåller en /media-underkatalog för motsvarande mediafiler. Mediafiler innehåller bilder som används i artiklar som har bildreferenser.

Inkluderar underkatalog

När vi har innehåll som kan återanvändas som delas mellan två eller flera artiklar placeras det i en /includes-underkatalog fristående från articles-huvudkatalogen. I en Markdown-fil där den inkluderade filen används placeras motsvarande Markdown-inkluderingstillägg på den plats där hänvisningen till inkluderingsfilen ska vara.

Se Markdown-referens: Innehåller för ytterligare vägledning.

Markdown-filmall

Av praktiska skäl innehåller rotkatalogen för varje lagringsplats normalt Markdown-mall med namnet template.md. Du kan använda den här mallen som en startfil om du behöver skapa en ny artikel till lagringsplatsen. Filen innehåller följande:

• Ett metadatahuvud längst upp i filen, avgränsat med två rader med 3 bindestreck. Den innehåller de olika taggar som används för att spåra information som rör artikeln. Metadata om en artikel krävs för vissa funktioner, till exempel författarattribution, bidragsattribution, synliga sökvägar och artikelbeskrivningar. Det omfattar också sökmotorsoptimeringar och rapporteringsprocesser som Microsoft använder för att utvärdera innehållets prestanda. Metadata är alltså viktigt!
• Ett metadataavsnitt som beskriver de olika metadatataggarna och värdena. Om du är osäker på vilka värden som ska användas för metadataavsnittet kan du låta dem vara tomma, eller kommentera dem med en inledande hashtagg (#) så kommer de att granskas/fyllas i av den som granskar pull-begäran för lagringsplatsen.
• Olika exempel på användning av Markdown vid formatering av delarna i en artikel.
• Allmänna anvisningar om användning av Markdown-tillägg, som du kan använda för olika typer av aviseringar.
• Exempel på att bädda in en video med hjälp av en iframe.
• Allmänna anvisningar om användning av docs.microsoft.com-tillägg som du kan använda för särskilda kontroller, till exempel knappar och väljare.

Hämta begäranden

En pull-begäran är ett enkelt sätt för deltagare att föreslå en uppsättning ändringar som ska appliceras på standardgrenen. Ändringarna (även kända som allokeringar) lagras i deltagarens gren, vilket gör det möjligt för GitHub att modellera deras påverkan då de slås samman med standardgrenen. En pull-begäran fungerar också som en mekanism för att förse deltagaren med feedback från en bygg-/valideringsprocess, pull-begäransgranskaren, för att lösa eventuella frågor innan ändringarna slås samman med standardgrenen.

Det finns två sätt att bidra med pull-begäran, beroende på storleken på de ändringar du vill föreslå. Vi går igenom detta mer i detalj i avsnittet om GitHub-arbetsflödet senare i den här guiden.