Základy Gitu a GitHubu pro dokumentaci k Microsoft Learn

  • Článek

Přehled

Jako přispěvatel dokumentace k Microsoft Learn budete pracovat s několika nástroji a procesy. Budete pracovat souběžně s ostatními přispěvateli na stejném projektu, možná na úplně stejném obsahu, dokonce i ve stejnou dobu. To vše umožňuje software Gitu a GitHubu.

Git je open-sourcový systém správy verzí. Usnadňuje tento typ spolupráce na projektech prostřednictvím distribuovaného systému správy verzí souborů umístěných v úložištích. Git v podstatě umožňuje u daného úložiště integrovat proudy práce provedené několika přispěvateli v průběhu času.

GitHub je webová hostitelská služba pro úložiště Git, například pro úložiště Microsoft Learn . U každého projektu GitHub hostuje hlavní úložiště, ze kterého můžou přispěvatelé vytvářet kopie pro vlastní potřebu.

Tento článek definuje klíčové termíny, které jsou součástí pracovního postupu Microsoft Learn. Poskytuje také přehled úložišť Git a GitHub a vysvětluje, jak je obsah uspořádaný pro technickou dokumentaci Microsoftu.

Pobočka

Větve oddělují toky práce (obvykle označované jako verze). Příspěvky se vždy provádějí do konkrétní větve.

Izolování souvisejících změn v konkrétní větvi umožňuje řídit a zavádět tyto změny nezávisle. V závislosti na typu práce můžete mít ve skutečnosti v úložišti několik pracovních větví. Není neobvyklé pracovat současně na více větvích, z nichž každá představuje jiný projekt.

Všechna úložiště obsahují výchozí větev (obvykle s názvem "main") a jednu nebo více probíhajících větví (které voláme pracovní větve), které ještě nebyly integrovány do výchozí větve. Výchozí větev slouží jako aktuální verze a "jediný zdroj pravdy" pro projekt. Je nadřazenou větví, ze které se vytvářejí všechny ostatní větve v úložišti.

Pokaždé, když zavádíte novou sadu logicky souvisejících změn, je osvědčeným postupem vytvořit pracovní větev pro správu změn. Nedoporučujeme provádět změny výchozí větve přímo.

Fork

Tento termín se obvykle používá jako podstatné jméno při odkazování na kopii hlavního úložiště GitHubu. V praxi je fork prostě další úložiště. Je ale speciální v tom smyslu, že GitHub udržuje jeho spojení zpět s hlavním/nadřazeným úložištěm. Tento termín se někdy používá jako sloveso, jako v části "Musíte nejprve vytvořit fork úložiště".

Git

Pokud znáte centralizované systémy správy verzí (například Team Foundation Server, SharePoint nebo Visual Source Sejf), všimnete si, že Git má jedinečný pracovní postup přispívání a terminologie pro podporu distribuovaného modelu. Například neexistuje žádné zamykání souborů, které by normálně souvisely s operacemi rezervace nebo vrácení se změnami. Místo toho se Git zabývá změnami na ještě jemnější úrovni a porovnává soubory bajtů bajtů.

Git také k ukládání a správě obsahu pro projekt používá strukturu úrovní:

  • Úložiště: úložiště je nejvyšší jednotka pro ukládání dat. Úložiště obsahuje jednu nebo více větví.
  • Větev: jednotka úložiště obsahující soubory a složky, které tvoří sadu obsahu projektu. Další informace o větvích najdete v části Větev tohoto článku.

Přispěvatelé při práci s Gitem aktualizují a upravují úložiště jak na místní úrovni, tak na úrovni GitHubu:

  • Místně prostřednictvím nástrojů jako je konzola Git Bash, která podporuje příkazy Gitu pro správu místních úložišť a komunikaci s úložišti GitHubu.
  • Prostřednictvím webu www.github.com, který integruje Git pro účely správy sloučení příspěvků, které se přenášejí zpět do hlavního úložiště.

GitHubu

Poznámka:

I když pokyny k dokumentaci vycházejí z používání GitHubu, některé týmy k hostování úložišť Git používají Visual Studio Team Services. Klient Visual Studio Team Explorer poskytuje pro interakci s úložišti Team Service grafické uživatelské rozhraní, které je alternativou k používání příkazů Git pomocí příkazového řádku.
Mnohé z následujících pokynů byly také vyvinuty jako osvědčené postupy z let zkušeností s hostování obsahu služeb Azure na GitHubu. Můžou se vyžadovat v některých úložištích Microsoft Learn.

