Göra större ändringar i Microsoft Learn-dokumentationen

Artikel
01/28/2024

Viktigt!

Alla lagringsplatser som publicerar till Microsoft Learn har antagit antingen Microsoft Open Source Code of Conduct eller .NET Foundation Code of Conduct. Mer information finns i vanliga frågor och svar om uppförandekoden. Eller kontakta opencode@microsoft.com, eller conduct@dotnetfoundation.org med frågor eller funderingar.

Mindre korrigeringar eller förtydliganden av dokumentation och kodexempel i offentliga lagringsplatser omfattas av video2.skills-academy.com användningsvillkor. Eventuella ändringar genererar en kommentar i pull-begäran och ber dig att skicka ett licensavtal för bidrag online (CLA) om du inte är anställd hos Microsoft. Du behöver slutföra online-formuläret innan din pull-begäran kan sammankopplas.

Den här artikeln visar hur du ändrar en Microsoft Learn-artikel med hjälp av lokala verktyg och är lämplig för en deltagare som behöver göra en större ändring eller som ofta kommer att delta i en lagringsplats. Frekventa deltagare har vanligtvis pågående eller långvariga ändringar som går igenom flera bygg-/validerings-/mellanlagringscykler eller sträcker sig över flera dagar innan de loggar ut på sin pull-begäran (PR).

Exempel på dessa typer av bidrag är:

Göra ett stort bidrag. Dina bidrag (tillägg, ändringar eller borttagningar) kan till exempel omfatta flera artiklar och måste checkas in och testas som en arbetsenhet i en enda PR.
Skapa och publicera en ny artikel, som normalt kräver ett stabilare lokalt redigeringsprogram.
Lägga till nya bilder eller uppdatera bilder, vilket vanligtvis kräver att du samtidigt skapar en ny media underkatalog, skapar bildfiler, uppdaterar bildlänkar i artiklar och förhandsgranskar Markdown-filer i en lokal redigerare för att testa bildåtergivning.
Uppdatera en artikel i flera dagar innan publicering sker. I dessa fall behöver du vanligtvis göra regelbunden integrering av andra ändringar som sker i standardgrenen. Den här integreringen är enklare att utföra via Git Bash och lokal redigering. Du riskerar också att förlora dina redigeringar om du gör detta via GitHub-webbredigeraren och väntar innan du genomför ändringarna.
Göra kontinuerliga uppdateringar av samma artikel efter att en PR har öppnats. Även om du kan använda GitHub-webbredigeraren för det här ändamålet kan du skapa flera utestående pr:er för samma fil, vilket kan vara i konflikt med varandra.

Förutsättningar

Identifiera GitHub-lagringsplatsen som lagrar den dokumentation som du vill redigera.
Skapa ett GitHub-konto om du inte har något.
Installera Git- och Markdown-verktyg.
Konfigurera en lokal Git-lagringsplats.
Granska grunderna för Git och GitHub (valfritt).

Skapa och kolla in din arbetsgren

Börja genom att skapa en ny arbetsgren på den lokala lagringsplatsen för att samla in de föreslagna ändringarna. Mer bakgrund om grenar finns i Grunderna för Git och GitHub.

I den här självstudien används Git Bash och Visual Studio Code, men du kan använda valfri Git-klient och -redigerare som du föredrar.

Öppna lagringsplatsens mapp för din lokala klon i VS Code. På menyn Arkiv väljer du Öppna mapp och navigerar till mappen på datorn.
Välj Visa på den översta menyn och välj sedan Terminal för att öppna den integrerade terminalen.
Kontrollera att du är i lagringsplatsens mapp i den integrerade terminalen.
Innan du skapar en arbetsgren kontrollerar du att din lokala huvudgren är aktuell med allt i produktionslagringsplatsens huvudgren. Den här uppgiften säkerställer att din arbetsgren samlar in alla ändringar som har skett i produktionslagringsplatsen sedan den senaste gången du synkroniserade med den.
1. Växla till huvudgrenen på din lokala lagringsplats:
```
git checkout main 
```
2. Kontrollera att din lokala huvudgren är aktuell:
```
git pull upstream main 
```
Skapa en lokal arbetsgren baserat på huvudgrenen:
```
git checkout -b <branch-name>
```
<branch-name> är en platshållare. När du kör kommandot ersätter du det med ett unikt och meningsfullt namn för din gren och tar bort vinkelparenteserna.
Push-överför den lokala arbetsgrenen till fjärrgrenen i din GitHub-förgrening:
```
git push origin <branch-name> -u
```
Alternativet -u länkar de lokala grenarna och fjärrgrenarna. Med det här alternativet kan du skicka incheckningar till din förgrening genom att ange i git push stället för git push origin <branch-name>.

Hitta markdown-källfilen

