Provádění důležitých změn v dokumentaci k Microsoft Learn

Důležité

Všechna úložiště, která publikují do microsoft Learn, přijala pravidla chování microsoftu open source nebo pravidla chování pro .NET Foundation. Další informace najdete v častých otázkách k pravidlům chování. Se svými dotazy nebo připomínkami se můžete také obrátit na opencode@microsoft.com nebo conduct@dotnetfoundation.org.

Menší opravy nebo objasnění dokumentace a příkladů kódu ve veřejných úložištích se týkají learn.microsoft.com podmínek použití. Jakékoli změny vygenerují v žádosti o přijetí změn komentář a požádá vás, abyste odeslali online licenční smlouvu s příspěvkem (CLA), pokud nejste zaměstnancem Microsoftu. Aby mohla být vaše žádost o přijetí změn sloučena, musíte online formulář vyplnit.

Tento článek ukazuje, jak změnit článek Microsoft Learn pomocí místních nástrojů a je vhodný pro přispěvatele, který potřebuje provést velkou změnu nebo bude častým přispěvatelem do úložiště. Často přispěvatelé obvykle mají probíhající nebo dlouhotrvající změny, které procházejí více cykly sestavení, ověřování a přípravy nebo se zabývají více dnů, než se odhlásí ke své žádosti o přijetí změn.

Mezi příklady těchto typů příspěvků patří:

• Rozsáhlý příspěvek: Například vaše příspěvky (přidání, změny nebo odstranění) můžou zahrnovat více článků a je třeba je potvrdit a otestovat jako jednu jednotku práce v jedné žádosti o přijetí změn.
• Vytvoření a publikování nového článku: Obvykle se vyžaduje robustnější místní editor.
• Přidání nových obrázků nebo aktualizace obrázků, které obvykle vyžadují, abyste současně vytvořili nový media podadresář, vytvořili soubory obrázků, aktualizovali odkazy na obrázky v článcích a náhled souborů Markdownu v místním editoru pro testování vykreslování obrázků.
• Aktualizace článku v průběhu několika dnů před publikováním: V těchto případech obvykle potřebujete provést pravidelnou integraci jiných změn, ke kterým dochází ve výchozí větvi. Tato integrace je snadnější přes Git Bash a místní úpravy. Pokud to uděláte pomocí webového editoru GitHubu, riskujete také ztrátu úprav a počkáte, než změny potvrdíte.
• Průběžné aktualizace stejného článku po otevření žádosti o přijetí změn I když k tomuto účelu můžete použít webový editor GitHubu, můžete pro stejný soubor vytvořit několik nevyřízených žádostí o přijetí změn, což může být v konfliktu s druhým.

Požadavky

• Identifikujte úložiště GitHub, ve kterém je uložená dokumentace, kterou chcete upravit.
• Pokud ho nemáte, vytvořte si účet GitHub.
• Nainstalujte nástroje Git a Markdown.
• Nastavte místní úložiště Git.
• Projděte si základy Gitu a GitHubu (volitelné).

Vytvoření a rezervace pracovní větve

Začněte tak, že v místním úložišti vytvoříte novou pracovní větev, která bude zaznamenávat navrhované změny. Další informace o větvích najdete v tématu Základy Gitu a GitHubu.

Tento kurz používá Git Bash a Visual Studio Code, ale můžete použít libovolného klienta a editoru Git, který dáváte přednost.

1. Ve VS Code otevřete složku úložiště místního klonu. V nabídce Soubor vyberte Otevřít složku a přejděte do složky na svém počítači.

2. V horní nabídce vyberte View (Zobrazit ) a pak vyberte Terminal (Terminál ) a otevřete integrovaný terminál.

3. V integrovaném terminálu se ujistěte, že jste ve složce úložiště.

4. Než vytvoříte pracovní větev, ujistěte se, že je místní hlavní větev aktuální se vším v hlavní větvi produkčního úložiště. Tato úloha zajistí, že vaše pracovní větev zachytí všechny změny, ke kterým došlo v produkčním úložišti od poslední synchronizace.

   1. Přepněte do hlavní větve v místním úložišti:

      git checkout main 
      

   2. Ujistěte se, že je vaše místní hlavní větev aktuální:

      git pull upstream main 
      

5. Vytvořte místní pracovní větev na základě hlavní větve:

   git checkout -b <branch-name>
   

   <branch-name> je zástupný symbol. Když příkaz spustíte, nahraďte ho jedinečným a smysluplným názvem větve a odeberte úhlové závorky.

6. Nasdílejte místní pracovní větev do vzdálené větve ve forku GitHubu:

   git push origin <branch-name> -u
   

   Možnost -u propojuje místní a vzdálené větve. Tato možnost umožňuje nasdílení potvrzení do forku tak, že místo toho zadáte git push git push origin <branch-name>.

Vyhledání zdrojového souboru Markdownu

