Jelentős módosítások a Microsoft Learn dokumentációjában

  • Cikk

Fontos

A Microsoft Learnben közzétevő összes adattár a Microsoft nyílt forráskódú magatartási kódexét vagy a .NET Foundation magatartási kódexét fogadta el. További információkért keresse fel a Viselkedési szabályzattal kapcsolatos gyakori kérdések oldalát, illetve elküldheti kérdéseit és észrevételeit az opencode@microsoft.com vagy a conduct@dotnetfoundation.org címre.

A nyilvános adattárakban található dokumentációk és kódpéldák kisebb javításait és pontosításait a learn.microsoft.com Használati feltételek ismertetik. Minden módosítás megjegyzést fog generálni a lekéréses kérelemben, amely arra kéri, hogy küldjön be egy online hozzájárulási licencszerződést (CLA), ha Ön nem a Microsoft alkalmazottja. A lekéréses kérelme csak akkor dolgozható fel, ha előzőleg kitöltötte az online űrlapot.

Ez a cikk bemutatja, hogyan módosíthatja a Microsoft Learn-cikkeket helyi eszközökkel, és hogyan használható olyan közreműködők számára, akiknek jelentős módosítást kell végeznie, vagy gyakori közreműködője lesz egy adattárnak. A gyakori közreműködők általában folyamatos vagy hosszú ideig futó módosításokat hajtanak végre, amelyek több buildelési/érvényesítési/előkészítési cikluson mennek keresztül, vagy több napig tartanak, mielőtt kijelentkeznének a lekéréses kérelemre (PR).

Ilyen típusú közreműködések többek között az alábbiak:

  • Nagy hozzájárulást. A hozzájárulások (kiegészítések, módosítások vagy törlések) például több cikkre is kiterjedhetnek, és egyetlen lekéréses kérelemben egyetlen munkaegységként kell véglegesíteni és tesztelni.
  • Új cikk létrehozása és közzététele, amelyhez általában robusztusabb helyi szerkesztőre van szükség.
  • Új képek hozzáadása vagy képek frissítése, ami általában megköveteli, hogy egyszerre hozzon létre egy új media alkönyvtárat, hozzon létre képfájlokat, frissítse a cikkekben lévő képhivatkozásokat, és tekintse meg a Markdown-fájlokat egy helyi szerkesztőben a képmegjelenítés teszteléséhez.
  • Cikk frissítése a közzététel előtt néhány nappal. Ezekben az esetekben általában az alapértelmezett ágban előforduló egyéb módosítások rendszeres integrációját kell elvégeznie. amit egyszerűbb elvégezni a Git Bash használatával és helyi szerkesztéssel. Ha ezt a GitHub-webszerkesztőn keresztül hajtja végre, és megvárja a módosítások véglegesítését, akkor a módosítások elvesztésének kockázata is fennáll.
  • A lekéréses kérelem megnyitása után folyamatosan frissítheti ugyanazt a cikket. Bár ehhez használhatja a GitHub webszerkesztőt, több kiemelkedő PRS-t is létrehozhat ugyanahhoz a fájlhoz, ami ütközhet egymással.

Előfeltételek

A munkaág létrehozása és kivétele

Első lépésként hozzon létre egy új munkaágat a helyi adattárban a javasolt módosítások rögzítéséhez. Az ágakkal kapcsolatos további háttérért tekintse meg a Git és a GitHub alapjait.

Ez az oktatóanyag a Git Basht és a Visual Studio Code-ot használja, de bármilyen Git-ügyfelet és szerkesztőt használhat.

  1. A VS Code-ban nyissa meg a helyi klón adattármappáját. A Fájl menüben válassza a Mappa megnyitása lehetőséget, és lépjen a számítógépen lévő mappára.

  2. A felső menüben válassza a Nézet lehetőséget, majd a Terminál lehetőséget az integrált terminál megnyitásához.

  3. Az integrált terminálban győződjön meg arról, hogy az adattár mappájában van.

  4. Mielőtt létrehoz egy munkaágat, győződjön meg arról, hogy a helyi főág naprakész az éles adattár főágában lévő összes elemével. Ez a feladat biztosítja, hogy a munkaág rögzítse a legutóbbi szinkronizálás óta az éles adattárban történt módosításokat.

    1. Váltson a helyi adattár fő ágára:

      git checkout main

    2. Győződjön meg arról, hogy a helyi főág aktuális:

      git pull upstream main

  5. Hozzon létre egy helyi munkaágat a fő alapján:

    git checkout -b <branch-name>

    <branch-name> helyőrző. A parancs futtatásakor cserélje le az ág egyedi és értelmes nevére, és távolítsa el a szögletes zárójeleket.

  6. A helyi munkaág leküldése a GitHub-elágazás távoli ágára:

    git push origin <branch-name> -u

    A -u lehetőség összekapcsolja a helyi és a távoli ágakat. Ezzel a beállítással leküldheti a véglegesítéseket az elágaztatásba úgy, hogy ahelyett, hogy beírja git pushgit push origin <branch-name>őket.