Om du vill redigera en artikel letar du reda på källfilen för artikeln i klonen av den lokala lagringsplatsen. I VS Code öppnar du lagringsplatsens Markdown-filer via utforskaren (en dokumentikon i sidofältet längst upp till vänster). Utforskaren visar lagringsplatsens mappstruktur och du kan navigera till den fil som du vill redigera.

Om du inte hittar filen går du till artikeln om Microsoft Learn och väljer pennikonen Redigera . Den relativa mappplatsen på GitHub-lagringsplatsen visas i URL:en. Här är ett exempel på redigera länk-URL:

   https://github.com/Microsoft/azure-docs/blob/main/articles/azure-functions/functions-overview.md

Här är en exempelfilplats för den här URL:en.

   C:\GitHub\*\azure-docs\articles\azure-functions\functions-overview.md

Redigera filen

Öppna filen i VS Code genom att välja den.
Gör önskade ändringar.
Spara ändringarna genom att välja Spara fil>. Använd Spara alla för att spara flera filer samtidigt.

Checka in och push-överföra ändringarna

Om du har gjort omfattande ändringar eller granskat en artikel för färskhet uppdaterar ms.date du i metadatablocket överst i filen. Formatera datumet som mm/dd/åååå.

Du kan använda VS Code-terminalen eller VS Code-användargränssnittet för att checka in och skicka ändringarna.

VS-kodterminal
ANVÄNDARGRÄNSSNITT FÖR VS Code

git status Kör kommandot för att kontrollera att endast de filer som du redigerade visas i listan över ändrade filer.
```
git status
```
git add Kör kommandot följt av filsökvägen och filnamnet för att mellanlagra filen som du ändrade.
```
git add folder-name/file-name.md
```
Om du har ändrat flera filer anger du ett git add kommando för varje fil.

Du kan också köra git add . (notera perioden efter add) för att automatiskt mellanlagra alla ändringar som du har gjort. Den här metoden är snabbare men kan orsaka problem genom att inkludera ändringar som du gjort av misstag.
Kör git status igen för att bekräfta vilka ändringar som har mellanlagrats.
git commit Kör kommandot följt av ett incheckningsmeddelande för att spara ändringarna i den lokala klonade lagringsplatsen.
```
git commit -m "your commit message"
```
Kör git push för att push-överföra ändringarna.
```
git push
```

Du kan skapa och push-överföra en incheckning med hjälp av Git-integreringsfunktionerna i VS Code. Kom ihåg att fortsätta ditt arbete på samma dator. Om du byter dator har du inte den senaste versionen av arbetsgrenen att fortsätta med.

Kontrollera att din lokala lagringsplats fortfarande har samma arbetsgren utcheckad. I VS Code-användargränssnittet visas grenen i det nedre vänstra hörnet. Grennamnet fungerar också som en knapp för att växla grenar.
I sidofältet till vänster i VS Code väljer du förgreningsverktyget för att se fönstret Källkontroll: Git .

Filen som du redigerade visas under Ändringar med ett M till höger för att indikera att den har ändrats. Nya filer visas med ett U (ospårat) och borttagna filer visas med ett D.
Mellanlagra ändringarna. Hovra över raden Ändringar tills en + ikon visas. Välj den ikonen. Den här åtgärden motsvarar git add kommandot. Filen visas nu i avsnittet Mellanlagrade ändringar .
Ange ett incheckningsmeddelande som "uppdatera metadatadatum" i textrutan Meddelande och markera bockmarkeringen.
Skicka incheckningen. Välj knappen Synkronisera ändringar som visas under incheckningsmeddelandeblocket.

Du har gjort det! Koden är nu uppe på din GitHub-lagringsplats och är redo att öppna en PR.

Behöver du åtgärda något som du redan har skickat? Det är enkelt! Upprepa bara stegen ovan, från och med Redigera filen, för att göra ändringar i samma gren och sedan checka in och push-överföra igen (du behöver inte konfigurera den överordnade servern vid efterföljande push-överföringar av samma gren). I allmänhet används grenar för att separera arbetsströmmar, så du behöver inte skapa en ny gren om du inte är redo att arbeta med något annat.

Gör nästa ändring

Är du redo att göra en ny ändring som inte är relaterad till den här? Växla tillbaka till standardgrenen, hämta från den överordnade lagringsplatsen för att uppdatera din förgrening och kolla in en ny gren. Kör följande kommandon i Git Bash:

git checkout main
git pull upstream main
git checkout -b "branchname"
git push origin <branch-name> -u

Nu är du i en ny gren som är länkad till fjärrgrenen och du är redo att göra fler ändringar. Du är på god väg att bli expert!

Nästa steg

Om du har slutfört stegen ovan är det dags att öppna en PR för att få ändringarna sammanfogade i huvudgrenen.
Mer information om ämnen som Markdown- och Markdown-tilläggssyntax finns i Markdown-referensen.

Dela via