Pokud chcete upravit článek, vyhledejte zdrojový soubor článku ve klonu místního úložiště. V editoru VS Code přejděte k souborům Markdownu úložiště prostřednictvím Průzkumníka souborů (ikona dokumentu v levém horním bočním panelu). Průzkumník souborů zobrazuje strukturu složek úložiště a můžete přejít na soubor, který chcete upravit.

Pokud soubor nemůžete najít, přejděte do článku na Webu Microsoft Learn a vyberte ikonu Upravit tužku. Relativní umístění složky v úložišti GitHub se zobrazuje v adrese URL. Tady je příklad adresy URL odkazu pro úpravy :

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

Tady je příklad umístění souboru pro tuto adresu URL.

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

Úprava souboru

1. Otevřete soubor ve VS Code tak, že ho vyberete.
2. Proveďte změny.
3. Změny uložte výběrem možnosti Uložit soubor>. Pomocí příkazu Uložit vše můžete uložit více souborů najednou.

Potvrzení a nasdílení změn

Pokud jste provedli podstatné úpravy nebo jste si prostudovali článek o aktuálnosti, aktualizujte ms.date ho v bloku metadat v horní části souboru. Naformátujte datum jako mm/dd/rrrr.

K potvrzení a nasdílení změn můžete použít terminál VS Code nebo uživatelské rozhraní VS Code.

Terminál VS Code

1. Spuštěním git status příkazu ověřte, že se v seznamu změněných souborů zobrazí jenom soubory, které jste upravili.

   git status
   

2. git add Spusťte příkaz následovaný cestou k souboru a názvem souboru a připravte soubor, který jste změnili.

   git add folder-name/file-name.md
   

   Pokud jste změnili více souborů, zadejte git add příkaz pro každý soubor.

   Případně můžete spustit git add . (všimněte si období po add) a automaticky zfázovat všechny provedené změny. Tato metoda je rychlejší, ale může způsobit problémy zahrnutím změn, které jste omylem provedli.

3. Spusťte git status znovu, abyste potvrdili, jaké změny byly připraveny.

4. git commit Spusťte příkaz následovaný zprávou potvrzení a uložte změny v místním klonovaném úložišti.

   git commit -m "your commit message"
   

5. Spuštěním nasdílejte git push změny.

   git push
   

Uživatelské rozhraní VS Code

Potvrzení můžete vytvořit a odeslat pomocí funkcí integrace Gitu v editoru VS Code. Nezapomeňte pokračovat v práci na stejném počítači. Pokud přepnete počítače, nebudete mít nejnovější verzi pracovní větve, abyste mohli pokračovat.

1. Ujistěte se, že vaše místní úložiště má stále rezervovanou stejnou pracovní větev. V uživatelském rozhraní VS Code se větev zobrazí v levém dolním rohu. Název větve také funguje jako tlačítko pro přepínání větví.

   

2. Na levém bočním panelu VS Code vyberte nástroj forku a zobrazte podokno Správa zdrojového kódu: Git .

   

   Soubor, který jste upravili, se zobrazí v části Změny s M na pravé straně, aby bylo uvedeno, že byl změněn. Nové soubory se zobrazí s U (nesledované) a odstraněné soubory se zobrazí s příponou D.

3. Připravte změny. Najeďte myší na řádek Změny , dokud + se nezobrazí ikona. Vyberte tuto ikonu. Tato akce je ekvivalentní příkazu git add . Soubor se teď zobrazí v části Fázované změny .

4. Do textového pole Zpráva zadejte zprávu potvrzení, například "aktualizovat datum metadat" a zaškrtněte políčko.

   

5. Nasdílí potvrzení. Vyberte tlačítko Synchronizovat změny, které se zobrazí pod blokem potvrzení-zpráva.

   

A máte to hotové! Váš kód je teď v úložišti GitHubu a připravený k otevření žádosti o přijetí změn.

Potřebujete opravit něco, co jste odeslali? Je to snadné! Opakujte výše uvedené kroky, počínaje úpravou souboru, proveďte změny ve stejné větvi a pak potvrďte a odešlete znovu (není nutné nastavit nadřazený server na následných nasdílení změn stejné větve). Obecně platí, že větve se používají k oddělení datových proudů práce, takže nemusíte vytvářet novou větev, pokud nejste připravení pracovat na něčem jiném.

Provedení další změny

Jste připravení provést další změnu, nesouvisející s touto změnou? Přepněte zpět na výchozí větev, stáhněte si z upstreamového úložiště, aktualizujte fork a podívejte se na novou větev. V okně Git Bash spusťte následující příkazy:

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

Teď jste v nové větvi, která je propojená s vaší vzdálenou větví, a jste připraveni provést další změny. Jste na cestě stát se expertním přispěvatelem!

Další kroky

• Pokud jste dokončili výše uvedené kroky, teď je čas otevřít žádost o přijetí změn , aby se změny sloučily do hlavní větve.
• Další informace o tématech, jako je Markdown a syntaxe rozšíření Markdownu, najdete v referenčních informacích k Markdownu.