Git i GitHub essentials for Microsoft Learn documentation (Podstawy usług Git i GitHub dla dokumentacji środowiska Microsoft Learn)

  • Artykuł

Omówienie

Jako współautor dokumentacji usługi Microsoft Learn będziesz korzystać z wielu narzędzi i procesów. Będziesz pracować nad tym samym projektem równolegle z innymi współautorami — być może nad dokładnie tą samą zawartością, a nawet w tym samym czasie. Wszystko to jest możliwe dzięki usłudze Git i oprogramowaniu GitHub.

Usługa Git to system kontroli wersji typu open source. Umożliwia współpracę tego typu w ramach projektu dzięki rozproszonej kontroli wersji plików znajdujących się w repozytoriach. Usługa Git pozwala na integrowanie strumieni pracy wykonywanej przez różnych współautorów wraz z upływem czasu dla danego repozytorium.

GitHub to internetowa usługa hostingu dla repozytoriów Git, na przykład używana do przechowywania zawartości witryny Microsoft Learn . Dla każdego projektu w usłudze GitHub hostowane jest główne repozytorium, z poziomu którego współautorzy mogą wykonywać kopie na potrzeby własnej pracy.

W tym artykule zdefiniowano kluczowe terminy będące częścią przepływu pracy usługi Microsoft Learn. Zawiera również omówienie repozytoriów Git i GitHub oraz objaśnia sposób organizowania zawartości dla dokumentacji technicznej firmy Microsoft.

Oddział

Gałęzie rozdzielają strumienie pracy (zwykle określane jako wersje). Tworzone elementy są zawsze przygotowywane i dostosowywane pod kątem określonej gałęzi.

Izolowanie powiązanych zmian w określonej gałęzi umożliwia kontrolowanie i wprowadzanie tych zmian niezależnie. W praktyce w zależności od rodzaju wykonywanych prac może dojść do tego, że w repozytorium będzie kilka gałęzi roboczych. Praca nad wieloma gałęziami równocześnie nie należy do rzadkości, a wtedy każda z nich reprezentuje inny projekt.

Wszystkie repozytoria zawierają gałąź domyślną (zazwyczaj o nazwie "main") i co najmniej jedną gałąź pracy w toku (nazywane gałęziami roboczymi), które nie zostały jeszcze zintegrowane z gałęzią domyślną. Gałąź domyślna służy jako bieżąca wersja i "pojedyncze źródło prawdy" dla projektu. Jest to poziom nadrzędny, z którego tworzone są wszystkie inne gałęzie w repozytorium.

Za każdym razem, gdy wprowadzasz nowy zestaw logicznie powiązanych zmian, najlepszym rozwiązaniem jest utworzenie gałęzi roboczej do zarządzania zmianami. Nie zalecamy bezpośredniego wprowadzania zmian w gałęzi domyślnej.

Rozwidlenia

Ten termin jest zwykle używany jako ownik podczas odwoływania się do kopii głównego repozytorium GitHub. W praktyce rozwidlenie stanowi po prostu kolejne repozytorium. Jego cechą charakterystyczną jest to, że serwis GitHub zachowuje połączenie z repozytorium głównym/nadrzędnym. Ten termin jest czasami używany jako czasownik, jak w sekcji "Musisz najpierw rozwidlić repozytorium".

Usługa Git

Jeśli znasz scentralizowane systemy kontroli wersji (takie jak Team Foundation Server, SharePoint lub Visual Source Sejf), zauważysz, że usługa Git ma unikatowy przepływ pracy współtworzenia i terminologię do obsługi modelu rozproszonego. Na przykład nie ma blokady pliku, która jest zwykle skojarzona z operacjami wyewidencjonowania/ewidencjonowania. Zamiast tego usługa Git jest zaniepokojona zmianami na jeszcze bardziej precyzyjnym poziomie, porównując bajt bajtów plików.

