Vykonanie hlavných zmien v dokumentácii Microsoft Learn

Dôležité

Všetky odkladacie priestory, ktoré publikujú do služby Microsoft Learn, prijali pravidlá správania Microsoft Open Source Code of Conduct alebo .NET Foundation Code of Conduct. Ďalšie informácie nájdete v téme Najčastejšie otázky pre pravidlá správania. Ak máte akékoľvek otázky alebo komentáre, obráťte sa na adresu opencode@microsoft.com alebo conduct@dotnetfoundation.org.

Drobné opravy alebo objasnenia k dokumentácii a príklady kódov vo verejných odkladacích priestoroch sú zahrnuté v learn.microsoft.com podmienkami používania. Akékoľvek zmeny budú mať za následok vygenerovanie komentára v žiadosti o prijatie zmien. Ak nie ste zamestnancom spoločnosti Microsoft, zobrazí sa žiadosť o odoslanie online licenčnej zmluvy na prispievanie (CLA). Pred zlúčením žiadosti o prijatie zmien budete musieť vyplniť online formulár.

V tomto článku sa dozviete, ako zmeniť článok služby Microsoft Learn pomocou lokálnych nástrojov a je vhodný pre prispievateľa, ktorý potrebuje vykonať významnú zmenu alebo bude častým prispievateľom do odkladacieho priestoru. Častí prispievatelia majú zvyčajne prebiehajúce alebo dlhodobé zmeny, ktoré prechádzajú viacerými cyklami typu vytvorenie/overenie/pracovná časť alebo trvajú viac dní predtým, ako sa prihlásia so svojou žiadosťou o prijatie zmien (PR).

Príklady týchto druhov príspevkov zahŕňajú:

• Pridanie veľkého príspevku. Napríklad vaše príspevky (dodatky, zmeny alebo odstránenia) sa môžu týkať viacerých článkov a je potrebné, aby boli potvrdené a testované ako jedna jednotka práce v jednej žiadosti o prijatie zmien.
• Vytvorenie a publikovanie nového článku, ktoré zvyčajne vyžaduje robustnejší lokálny editor.
• Pridávanie nových obrázkov alebo aktualizácia obrázkov, ktoré zvyčajne vyžaduje súčasné vytvorenie nového media podadresára, vytvorenie obrázkových súborov, aktualizovanie prepojení na obrázky v článkoch a ukážku súborov jazyka Markdown v lokálnom editore na testovanie vykresľovania obrázka.
• Aktualizácia článku počas niekoľkých dní pred publikovaním. V týchto prípadoch je zvyčajne potrebné robiť pravidelnú integráciu iných zmien, ktoré sa vyskytujú v predvolenej vetve. Táto integrácia je jednoduchšia cez Git Bash a lokálne úpravy. Hrozí aj strata úprav, ak to robíte prostredníctvom webového editora služby GitHub a pred odoslaním zmien čakáte.
• Vytváranie neustálych aktualizácií do toho istého článku po otvorení PR. Aj keď na tento účel môžete použiť webový editor služby GitHub, môžete pre ten istý súbor vytvoriť viaceré vynikajúce žiadosti o prijatie zmien, ktoré môžu byť navzájom v rozpore.

Predpoklady

• Identifikujte odkladací priestor GitHub, ktorý uchováva dokumentáciu, ktorú chcete upraviť.
• Ak ho nemáte, vytvorte si konto v službe GitHub.
• Nainštalujte si nástroje systému Git a jazyka Markdown.
• Nastavte lokálny odkladací priestor systému Git.
• Prečítajte si základy systémov Git a GitHub (voliteľné).

Vytvorenie a kontrola pracovnej vetvy

Ak chcete začať, vytvorte novú pracovnú vetvu v lokálnom odkladacom priestore na zaznamenanie navrhovaných zmien. Ďalšie podrobnosti o vetvách nájdete v téme Základy systémov Git a GitHub.