Všechny pracovní postupy začínají a končí na úrovni GitHubu, kde je uložené hlavní úložiště pro jakýkoli projekt dokumentace. Kopie, které přispěvatelé vytvářejí pro vlastní potřebu, jsou distribuované na víc počítačů. Tyto kopie se nakonec sloučí zpět do hlavního úložiště GitHub projektu.

Organizace adresáře

Výchozí větev projektu slouží jako aktuální verze obsahu projektu. Obsah ve výchozí větvi a větvích vytvořených z ní je volně sladěný s organizací článků na odpovídajících stránkách Microsoft Learn. Podadresáře se používají k oddělení, jako jsou články (například služby), mediální obsah (například soubory obrázků) a "zahrnout" soubory (které umožňují opakované použití obsahu).

Podadresář článků

Hlavní adresář articles obvykle najdete v kořenovém adresáři úložiště. Adresář articles obsahuje sadu podadresářů Články v podadresářích jsou formátovány jako soubory Markdown, které používají příponu .md . Některá úložiště podporující více služeb používají obecný podadresář /articles, jako například úložiště Azure-Docs. Jiná mohou používat název specifický pro službu, jako například úložiště IntuneDocs, které používá /IntuneDocs.

V kořenové složce tohoto adresáře naleznete obecné články související s obecným fungováním služby nebo produktu. Obvykle pak také najdete další řady podadresářů, které odpovídají příslušným funkcím/službám nebo běžným scénářům. Třeba články o „virtuálním počítači“ Azure jsou v podadresáři /virtual-machines, zatímco články o „porozumění a prozkoumání“ Intune jsou v podadresáři /understand-explore.

Podadresář Media

Adresář každého článku obsahuje podadresář /media pro odpovídající soubory médií. Soubory médií obsahují obrázky používané v článcích, které odkazují na obrázky.

Podadresář Includes

Pokud máme nějaký opakovaně použitelný obsah, který je sdílený dvěma nebo více články, je umístěný v podadresáři /includes hlavního adresáře articles. Do souboru Markdownu, který používá příslušný soubor zahrnutí, se na místo, kde se na tento soubor má odkazovat, umístí odpovídající rozšíření Markdownu pro „zahrnutí“.

Viz referenční informace k Markdownu: Obsahuje další pokyny.

Šablona souboru Markdown