Usługa Git używa również struktury warstwowej do przechowywania zawartości projektu i zarządzania nią:

  • Repozytorium — (w języku angielskim określane również jako repo) najwyższy poziom magazynu. Repozytorium zawiera co najmniej jedną gałąź.
  • Gałąź — jednostka magazynu, która zawiera pliki i foldery tworzące zestaw zawartości projektu. Aby uzyskać więcej informacji na temat gałęzi, zobacz sekcję Gałąź tego artykułu.

Współautorzy używają usługi Git do aktualizowania repozytoriów i manipulowania nimi lokalnie oraz na poziomie usługi GitHub:

  • W środowisku lokalnym za pośrednictwem narzędzi takich jak konsola Bash usługi Git, która obsługuje polecenia usługi Git służące do zarządzania repozytoriami lokalnymi i komunikowania się z repozytoriami usługi GitHub.
  • W witrynie www.github.com, która umożliwia integrowanie usługi Git w celu uzgadniania elementów tworzonych przez współautorów i przekazywanych z powrotem do głównego repozytorium.

GitHub

Uwaga

Chociaż wskazówki dotyczące dokumentacji są oparte na korzystaniu z usługi GitHub, niektóre zespoły używają usług Visual Studio Team Services do hostowania repozytoriów Git. Klient programu Visual Studio Team Explorer oferuje graficzny interfejs użytkownika na potrzeby interakcji z repozytoriami usługi Team Services, co jest alternatywą do korzystania z poleceń usługi Git w wierszu polecenia.
Ponadto wiele z poniższych wytycznych zostało opracowanych jako najlepsze rozwiązania od lat w zakresie hostowania zawartości usługi platformy Azure w usłudze GitHub. Mogą one być wymagane w niektórych repozytoriach Microsoft Learn.

Wszystkie przepływy pracy rozpoczynają się i kończą na poziomie usługi GitHub, gdzie przechowywane jest główne repozytorium dla dowolnego projektu dokumentacji. Kopie tworzone przez współautorów do własnego użytku są dystrybuowane na wiele komputerów. Te kopie są ostatecznie uzgadniane z głównym repozytorium projektu w usłudze GitHub.

Organizacja katalogów

Domyślna gałąź projektu służy jako bieżąca wersja zawartości projektu. Zawartość w domyślnych gałęziach i gałęziach utworzonych na jej podstawie jest luźno zgodna z organizacją artykułów na odpowiednich stronach witryny Microsoft Learn. Podkatalogi są używane do oddzielania takich artykułów jak artykuły (takie jak usługi), zawartość multimediów (np. pliki obrazów) i pliki "include" (które umożliwiają ponowne użycie zawartości).

Podkatalog artykułów

Zwykle katalog główny articles znajduje się poza katalogiem głównym repozytorium. Katalog articles zawiera zestaw podkatalogów Artykuły w podkatalogach są formatowane jako pliki Markdown, które używają rozszerzenia md . Niektóre repozytoria, które obsługują wiele usług, korzystają z ogólnego podkatalogu /articles. Tak jest na przykład w przypadku repozytorium Azure-Docs. Inne mogą używać nazwy powiązanej z usługą, takiej jak repozytorium IntuneDocs, które korzysta z katalogu /IntuneDocs.

W katalogu głównym tego katalogu można znaleźć ogólne artykuły dotyczące usługi lub produktu jako całości. Przeważnie można potem przejść do innego zestawu podkatalogów odpowiadających funkcjom/usługom lub typowym scenariuszom. Na przykład artykuły typu „maszyna wirtualna” platformy Azure znajdują się w podkatalogu /virtual-machines, artykuły typu „poznawanie i eksplorowanie” dotyczące usługi Intune — w podkatalogu /understand-explore.

Podkatalog plików multimedialnych

Każdy katalog artykułów zawiera podkatalog /media przeznaczony na odpowiednie pliki multimedialne. Pliki multimedialne zawierają obrazy używane przez artykuły z odwołaniami do obrazów.

Podkatalog dołączania