A forrás Markdown-fájl megkeresése

Cikk szerkesztéséhez keresse meg a cikk forrásfájlját a helyi adattár klónjában. A VS Code-ban a fájlkezelőn (a bal felső oldalsávon található dokumentumikonon) keresztül érheti el az adattár Markdown-fájljait. A fájlkezelő megjeleníti az adattár mappastruktúráját, és navigálhat a szerkeszteni kívánt fájlhoz.

Ha nem találja a fájlt, látogasson el a Microsoft Learn cikkére, és válassza a Ceruza szerkesztése ikont. A GitHub-adattár relatív mappahelye megjelenik az URL-címen. Íme egy példa a hivatkozás URL-címének szerkesztése :

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

Íme egy példafájl helye ehhez az URL-címhez.

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

A fájl szerkesztése

  1. Nyissa meg a fájlt a VS Code-ban a kijelölésével.
  2. Végezze el a módosításokat.
  3. Mentse a módosításokat a Fájl>mentése gombra kattintva. Az Összes mentése parancs egyszerre több fájlt is menthet.

Módosítások véglegesítése és leküldése

Ha jelentős módosításokat végzett, vagy áttekintett egy cikket a frissesség érdekében, frissítsen ms.date a fájl tetején található metaadat-blokkban. Formázza a dátumot mm/dd/yyy formátumban.

A MÓDOSÍTÁSOK véglegesítéséhez és leküldéséhez használhatja a VS Code terminált vagy a VS Code felhasználói felületét.

  1. Futtassa a git status parancsot annak ellenőrzéséhez, hogy csak a szerkesztett fájlok jelennek-e meg a módosított fájlok listájában.

    git status

  2. Futtassa a git add parancsot, majd a fájl elérési útját és nevét a módosított fájl szakaszához.

    git add folder-name/file-name.md

    Ha több fájlt módosított, minden fájlhoz adjon meg egy git add parancsot.

    Másik lehetőségként futtathatja git add . (jegyezze fel az azt követő addidőszakot) az összes elvégzett módosítás automatikus szakaszához. Ez a módszer gyorsabb, de problémákat okozhat, ha véletlenül módosítja a módosításokat.

  3. Futtassa git status újra a módosításokat.

  4. Futtassa a git commit parancsot, majd egy véglegesítési üzenettel mentse a módosításokat a helyi klónozott adattárban.

    git commit -m "your commit message"

  5. Futtassa git push a módosítások leküldését.

    git push

Készen is van! A kód most már fel van állítva a GitHub-adattárban, és készen áll a lekéréses kérelem megnyitására.

Ki kell javítania valamit, amit már elküldött? Könnyű! Csak ismételje meg a fenti lépéseket, kezdve a fájl szerkesztésével, hogy módosításokat hajtson végre ugyanabban az ágban, majd véglegesítse és küldje újra (nem kell beállítania a felsőbb rétegbeli kiszolgálót ugyanazon ág későbbi leküldéseinél). Az ágak általában a munkafolyamok elkülönítésére szolgálnak, így csak akkor kell új ágat létrehoznia, ha készen áll arra, hogy valami máson dolgozzon.

Végezze el a következő módosítást

Készen áll egy másik módosításra, nem kapcsolódik ehhez? Váltson vissza az alapértelmezett ágra, húzza le a felső adattárból az elágazás frissítéséhez, és válasszon ki egy új ágat. Futtassa az alábbi parancsot a Git Bashben:

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

Most egy új ágban van, amely a távoli ághoz van csatolva, és készen áll további módosításokra. Jó úton jár ahhoz, hogy szakértő közreműködővé váljon!

Következő lépések

  • Ha elvégezte a fenti lépéseket, most már meg kell nyitnia egy lekéréses kérelmet , hogy a módosítások egyesítve lesznek a főágban.
  • Ha többet szeretne megtudni az olyan témakörökről, mint a Markdown és a Markdown-bővítmények szintaxisa, tekintse át a Markdown-hivatkozást.