Základy systémov Git a GitHub pre dokumentáciu Microsoft Learn

  • Článok

Prehľad

Ako prispievateľ do dokumentácie služby Microsoft Learn budete pracovať s viacerými nástrojmi a procesmi. Budete pracovať súčasne s ostatnými prispievateľmi na rovnakom projekte, potenciálne na úplne rovnakom obsahu a dokonca v rovnakom čase. To všetko umožňuje softvér Git a GitHub.

Git je systém správy verzie s otvoreným zdrojom. Uľahčuje projektovú spoluprácu tohto typu prostredníctvom distribuovanej správy verzie súborov, ktoré sú aktívne v odkladacích priestoroch. V podstate umožňuje systém Git integráciu práce vykonanej viacerými prispievateľmi v určitom časovom úseku pre dané odkladacie zariadenie.

GitHub je webová hostingová služba pre odkladacie priestory Git, ako sú tie, ktoré sa používajú na ukladanie obsahu služby Microsoft Learn . V akomkoľvek projekte GitHub hosťuje hlavný odkladací priestor, z ktorého prispievatelia môžu robiť kópie pre svoju prácu.

Tento článok definuje kľúčové výrazy, ktoré sú súčasťou pracovného postupu služby Microsoft Learn. Poskytuje tiež prehľad o odkladacích priestoroch Git a GitHub a vysvetľuje, ako je obsah usporiadaný pre technickú dokumentáciu spoločnosti Microsoft.

Pobočka

Vetvy oddeľujú pracovné streamy (zvyčajne označované ako verzie). Príspevky sa vždy vytvárajú a zameriavajú na konkrétnu vetvu.

Izolovanie súvisiacich zmien do konkrétnej vetvy umožňuje ovládať a zavádzať tieto zmeny nezávisle. V skutočnosti, v závislosti od typu práce, ktorú robíte, môžete ľahko skončiť vo svojom odkladacom priestore s niekoľkými pracovnými vetvami. Nie je nezvyčajné pracovať na viacerých vetvách naraz, pričom každá predstavuje iný projekt.

Všetky odkladacie priestory obsahujú predvolenú vetvu (zvyčajne s názvom "hlavná") a jednu alebo viac vetiev nedokončenej práce (ktoré nazývame pracovné vetvy), ktoré ešte neboli integrované do predvolenej vetvy. Predvolená vetva slúži ako aktuálna verzia a "jediný zdroj pravdy" pre projekt. Je rodičom, z ktorého sa vytvárajú všetky ostatné vetvy v odkladacom priestore.

Vždy, keď zavediete novú množinu logicky súvisiacich zmien, najlepšie je vytvoriť pracovnú vetvu na spravovanie zmien. Neodporúčame vykonávaním zmien v predvolenej vetve priamo.

Fork

Tento výraz sa zvyčajne používa ako podstatné meno, keď sa odkazuje na kópiu hlavného odkladacieho priestoru v službe GitHub. V praxi je vetva len ďalší odkladací priestor. Je však jedinečný v tom, že GitHub udržiava spojenie smerom späť do hlavného/nadradeného odkladacieho priestoru. Tento výraz sa niekedy používa ako sloveso, ako napríklad "Odkladací priestor musíte najskôr vetvenie."

Git

Ak poznáte centralizované verzia systémy správy verzií (napríklad Team Foundation Server, SharePoint alebo Visual Source Trezor), všimnete si, že Git má jedinečný pracovný postup prispievaia a terminológiu na podporu svojho distribuovaného modelu. Neexistuje napríklad žiadne uzamknutie súborov, ktoré by sa normálne spájali s operáciami check-out/check-in. Namiesto toho sa Git zaoberá zmenami na ešte jemnejšom úrovni a porovnáva súbory bajt po bajte.

Git tiež používa vrstvovú štruktúru na ukladanie a spravovanie obsahu pre projekt:

  • Odkladací priestor: Známy aj ako repo, ktorý predstavuje najvyššiu jednotku úložiska. Odkladací priestor obsahuje jednu alebo viac vetiev.
  • Vetva: Jednotka úložiska obsahujúca súbory a priečinky, ktoré tvoria obsahovú súpravu projektu. Ďalšie informácie o vetvách nájdete v časti Vetva tohto článku.

Prispievatelia komunikujú so systémom Git, aby aktualizovali a pracovali s odkladacími priestormi na lokálnej úrovni aj úrovní GitHub:

  • Lokálne prostredníctvom nástrojov, ako je konzola Git Bash, ktorá podporuje príkazy Git pre správu lokálnych odkladacích priestorov a komunikáciu s odkladacími priestormi služby GitHub.
  • Prostredníctvom lokality www.github.com, ktorá integruje Git na spravovanie zosúladenia príspevkov, ktoré tečú späť do hlavného odkladacieho priestoru.

GitHub

Poznámka