Tento kurz používa Git Bash a Visual Studio Code, ale môžete použiť ľubovoľného klienta a editora Git, ktorý preferujete.

1. V nástroji VS Code otvorte priečinok odkladacieho priestoru lokálneho klonu. V ponuke Súbor vyberte položku Otvoriť priečinok a prejdite do priečinka vo vašom počítači.

2. V hornej ponuke vyberte položku Zobraziť a potom vyberte položku Terminal (Terminál ), čím otvoríte integrovaný terminál.

3. V integrovanom termináli sa uistite, že sa nachádzate v priečinku odkladacieho priestoru.

4. Pred vytvorením pracovnej vetvy sa uistite, že lokálna hlavná vetva je aktuálna so všetkým v hlavnej vetve odkladacieho priestoru produkcie. Táto úloha zabezpečí, že pracovná vetva zaznamená všetky zmeny, ktoré sa vykonali v produkčnom odkladacom priestore od posledného synchronizovania s pracovným priestorom.

   1. Prepnite na hlavnú vetvu v lokálnom odkladacom priestore:

      git checkout main 
      

   2. Skontrolujte, či je lokálna hlavná vetva aktuálna:

      git pull upstream main 
      

5. Vytvorte lokálnu pracovnú vetvu založenú na hlavnej:

   git checkout -b <branch-name>
   

   <branch-name> je zástupný symbol. Po spustení príkazu ho nahraďte jedinečným a zmysluplným názvom vetvy a odstráňte lomené zátvorky.

6. Zatlačte miestnu pracovnú vetvu do vzdialenej vetvy vo svojej vetve v službe GitHub:

   git push origin <branch-name> -u
   

   Možnosť -u spája lokálne a vzdialené vetvy. Táto možnosť vám umožňuje odoslať potvrdenia do svojej vetvy zadaním iba git push namiesto položky git push origin <branch-name>.

Vyhľadanie zdrojového súboru v jazyku Markdown

Ak chcete upraviť článok, nájdite zdrojový súbor pre článok v klone lokálneho odkladacieho priestoru. V rámci nástroja VS Code získajte prístup k súborom jazyka Markdown odkladacieho priestoru prostredníctvom prieskumníka súborov (ikona dokumentu v ľavom hornom paneli). Prieskumník súborov zobrazuje štruktúru priečinkov odkladacieho priestoru a môžete prejsť na súbor, ktorý chcete upraviť.

Ak súbor nemôžete nájsť, prejdite do článku na lokalite Microsoft Learn a vyberte ikonu ceruzky Upraviť . Umiestnenie relatívneho priečinka v odkladacom priestore GitHub sa zobrazuje v URL adrese. Tu je príklad Úprava URL adresy prepojenia:

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

Tu je príklad umiestnenia súboru pre túto URL adresu.

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

Úprava súboru

1. Otvorte súbor v nástroji VS Code tak, že ho vyberiete.
2. Vykonajte zmeny.
3. Uložte zmeny výberom položky Súbor>Uložiť. Ak chcete uložiť viacero súborov naraz, použite možnosť Uložiť všetko .

Potvrdenie a doručenie zmien

Ak ste vykonali podstatné úpravy alebo ste kontrolovali aktuálnosť článku, aktualizujte ms.date v bloku metaúdajov v hornej časti súboru. Naformátujte dátum ako mm/dd/rrrr.

Na potvrdenie a presunutie zmien môžete použiť terminál VS Code alebo používateľské rozhranie programu VS Code.

VS Code Terminal

1. Spustením git status príkazu overte, či sa v zozname zmenených súborov zobrazujú iba súbory, ktoré ste upravili.

   git status
   

2. git add Spustite príkaz, za ktorým nasleduje cesta k súboru a názov súboru do fázy súboru, ktorý ste zmenili.

   git add folder-name/file-name.md
   

   Ak ste zmenili viacero súborov, zadajte git add príkaz pre každý súbor.

   Prípadne môžete spustiť git add . (všimnite si bodku po add) a automaticky nastaviť všetky vykonané zmeny. Táto metóda je rýchlejšia, ale môže spôsobiť problémy zahrnutím zmien, ktoré vykonáte náhodou.

