Dela via

Dokumentation om Git och GitHub för Microsoft Learn

  • Artikel

Översikt

Som deltagare i Microsoft Learn-dokumentationen interagerar du med flera 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, till exempel de som används för att lagra Microsoft Learn-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.

Den här artikeln definierar viktiga termer som ingår i Microsoft Learn-arbetsflödet. Den ger också en översikt över Git- och GitHub-lagringsplatser och förklarar hur innehåll organiseras för Microsofts tekniska dokumentation.

Filial

Grenar separerar arbetsströmmar (kallas oftast versioner). Bidrag görs alltid i en viss gren.

Genom att isolera relaterade ändringar i en specifik gren kan du styra och introducera dessa ändringar oberoende av varandra. I själva fallet, beroende på vilken typ av arbete du utför, kan du lätt få flera olika arbetsgrenar i din lagringsplats. Det är inte ovanligt att arbeta med flera grenar på samma gång, där var och en representerar ett projekt.

Alla lagringsplatser innehåller en standardgren (vanligtvis "main") och en eller flera pågående grenar (som vi kallar arbetsgrenar) som ännu inte har integrerats i 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.

Varje gång du introducerar en ny uppsättning logiskt relaterade ändringar är det bästa praxis att skapa en arbetsgren för att hantera dina ändringar. Vi rekommenderar inte att du gör ändringar i standardgrenen direkt.

Fork

Den här termen används normalt som ett substantiv när du refererar till en kopia av en huvudlagringsplats för GitHub. I praktiken är en förgrening bara en annan lagringsplats. Men den är speciell på det sätt att GitHub behåller en koppling tillbaka till huvudlagringsplatsen. Den här termen används ibland som ett verb, som i "Du måste förgrena lagringsplatsen först".

Git

Om du är bekant med centraliserade versionskontrollsystem (till exempel Team Foundation Server, SharePoint eller Visual Source Valv) kommer du att märka att Git har ett unikt bidragsarbetsflöde och terminologi som stöd för dess distribuerade modell. Det finns till exempel ingen fillåsning som normalt är associerad med utchecknings-/incheckningsåtgärder. I stället är Git oroat över ändringar på en ännu finare nivå och jämför filer byte med 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 enhet lagringsutrymme som innehåller de filer och mappar som bildar ett projekts innehåll. Mer information om grenar finns i avsnittet Gren i den här artikeln.

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

Kommentar

Även om dokumentationsvägledningen baseras på användning av GitHub använder vissa team Visual Studio Team Services som värd för Git-lagringsplatser. Visual Studio Team Explorer-klienten har ett GUI för att interagera med Team Services-lagringsplatser, som är ett alternativ till att använda Git-kommandon via en kommandorad.
Dessutom utvecklades många av följande riktlinjer som metodtips från många års erfarenhet av att hantera Azure-tjänstinnehåll i GitHub. De kan krävas i vissa Microsoft Learn-lagringsplatser.

Alla arbetsflöden börjar och slutar på GitHub-nivå, där huvudlagringsplatsen för alla dokumentationsprojekt lagras. 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

Ett projekts standardgren fungerar som den aktuella versionen av innehållet för projektet. Innehållet i standardgrenen – och grenar som skapats från den – är löst anpassat till organisationen av artiklarna på motsvarande Microsoft Learn-sidor. Underkataloger används för att separera t.ex. artiklar (till exempel tjänster), medieinnehåll (till exempel bildfiler) och "inkludera" filer (som möjliggör återanvändning av innehåll).

Underkatalog för artiklar

Du hittar normalt en articles-huvudkatalogen vid lagringsplatsens rot. Katalogen articles innehåller en uppsättning underkataloger Artiklar i underkatalogerna formateras 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 Azure-Docs. Andra kan använda ett tjänstespecifikt namn, t.ex. lagringsplatsen IntuneDocs som använder /IntuneDocs.

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.

Mer vägledning finns i Markdown-referens : Innehåller .

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 hur du använder Microsofts tillägg för teknisk dokumentation, som du kan använda för särskilda kontroller, till exempel knappar och väljare.

Ursprung