Hoci sprievodný materiál k dokumentácii je založený na používaní služby GitHub, niektoré tímy používajú Visual Studio Team Services na hosťovanie odkladacích priestorov Git. Klient Visual Studio Team Explorer poskytuje grafické používateľské rozhranie na komunikáciu s odkladacími priestormi Team Services ako alternatívu k používaniu príkazov Git prostredníctvom príkazového riadku.
Aj mnohé z nasledujúcich usmernení boli vyvinuté ako to najlepšie, čo sme si vytvorili počas rokov skúseností hosťovania obsahu služieb Azure v GitHube. Môžu sa vyžadovať v niektorých odkladacích priestoroch služby Microsoft Learn.

Všetky pracovné postupy začínajú a končia na úrovni GitHubu, kde je uložený hlavný odkladací priestor pre všetky dokumentačné projekty. Kópie vytvorené prispievateľom pre ich vlastnú potrebu sa distribuujú vo viacerých počítačoch. Tieto kópie sa po čase nakoniec dostali späť do hlavného odkladacieho priestoru GitHub.

Organizácia adresára

Predvolená vetva projektu slúži ako aktuálna verzia obsahu projektu. Obsah v predvolenej vetve a vetvách z nej vytvorených sa voľne zarovná s organizáciou článkov na príslušných stránkach služby Microsoft Learn. Podadresáre sa používajú na oddelenie, ako sú články (napríklad služby), mediálny obsah (napríklad obrázkové súbory) a súbory "patrí" (ktoré umožňujú opätovné použitie obsahu).

Podadresár článkov

Zvyčajne nájdete hlavný adresár articles mimo koreňa odkladacieho priestoru. Adresár articles obsahuje množinu podadresárov Články v podadresároch sú formátované ako súbory Markdown používajúce príponu .md . Niektoré odkladacie priestory podporujúce viacero služieb používajú generický /articles podadresár, ako napríklad odkladací priestor Azure-Docs. Iné môžu používať názov konkrétnej služby, napríklad odkladací priestor IntuneDocs, ktorý používa /IntuneDocs.

V koreni tohto adresára môžete nájsť všeobecné články, ktoré sa týkajú celkovej služby alebo produktu. Zvyčajne potom môžete nájsť ďalšiu sériu podadresárov, ktoré sa zhodujú s funkciami, službami alebo bežnými scenármi. Napríklad články o „virtuálnom zariadení“ Azure sú v podadresári /virtual-machines a články o „pochopení a preskúmaní“ Intune sú v podadresári /understand-explore.

Podadresár médií

Každý adresár článku obsahuje podadresár /media pre príslušné mediálne súbory. Mediálne súbory obsahujú obrázky použité v článkoch s obrazovými referenciami.

Zahŕňa podadresár

Vždy, keď je k dispozícii opätovne použiteľný obsah zdieľaný v rámci dvoch alebo viacerých článkov, umiestni sa v podadresári /includes mimo hlavného adresára articles. V súbore Markdown, ktorý používa zahrňujúci súbor sa príslušné „include“ rozšírenia Markdownu nachádza na mieste, na ktorom treba na zahrňujúci súbor odkazovať.

Pozrite si príručku jazyka Markdown: Zahrnutia pre ďalšie pokyny.

Súbor šablóny Markdown