Kořenový adresář každého úložiště obvykle pro pohodlnější používání obsahuje soubor šablony Markdownu s názvem template.md. Tento soubor šablony můžete použít jako „výchozí soubor“, pokud potřebujete vytvořit nový článek k odeslání do úložiště. Tento soubor obsahuje:

  • Záhlaví metadat v horní části souboru, vymezené dvěma řádky tvořenými třemi spojovníky. Obsahuje různé značky používané ke sledování informací týkajících se článku. Metadata článku umožňují některé funkce, jako je uvedení autora, uvedení přispěvatele, popis cesty a popisy článku. Zahrnují také optimalizaci pro vyhledávače (SEO) a procesy vytváření sestav, které Microsoft používá k vyhodnocení výkonu obsahu. Metadat jsou proto důležitá!
  • Sekci metadat popisující různé hodnoty a značky metadat. Pokud si nejste jistí, jaké hodnoty je třeba pro sekci metadat použít, můžete ji nechat prázdnou nebo přidat komentář začínající hashtagem (#). Kontrolor žádostí o přijetí změn pro příslušné úložiště pak tuto sekci zkontroluje a dokončí.
  • Různé příklady použití formátu Markdown pro formátování prvků článku.
  • Obecné pokyny týkající se použití rozšíření Markdownu, která můžete použít pro různé typy výstrah
  • Příklady vložení videa pomocí iframe
  • Obecné pokyny k používání rozšíření technické dokumentace společnosti Microsoft, které můžete použít pro speciální ovládací prvky, jako jsou tlačítka a selektory.

Zdroj

Tento termín je název přiřazený k propojení mezi místním úložištěm a úložištěm, ze kterého byl naklonován. V pracovním postupu Microsoft Learn představuje zdroj připojení k vašemu forku. Tento termín se někdy používá jako moniker pro samotné úložiště původu, například "Nezapomeňte nasdílit změny do zdroje".

Žádosti o přijetí změn

Žádost o přijetí změn (PR) je žádost vlastníka obsahu o přijetí změn do oficiálního zdroje. Žádost o přijetí změn umožňuje model spolupráce GitHubu tím, že požádá o změny (označované také jako potvrzení) z vaší pracovní větve, které se mají načíst a sloučit do jiné větve. Ve většině případů je druhá větev výchozí větví v hlavním úložišti.

Žádost o přijetí změn slouží také jako mechanismus, který přispěvateli poskytne zpětnou vazbu z ověřovacích procesů Microsoft Learn a revidujícímu žádosti o přijetí změn, aby vyřešil problémy nebo dotazy před sloučením změn do výchozí větve.

Vzdálené

Vzdálené je pojmenované připojení ke vzdálenému úložišti, například "origin" nebo "upstream". Git to označuje jako vzdálený, protože se používá k odkazování na úložiště hostované na jiném počítači. V pracovním postupu Microsoft Learn je vzdálené úložiště vždy úložiště GitHub.

Upstreamové

Stejně jako vzdálený zdroj je upstream pojmenovaným připojením k jinému úložišti. V pracovním postupu Microsoft Learn představuje upstream propojení mezi místním úložištěm a hlavním úložištěm, ze kterého byl váš fork vytvořen. Tento termín se někdy používá jako moniker samotného upstreamového úložiště, například "Nezapomeňte stáhnout nejnovější změny z upstreamu".

Další informace

Pokud git nebo GitHub neznáte, můžou vám tyto zdroje informací pomoct naučit se, být produktivní nebo odpovídat na otázky.

Prostředky správy zdrojového kódu Gitu

Prostředky GitHubu

Nejčastější dotazy

Co je Git?

Git pomáhá sledovat změny, když mnoho lidí pracuje na počítačovém kódu společně. Je to jako stroj času pro kód, takže můžete zjistit, co se změnilo, a v případě potřeby se vrátit.

Proč používat Git?

Je to skvělé pro týmovou práci. Git usnadňuje spoustě lidí pracovat na stejném projektu, aniž by si museli vzájemně pokazit práci. Pomáhá také snadno opravit chyby.

Jak Git funguje?

Git ukládá všechny verze kódu projektu. Když provedete změny, Git pořídí obrázek (třeba snímek) toho, co se liší. Bez problému můžete současně vytvářet různé verze.

Co jsou větve v Gitu?

Větve se v projektu podobají různým cestám. Umožňují lidem pracovat na nových věcech beze změny hlavního projektu. Později můžou tyto změny přenést zpět do hlavního projektu.

Co je potvrzení v Gitu?

Potvrzení je jako bod uložení. Je to způsob, jak zaznamenávat změny, které jste udělali. Každé potvrzení má jedinečné ID a poznámku o tom, co se změnilo.

Co je GitHub?

GitHub je web, na kterém můžete ukládat své projekty Git. Je to jako velké centrum pro sdílení a spolupráci na kódu s ostatními. Pomáhá také sledovat, kdo co změnil.

Jak se GitHub liší od Gitu?

Git je nástroj pro sledování změn, zatímco GitHub je místem pro ukládání projektů a spolupráci. GitHub používá Git ke své magii.

Je GitHub zdarma?

Ano, pro projekty můžou vidět všichni. Ale u soukromých projektů (jenom vy a váš tým) možná budete muset zaplatit. Nabízejí různé plány s dalšími funkcemi.

Co jsou žádosti o přijetí změn na GitHubu?

Žádosti o přijetí změn se podobají žádosti o vložení změn do hlavního projektu. Lidé můžete změny před jejich přidáním zkontrolovat a probrat.

Jak bezpečný je GitHub?

GitHub se postará o zabezpečení. Používají speciální kódy a pravidla, aby měli jistotu, že váš kód budou mít přístup a měnit jenom ti správní lidé. Můžete také přidat další vrstvy zabezpečení, jako je dvoufaktorové ověřování, abyste měli větší bezpečnost.