Każda zawartość do wielokrotnego użytku udostępniana w co najmniej dwóch artykułach jest umieszczana w podkatalogu /includes katalogu poza głównym katalogiem articles. W pliku Markdown, w którym używany jest dołączony plik, odpowiednie rozszerzenie „include” języka znaczników Markdown jest umieszczane w lokalizacji, w której ma nastąpić odwołanie do tego pliku.

Zobacz Dokumentacja języka Markdown: zawiera dodatkowe wskazówki.

Szablon pliku markdown

Dla wygody katalog główny każdego repozytorium zwykle zawiera plik szablonu Markdown o nazwie template.md. Z tego pliku szablonu można korzystać jak z „pliku startowego”, gdy konieczne jest utworzenie nowego artykułu do przesłania do repozytorium. Plik zawiera:

  • Nagłówek metadanych u góry, który jest oddzielony dwiema liniami złożonymi z 3 łączników. Zawiera różne tagi używane do śledzenia informacji dotyczących konkretnego artykułu. Metadane artykułu dają dostęp do pewnych funkcji, takich jak przypisanie autora, przypisanie współautora, ścieżka nawigacyjna i opisy artykułu. Zawiera również optymalizacje SEO i procesy raportowania używane przez firmę Microsoft do oceny wydajności zawartości. Dlatego metadane są ważne.
  • Sekcję metadanych opisującą różne tagi i wartości metadanych. Jeśli nie masz pewności co do wartości do użycia w sekcji metadanych, możesz pozostawić je puste lub dodać do nich komentarz z hasztagiem (#) na początku. Wartości te zostaną przejrzane/uzupełnione przez recenzenta żądania ściągnięcia w repozytorium.
  • Różne przykłady użycia języka znaczników Markdown w celu formatowania elementów artykułu.
  • Ogólne instrukcje stosowania rozszerzeń języka znaczników Markdown, których można używać w przypadku różnych typów alertów.
  • Przykłady osadzania wideo przy użyciu elementu iframe.
  • Ogólne instrukcje dotyczące korzystania z rozszerzeń dokumentacji technicznej firmy Microsoft, których można używać do specjalnych kontrolek, takich jak przyciski i selektory.

Pochodzenie

Ten termin to nazwa przypisana do połączenia między repozytorium lokalnym a repozytorium, z którego została sklonowana. W przepływie pracy usługi Microsoft Learn źródło reprezentuje połączenie z rozwidleniu. Ten termin jest czasami używany jako pseudonim dla samego repozytorium pochodzenia, jak w sekcji "Pamiętaj, aby wypchnąć zmiany do źródła".

Żądania ściągnięcia

Żądanie ściągnięcia to żądanie ściągnięcia dla właściciela zawartości w celu ściągnięcia zmian do oficjalnego źródła. Żądanie ściągnięcia umożliwia model współpracy usługi GitHub, prosząc o zmiany (znane również jako zatwierdzenia) z gałęzi roboczej, które mają zostać ściągnięte i scalone z inną gałęzią. W większości przypadków ta inna gałąź jest gałęzią domyślną w repozytorium głównym.

Żądanie ściągnięcia służy również jako mechanizm przekazywania współautorowi opinii z procesów weryfikacji środowiska Microsoft Learn oraz recenzenta żądania ściągnięcia w celu rozwiązania problemów lub pytań przed scaleniem zmian z gałęzią domyślną.

Zdalnie

Zdalne jest nazwanym połączeniem z repozytorium zdalnym, takim jak zdalne "źródło" lub "nadrzędne". Usługa Git odwołuje się do tego jako zdalne, ponieważ jest używana do odwoływania się do repozytorium hostowanego na innym komputerze. W przepływie pracy usługi Microsoft Learn zdalne jest zawsze repozytorium GitHub.

W górę

Podobnie jak zdalne źródło, nadrzędne połączenie jest nazwanym połączeniem z innym repozytorium. W przepływie pracy usługi Microsoft Learn nadrzędny reprezentuje połączenie między repozytorium lokalnym a repozytorium głównym, z którego utworzono rozwidlenie. Ten termin jest czasami używany jako pseudonim dla samego repozytorium nadrzędnego, jak w temacie "Pamiętaj, aby ściągnąć najnowsze zmiany z nadrzędnego strumienia".

Dowiedz się więcej

Jeśli nie znasz usługi Git lub GitHub, te zasoby mogą ułatwić naukę, produktywność lub odpowiadanie na pytania.

Zasoby kontroli źródła usługi Git

Zasoby usługi GitHub

  • Ćwiczenie szybkiego startu Hello World w usłudze GitHub: samouczek online, który uwidacznia Podstawowe informacje o usłudze GitHub przy użyciu usługi GitHub.
  • Przewodniki GitHub: główna część dokumentacji usługi GitHub.
  • Zasoby szkoleniowe usługi GitHub: inne przydatne zasoby dotyczące usługi GitHub.
  • Słownik: przydatny słownik terminów git i GitHub.
  • Pakiet deweloperski dla uczniów usługi GitHub: bezpłatny dostęp do najlepszych narzędzi deweloperskich dla uczniów.

Często zadawane pytania

Co to jest usługa Git?

Usługa Git pomaga śledzić zmiany, gdy wiele osób pracuje razem w kodzie komputera. Jest to jak maszyna czasowa dla kodu, dzięki czemu możesz zobaczyć, co się zmieniło i w razie potrzeby wrócić.

Dlaczego warto używać usługi Git?

Doskonale nadaje się do pracy zespołowej. Usługa Git ułatwia wielu osobom pracę nad tym samym projektem bez bałaganu nad pracą nawzajem. Pomaga również łatwo naprawić błędy.

Jak działa usługa Git?

Usługa Git przechowuje wszystkie wersje kodu projektu. Po wprowadzeniu zmian usługa Git tworzy obraz (na przykład migawkę) różnych elementów. Różne wersje można tworzyć w tym samym czasie bez problemu.

Co to są gałęzie w usłudze Git?

Gałęzie są podobne do różnych ścieżek w projekcie. Pozwalają ludziom pracować nad nowymi rzeczami bez zmiany głównego projektu. Później mogą przywrócić te zmiany do głównego projektu.

Co to jest zatwierdzenie w usłudze Git?

Zatwierdzenie jest jak punkt zapisywania. Jest to sposób rejestrowania wprowadzonych zmian. Każde zatwierdzenie ma unikatowy identyfikator i notatkę o tym, co zostało zmienione.

Co to jest GitHub?

GitHub to witryna internetowa, w której można przechowywać projekty Git. Jest to jak duże centrum do udostępniania i współpracy nad kodem z innymi osobami. Pomaga również śledzić, kto zmienił to, co.

Czym różni się usługa GitHub od usługi Git?

Usługa Git to narzędzie do śledzenia zmian, a usługa GitHub to miejsce do przechowywania projektów i współpracy. Usługa GitHub używa usługi Git do wykonywania swojej magii.

Czy usługa GitHub jest bezpłatna?

Tak, w przypadku projektów każdy może zobaczyć. Jednak w przypadku projektów prywatnych (tylko Ty i Twój zespół) może być konieczne zapłacenie. Oferują różne plany z dodatkowymi funkcjami.

Co to są żądania ściągnięcia w usłudze GitHub?

Żądania ściągnięcia przypominają prośbę o wprowadzenie zmian do głównego projektu. Osoby można przejrzeć i omówić zmiany przed ich dodaniu.

Jak bezpieczne jest github?

Usługa GitHub dobrze dba o bezpieczeństwo. Używają specjalnych kodów i reguł, aby upewnić się, że tylko odpowiednie osoby mogą uzyskiwać dostęp do kodu i zmieniać go. Możesz również dodać dodatkowe warstwy zabezpieczeń, takie jak uwierzytelnianie dwuskładnikowe, aby uzyskać więcej bezpieczeństwa.