Kvôli pohodliu zvyčajne obsahuje koreňový adresár každého odkladacieho priestoru zvyčajne súbor šablóny Markdown s názvom template.md. Tento súbor šablóny môžete použiť ako počiatočný súbor, ak potrebujete vytvoriť nový článok na odoslanie do odkladacieho priestoru. Súbor obsahuje:

  • Hlavičku s metaúdajmi v hornej časti súboru oddelenú dvoma trojpomĺčkovými čiarami. Obsahuje rôzne značky používané na sledovanie informácií týkajúcich sa článku. Metaúdaje článku povoľujú niektoré funkcie, napríklad označenie autora, označenie prispievateľa, odkazy a popisy článku. Zahŕňa aj optimalizáciu SEO a procesy vytvárania správ, ktoré Microsoft používa na vyhodnotenie výkonu obsahu. Preto sú metaúdaje dôležité!
  • Časť metaúdaje opisujúca rôzne značky a hodnoty metaúdajov. Ak si nie ste istí hodnotami, ktoré sa majú použiť v časti metaúdajov, môžete polia nechať prázdne alebo ich okomentovať s hashtagom (#) vpredu. Tak ich skontrolujú alebo dokončia posudzovatelia žiadosti o prijatie zmien pre odkladací priestor.
  • Rôzne príklady použitia Markdownu na formátovanie prvkov článku.
  • Všeobecný návod na použitie rozšírení Markdownu, ktoré môžete použiť pre rôzne typy upozornení.
  • Príklady vkladania videa pomocou iframe.
  • Všeobecné pokyny na použitie rozšírení technickej dokumentácie spoločnosti Microsoft, ktoré môžete použiť pre špeciálne ovládacie prvky, ako sú tlačidlá a selektory.

Počiatok

Tento výraz je názov priradený spojeniu medzi vaším lokálnym odkladacím priestorom a odkladacím priestorom, z ktorého bol klonovaný. V pracovnom postupe služby Microsoft Learn origin predstavuje pripojenie k vašej vetve. Tento výraz sa niekedy používa ako prezývka pre samotný pôvodný odkladací priestor, ako napríklad v časti "Nezabudnite zatlačiť svoje zmeny do pôvodu."

Žiadosti o prijatie zmien

Žiadosť o prijatie zmien je žiadosť o prijatie zmien, ktorá umožňuje vlastníkovi obsahu vyžiadať zmeny v oficiálnom zdroji. Pr umožňuje fungovanie modelu spolupráce v GitHube tým, že požiada, aby sa zmeny (známe aj ako záväzky) z vašej pracovnej vetvy vytiahli a zlúčili do inej vetvy. Vo väčšine prípadov je táto iná vetva predvolenou vetvou v hlavnom odkladacom priestore.

Žiadosť o prijatie zmien slúži aj ako mechanizmus na poskytnutie spätnej väzby prispievateľovi od overovacích procesov služby Microsoft Learn a posudzovateľa PR na riešenie problémov alebo otázok pred zlúčením zmien do predvolenej vetvy.

Vzdialenej

Vzdialené je pomenované pripojenie na vzdialený odkladací priestor, ako je napríklad vzdialený "origin" alebo "upstream". Git naň odkazuje ako na vzdialené, pretože sa používa na odkazovanie na odkladací priestor, ktorý je umiestnený v inom počítači. V pracovnom postupe služby Microsoft Learn je vzdialené úložisko vždy odkladací priestor GitHub.

Proti prúdu

Podobne ako vzdialený origin aj upstream je pomenované pripojenie do iného odkladacieho priestoru. V pracovnom postupe služby Microsoft Learn upstream predstavuje spojenie medzi vaším lokálnym odkladacím priestorom a hlavným odkladacím priestorom, z ktorého bola vytvorená vaša vetva. Tento výraz sa niekedy používa ako prezývka pre samotný upstreamový odkladací priestor, ako napríklad v časti "Nezabudnite vytiahnuť najnovšie zmeny z upstreamu."

Ďalšie informácie

Ak nepoznáte Git alebo GitHub, tieto zdroje vám môžu pomôcť pri zisťovaní, produktivite alebo odpovedať na otázky.

Zdroje na ovládanie zdrojového kódu Gitu

Zdroje GitHubu

Najčastejšie otázky týkajúce sa služby

Čo je Git?

Git pomáha sledovať zmeny, keď mnohí ľudia spoločne pracujú na kóde počítača. Je to ako časový počítač pre kód, takže si môžete pozrieť, čo sa zmenilo, a vrátiť sa v prípade potreby.

Prečo používať Git?

Je to skvelé pre tímovú prácu. Git uľahčuje mnohým ľuďom prácu na tom istom projekte bez toho, aby sa navzájom pokazili. Pomáha to tiež jednoducho opraviť chyby.

Ako funguje Git?

Git ukladá všetky verzie kódu projektu. Keď vykonáte zmeny, Git zhotí obrázok (napríklad snímku) toho, čo sa líši. Bez problémov môžete vytvárať rôzne verzie súčasne.

Čo sú vetvy v Git?

Vetvy sú ako rôzne cesty v projekte. Umožňujú ľuďom pracovať na nových veciach bez toho, aby zmenili hlavný projekt. Neskôr môžu tieto zmeny preniesť späť do hlavného projektu.

Čo je potvrdenie v Git?

Potvrdenie je ako bod uloženia. Je to spôsob, ako zaznamenať zmeny, ktoré ste vykonali. Každá potvrdiť má jedinečné ID a poznámku o tom, čo sa zmenilo.

Čo je GitHub?

GitHub je webová lokalita, kde môžete ukladať svoje projekty Git. Je to ako veľké centrum pre zdieľanie a spoluprácu na kóde s ostatnými. Pomáha tiež udržať prehľad o tom, čo čo zmenilo.

Ako sa GitHub líši od Git?

Git je nástroj na sledovanie zmien, zatiaľ čo GitHub je miesto na ukladanie projektov a spoluprácu. GitHub používa Git na to svoje kúzlo.

Je GitHub bezplatný?

Áno, pre projekty môže vidieť každý. V prípade súkromných projektov (len vy a váš tím) však možno budete musieť zaplatiť. Ponúka rôzne plány s ďalšími funkciami.

Čo sú žiadosti o prijatie zmien v službe GitHub?

Žiadosti o prijatie zmien sú ako požiadavka na vloženie zmien do hlavného projektu. Ľudia si môžu pred pridaním skontrolovať zmeny a diskutovať o ňom.

Ako bezpečné je GitHub?

GitHub sa stará o bezpečnosť. Používajú špeciálne kódy a pravidlá, aby sa uistili, že k vášmu kódu majú prístup a môžu ho meniť len správni ľudia. Môžete tiež pridať ďalšie vrstvy zabezpečenia, ako je dvojfaktorové overovanie, aby ste mali väčšiu bezpečnosť.