Den här termen är det namn som tilldelats anslutningen mellan den lokala lagringsplatsen och den lagringsplats som den klonades från. I Microsoft Learn-arbetsflödet representerar ursprunget anslutningen till din förgrening. Den här termen används ibland som moniker för själva ursprungslagringsplatsen, som i "Kom ihåg att push-överföra dina ändringar till ursprunget".

Hämta begäranden

En pull-begäran (PR) är en begäran om att en innehållsägare ska hämta dina ändringar till den officiella källan. En PR gör det möjligt för GitHubs samarbetsmodell genom att be om att ändringarna (även kallade incheckningar) från din arbetsgren ska hämtas och sammanfogas till en annan gren. I de flesta fall är den andra grenen standardgrenen på huvudlagringsplatsen.

En pr fungerar också som en mekanism för att ge deltagaren feedback från Microsoft Learns valideringsprocesser och PR-granskaren för att lösa problem eller frågor innan ändringarna sammanfogas till standardgrenen.

Fjärr-

En fjärranslutning är en namngiven anslutning till en fjärrlagringsplats, till exempel fjärranslutningen "origin" eller "upstream". Git refererar till detta som en fjärranslutning eftersom den används för att referera till en lagringsplats som finns på en annan dator. I Microsoft Learn-arbetsflödet är en fjärrlagringsplats alltid en GitHub-lagringsplats.

Uppströms

Precis som ursprungsfjärrplatsen är uppströms en namngiven anslutning till en annan lagringsplats. I Microsoft Learn-arbetsflödet representerar uppströms anslutningen mellan din lokala lagringsplats och huvudlagringsplatsen som din förgrening skapades från. Den här termen används ibland som en moniker för själva den överordnade lagringsplatsen, som i "Kom ihåg att hämta de senaste ändringarna från uppströms".

Läs mer

Om du inte är bekant med Git eller GitHub kan dessa resurser hjälpa dig att lära dig, vara produktiv eller svara på frågor.

Git-källkontrollresurser

GitHub-resurser

Vanliga frågor och svar

Vad är Git?

Git hjälper till att hålla reda på ändringar när många arbetar med datorkod tillsammans. Det är som en tidsdator för kod, så du kan se vad som har ändrats och gå tillbaka om det behövs.

Varför ska jag använda Git?

Det är bra för lagarbete. Git gör det enkelt för många att arbeta med samma projekt utan att förstöra varandras arbete. Det hjälper också till att enkelt åtgärda misstag.

Hur fungerar Git?

Git lagrar alla versioner av ett projekts kod. När du gör ändringar tar Git en bild (till exempel en ögonblicksbild) av vad som är annorlunda. Du kan göra olika versioner samtidigt utan problem.

Vad är grenar i Git?

Grenar liknar olika sökvägar i ett projekt. De låter människor arbeta med nya saker utan att ändra huvudprojektet. Senare kan de föra tillbaka dessa ändringar till huvudprojektet.

Vad är en incheckning i Git?

En incheckning är som en sparandepunkt. Det är ett sätt att registrera ändringar som du har gjort. Varje incheckning har ett unikt ID och en anteckning om vad som har ändrats.

Vad är GitHub?

GitHub är en webbplats där du kan lagra dina Git-projekt. Det är som en stor hubb för att dela och arbeta tillsammans med kod med andra. Det hjälper också till att hålla reda på vem som ändrade vad.

Hur skiljer sig GitHub från Git?

Git är verktyget för att spåra ändringar, medan GitHub är platsen där du kan lagra dina projekt och arbeta tillsammans. GitHub använder Git för att göra sin magi.

Är GitHub kostnadsfri?

Ja, för projekt som alla kan se. Men för privata projekt (bara du och ditt team) kan du behöva betala. De erbjuder olika planer med extra funktioner.

Vad är pull-begäranden i GitHub?

Pull-begäranden är som att be om att lägga dina ändringar i huvudprojektet. Personer kan granska och diskutera ändringarna innan de läggs till.

Hur säkert är GitHub?

GitHub tar väl hand om säkerheten. De använder särskilda koder och regler för att se till att endast rätt personer kan komma åt och ändra din kod. Du kan också lägga till extra säkerhetslager som tvåfaktorautentisering för mer säkerhet.