3. Znova spustite, git status aby ste potvrdili, ktoré zmeny boli zinscenované.

4. git commit Spustite príkaz, za ktorým nasleduje správa potvrdenia, aby sa uložili zmeny v lokálnom klonovaní odkladacieho priestoru.

   git commit -m "your commit message"
   

5. Ak chcete zmeny posunúť, spustite git push príkaz .

   git push
   

Používateľské rozhranie programu VS Code

Potvrdenie môžete vytvoriť a odoslať pomocou funkcií integrácie Git VS Code. Nezabudnite pokračovať v práci na tom istom počítači. Ak prepínate počítače, nebudete mať najnovšiu verziu pracovnej vetvy, v ak chcete pokračovať.

1. Uistite sa, že váš lokálny odkladací priestor má stále rovnakú pracovnú vetvu. V používateľskom rozhraní programu VS Code sa vetva zobrazí v ľavom dolnom rohu. Názov vetvy tiež funguje ako tlačidlo na prepínanie vetiev.

   

2. Na ľavom bočnom paneli programu VS Code vyberte nástroj vetvenia, aby sa zobrazil tabla Zdrojový ovládací prvok: Git .

   

   Súbor, ktorý ste upravili, sa zobrazí v časti Zmeny s jazykom M vpravo na označenie, že bol upravený. Nové súbory sa zobrazia s používateľskou dráhou (nesledované) a odstránené súbory sa zobrazia s D.

3. Vymedzte zmeny. Ukážte myšou na riadok Zmeny , + kým sa nezobrazí ikona. Vyberte túto ikonu. Táto akcia je ekvivalentom git add príkazu. Súbor sa teraz zobrazí v časti Fázované zmeny .

4. Zadajte správu potvrdenia, napríklad "aktualizovať dátum metaúdajov" do textového poľa Správa , a začiarknite políčko.

   

5. Zatlačte potvrdenie. Vyberte tlačidlo Synchronizovať zmeny, ktoré sa zobrazí pod blokom hlásenia hlásenia.

   

Urobili ste to! Váš kód je teraz vo vašom odkladacom priestore GitHub a je pripravený na otvorenie PR.

Potrebujete opraviť niečo, čo ste odoslali? Je to jednoduché. Ak chcete vykonať zmeny v tej istej vetve a potom potvrdiť a tlačiť znova, zopakujte kroky uvedené vyššie počnúc úpravou súboru (nie je potrebné nastavovať server upstream pri následných presunutiech tej istej vetvy). Vo všeobecnosti sa vetvy používajú na oddelenie pracovných prúdov, takže nemusíte vytvárať novú vetvu, pokiaľ nie ste pripravení pracovať na niečom inom.

Vykonať ďalšiu zmenu

Ste pripravení vykonať ďalšiu zmenu, ktorá nesúvisí s touto? Prepnite sa späť na predvolenú vetvu, prijmite kroky z upstreamového odkladacieho priestoru, aktualizujte svoju vetvu a prejdite na novú vetvu. Spustite nasledujúce príkazy v aplikácii Git Bash:

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

Teraz sa nachádzate v novej vetve, ktorá je prepojená s vašou vzdialenou vetvou a ste pripravení vykonať ďalšie zmeny. Ste na dobre ceste stať sa odborným prispievateľom.

Ďalšie kroky

• Ak ste dokončili kroky uvedené vyššie, teraz je čas otvoriť žiadosť o prijatie zmien, aby sa vaše zmeny zlúčili do hlavnej vetvy.
• Ďalšie informácie o témach, ako je napríklad jazyk Markdown a syntax rozšírení jazyka Markdown, nájdete v téme Referenčné informácie o jazyku Markdown.