Przepływ pracy dotyczący współtworzenia dokumentacji w usłudze GitHub: istotne lub długotrwałe zmiany

Ważne

W przypadku wszystkich repozytoriów publikowanych w witrynie docs.microsoft.com stosowany jest Kodeks postępowania firmy Microsoft dotyczący rozwiązań typu open source lub Kodeks postępowania organizacji .NET Foundation. Aby uzyskać więcej informacji, zobacz często zadawane pytania dotyczące kodu postępowania. W przypadku pytań lub komentarzy możesz też napisać na adres opencode@microsoft.com lub conduct@dotnetfoundation.org.

Drobne poprawki lub wyjaśnienia dotyczące dokumentacji i przykładów kodu w repozytoriach publicznych znajdują się w Warunkach korzystania z witryny docs.microsoft.com. Nowe lub ważne zmiany spowodują wygenerowanie komentarza w żądaniu ściągnięcia z prośbą o przesłanie internetowej umowy licencyjnej współautorstwa (CLA), jeśli nie jesteś pracownikiem firmy Microsoft. Zanim scalimy żądanie ściągnięcia, musisz wypełnić formularz online.

Omówienie

Ten przepływ pracy jest przeznaczony dla współautorów, którzy muszą wprowadzić istotne zmiany lub będą często tworzyć dokumentację w repozytorium. Współautorzy, którzy często tworzą dokumentację, zwykle dokonują trwałych lub długookresowych zmian, które przechodzą wiele cykli kompilacji, weryfikacji i przemieszczania lub trwają wiele dni przed wyrejestrowaniem i scaleniem żądania ściągnięcia.

Przykłady tego typu zmian to:

  • Wprowadzenie wielu zmian. Przykładowo można wprowadzać zmiany zawartości (dodawania, modyfikowania lub usuwania) obejmujące wiele artykułów, które muszą zostać zatwierdzone i przetestowane jako jedna jednostka pracy w ramach jednego żądania ściągnięcia.
  • Utworzenie i opublikowanie nowego artykułu, co zwykle wymaga bardziej zaawansowanego edytora lokalnego.
  • Dodanie nowych obrazów lub zaktualizowanie obrazów, co zwykle wymaga jednoczesnego utworzenia nowego podkatalogu media, plików obrazów, aktualizacji linków obrazów w artykułach i wyświetlenia podglądu plików markdown w edytorze lokalnym w celu przetestowania renderowania obrazu.
  • Aktualizowanie artykułu przez wiele dni przed opublikowaniem. W takich przypadkach zazwyczaj trzeba regularnie integrować inne zmiany występujące w gałęzi domyślnej. Jest to łatwiejsze w przypadku powłoki Git Bash i edytowania lokalnego. Używanie w tym celu interfejsu użytkownika usługi GitHub wiąże się też z ryzykiem utraty zmian podczas oczekiwania na zatwierdzenie zmian.
  • Ciągłe aktualizowanie tego samego artykułu po otwarciu żądania ściągnięcia (jeśli zrobienie tego przy użyciu interfejsu użytkownika usługi GitHub stanowi problem). Interfejs użytkownika usługi GitHub umożliwia utworzenie wielu osobnych żądań ściągnięcia dla tego samego pliku, co może powodować konflikty między żądaniami.

Terminologia

Zanim rozpoczniemy, omówmy niektóre terminy i krótkie nazwy dotyczące systemu Git i serwisu GitHub użyte w tym przepływie pracy. Nie musisz czytać o nich teraz. Wystarczy wiedzieć, że są tu na ich temat informacje i można odwołać się do tej sekcji, jeśli trzeba będzie zweryfikować jakąś definicję.

Nazwa Opis
rozwidlenie Zwykle pojęcie to jest używane w formie rzeczownika i oznacza kopię głównego repozytorium w serwisie 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. Pojęcie to jest czasami używane w formie czasownika, np. w komunikacie „You must fork the repository first” („Musisz najpierw utworzyć rozwidlenie repozytorium”).
połączenie zdalne Nazwane połączenie z repozytorium zdalnym, np. połączenie zdalne „pierwotne” lub „nadrzędne”. W usłudze Git takie połączenia są nazywane połączeniami zdalnymi, ponieważ służą do odwoływania się do repozytorium hostowanego na innym komputerze. W tym przepływie połączenie zdalne jest zawsze połączeniem z repozytorium w serwisie GitHub.
połączenie pierwotne Nazwa przypisana do połączenia między repozytorium lokalnym a repozytorium, z którego zostało ono sklonowane. W tym przepływie połączenie pierwotne stanowi połączenie z rozwidleniem. Czasami służy jako krótka nazwa samego repozytorium origin, jak w przypadku komunikatu „Remember to push your changes to origin” (Pamiętaj, aby przekazać zmiany do repozytorium origin).
połączenie nadrzędne Tak jak połączenie zdalne pierwotne połączenie nadrzędne jest nazwanym połączeniem z innym repozytorium. W tym przepływie pracy połączenie nadrzędne stanowi połączenie między repozytorium lokalnym i repozytorium głównym, z którego zostało utworzone rozwidlenie. Czasami służy jako krótka nazwa samego repozytorium upstream, jak w przypadku komunikatu „Remember to pull the changes from upstream” (Pamiętaj, aby ściągać zmiany z repozytorium upstream).

Przepływ pracy

Ważne

Należy wykonać czynności w sekcji Konfiguracja, jeśli jeszcze nie zostały wykonane. Ta sekcja zawiera instrukcje konfigurowania konta w usłudze GitHub, instalowania powłoki Git Bash oraz edytora języka Markdown, tworzenia rozwidlenia oraz konfigurowania repozytorium lokalnego. Jeśli nie znasz pojęć dotyczących usług Git i GitHub, takich jak repozytorium lub gałąź, przejrzyj najpierw artykuł Git and GitHub fundamentals (Podstawy usług Git i GitHub).

W tym przepływie pracy zmiany odbywają się w powtarzających się cyklach. Zaczynając od lokalnego repozytorium urządzenia, są przesyłane z powrotem do rozwidlenia w serwisie GitHub, do repozytorium głównego serwisu GitHub i znowu z powrotem lokalnie podczas wdrażania zmian innych współautorów.

Stosowanie przepływu usługi GitHub

Przypomnij sobie z repozytorium Git i GitHub podstawy, że repozytorium Git zawiera gałąź domyślną oraz wszelkie dodatkowe gałęzie pracy w toku, które nie zostały zintegrowane z gałęzią domyślną. Gdy wprowadzasz zestaw logicznie powiązanych zmian, najlepszym rozwiązaniem jest utworzenie gałęzi roboczej do zarządzania zmianami przy użyciu przepływu pracy. W tym miejscu nazywamy ją gałęzią roboczą, ponieważ jest to obszar roboczy służący do iterowania/uściślinia zmian, dopóki nie będzie można ich ponownie zintegrować z gałęzią domyślną.

Wyizolowanie powiązanych zmian do określonej gałęzi umożliwia kontrolowanie i wprowadzanie tych zmian niezależnie oraz przeznaczanie ich na określony czas wydania w cyklu publikowania. 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.

Porada

Wprowadzanie zmian w gałęzi domyślnej nie jest dobrym rozwiązaniem. Imagine, że używasz gałęzi domyślnej, aby wprowadzić zestaw zmian na czas wydania funkcji. Dokonaliśmy zmian i czekamy na ich wydanie. Następnie w międzyczasie masz pilne żądanie naprawienia czegoś, więc wprowadzasz zmianę do pliku w gałęzi domyślnej, a następnie publikujesz zmianę. W tym przykładzie opublikowaliśmy nieumyślnie zarówno poprawkę, jak i zmiany zachowane do wydania określonego dnia.

Teraz utworzymy nową gałąź roboczą w lokalnym repozytorium, aby przechwycić proponowane zmiany. Jeśli skonfigurowano powłokę Git Bash (zobacz Instalowanie narzędzi do tworzenia zawartości), możesz utworzyć nową gałąź i wyewidencjonować ją przy użyciu jednego polecenia z poziomu sklonowanego repozytorium:

git checkout -b "branchname"

Każdy klient usługi Git jest inny, dlatego należy korzystać z pomocy dotyczącej preferowanego klienta. Omówienie procesu można zobaczyć w przewodniku usługi GitHub w artykule GitHub flow (Przepływ usługi GitHub).

Wprowadzanie zmian

Teraz, gdy masz kopię („klona”) repozytorium Microsoft i utworzoną gałąź, możesz wprowadzić dowolne zmiany, które według Ciebie będą korzystne dla społeczności, korzystając z dowolnego edytora tekstu lub języka Markdown, zgodnie z informacjami na stronie Instalowanie narzędzi do tworzenia zawartości. Zmiany możesz zapisywać lokalnie. Nie ma konieczności przesyłania ich do firmy Microsoft, dopóki nie będą całkowicie gotowe.

Zapisywanie zmian w repozytorium

Przed wysłaniem zmian do autora musisz najpierw zapisać je w swoim repozytorium GitHub. W każdym narzędziu odbywa się to inaczej, ale jeśli używasz wiersza polecenia Git Bash, wystarczy wykonać kilka prostych kroków.

Najpierw z poziomu repozytorium należy przygotować wszystkie zmiany w ramach następnego zatwierdzenia. W tym celu należy wykonać następujące polecenie:

git add --all

Następnie musisz zatwierdzić zapisane zmiany w lokalnym repozytorium. To zadanie można wykonać w powłoce Git Bash, wykonując polecenie:

git commit -m "Short Description of Changes Made"

Na koniec, ponieważ ta gałąź została utworzona na komputerze lokalnym, musisz wysłać informacje o niej do rozwidlenia na koncie GitHub.com. Jeśli używasz powłoki Git Bash, możesz to zrobić, wykonując polecenie:

git push --set-upstream origin <branchname>

Gotowe! Kod znajduje się teraz w repozytorium GitHub i można dla niego utworzyć żądanie ściągnięcia.

Porada

Chociaż po wypchnięciu zmiany staną się widoczne na osobistym koncie usługi GitHub, nie ma reguły nakazującej natychmiastowe przesłanie żądania ściągnięcia. Jeśli chcesz przerwać pracę i wrócić do niej później, aby wprowadzić drobne zmiany, możesz to zrobić.

Chcesz poprawić przesłaną zawartość? Żaden problem. Po prostu wprowadź zmiany w tej samej gałęzi, a następnie jeszcze raz zatwierdź je i wypchnij (w przypadku kolejnych operacji wypychania w ramach tej samej gałęzi nie trzeba ustawiać serwera połączenia nadrzędnego).

Wprowadzanie następnej zmiany

Chcesz wprowadzić inne zmiany, które nie są powiązane z tymi? Wróć do gałęzi domyślnej, pobierz z repozytorium nadrzędnego, aby upewnić się, że rozwidlenie jest aktualne, i wyewidencjonuj nową gałąź. Uruchom następujące polecenia w aplikacji Git Bash:

git checkout main
git pull upstream main
git checkout -b "branchname"

Uwaga

Powyższe polecenia zakładają, że repozytorium, z którym pracujesz, ma main domyślną gałąź. Jeśli pierwsze polecenie zakończy się niepowodzeniem, prawdopodobnie nie zmieniono nazwy gałęzi domyślnej. Zastąp main element w dwóch pierwszych poleceniach , master aby to sprawdzić.

Jesteś teraz z powrotem w nowej gałęzi i jesteś w drodze do bycia ekspertem współtworzem.

Przetwarzanie żądania ściągnięcia

W poprzedniej sekcji omówiono proces przesyłania proponowanych zmian przez umieszczenie ich w pakiecie w nowym żądaniu ściągnięcia dodawanym do kolejki żądań ściągnięcia repozytorium docelowego. Żądanie ściągnięcia włącza model współpracy usługi GitHub przez zażądanie ściągnięcia zmian z gałęzi roboczej i scalenia ich z inną gałęzią. W większości przypadków inna gałąź jest domyślną gałęzią w repozytorium głównym.

Walidacja

Zanim żądanie ściągnięcia będzie mogło zostać scalone z gałęzią docelową, może być konieczne jego przejście przez jeden lub więcej procesów weryfikowania żądań ściągnięcia. Procesy weryfikowania mogą się różnić zależnie od zakresu proponowanych zmian i reguły repozytorium docelowego. Po przesłaniu żądania ściągnięcia mogą zostać przeprowadzone następujące testy:

  • Scalanie: najpierw występuje test linii bazowej GitHub scalania, aby sprawdzić, czy proponowane zmiany w gałęzi nie są sprzeczne z gałęzią docelową. Jeśli żądanie ściągnięcia nie przejdzie pomyślnie tego testu, będzie konieczne usunięcie zawartości powodującej konflikt scalania, aby można było kontynuować przetwarzanie.
  • Umowa licencyjna udziału: jeśli współtworzysz zawartość w repozytorium publicznym i nie jesteś pracownikiem firmy Microsoft, przy pierwszej próbie przesłania żądania ściągnięcia do tego repozytorium może być konieczne wypełnienie krótkiej umowy licencyjnej udziału. Żądanie ściągnięcia zostanie przetworzone po wykonaniu kroku z umową licencyjną udziału.
  • Tworzenie etykiet: do żądania ściągnięcia są automatycznie stosowane etykiety, które wskazują stan żądania przekazywanego w ramach przepływu pracy weryfikacji. Na przykład do nowych żądań ściągnięcia może być automatycznie stosowana etykieta wskazująca brak możliwości scalenia z powodu nieukończonego procesu weryfikacji, przeglądu i akceptacji.
  • Weryfikacja i kompilacja: zautomatyzowane kontrole sprawdzają, czy zmiany przeszły testy weryfikacyjne. Testy weryfikacyjne mogą zwracać ostrzeżenia lub błędy, które wymagają wprowadzenia zmian w co najmniej jednym pliku w żądaniu ściągnięcia przed scaleniem. Wyniki testów weryfikacyjnych są dodawane do żądania ściągnięcia jako komentarz, który możesz przejrzeć, i mogą zostać wysłane pocztą e-mail.
  • Przygotowywanie: strony artykułów, których dotyczą zmiany, mogą zostać automatycznie wdrożone w środowisku przygotowawczym na potrzeby przeglądu po pomyślnej weryfikacji i kompilacji. Adresy URL podglądu są udostępniane w komentarzu do żądania ściągnięcia.
  • Automatyczne scalanie: żądanie ściągnięcia może zostać automatycznie scalone, jeśli pomyślnie przejdzie testy weryfikacyjne i spełni określone kryteria. W takim przypadku nie trzeba podejmować żadnych dalszych akcji.

Przegląd i akceptacja

Po zakończeniu całego procesu przetwarzania żądania ściągnięcia przejrzyj wyniki (komentarze do żądania, adresy URL podglądu itp.), aby ustalić, czy przed jego zaakceptowaniem lub scaleniem należy wprowadzić dodatkowe zmiany w jego plikach. Jeśli żądanie ściągnięcia zostało przejrzane przez recenzenta, mógł on dodać komentarze z informacją o problemach do rozwiązania lub pytaniami wymagającymi odpowiedzi przed scaleniem.

Automatyzacja komentarza umożliwia użytkownikom mającym poziom uprawnień do odczytu (użytkownikom, którzy nie mają uprawnień do zapisu w repozytorium) wykonanie akcji na poziomie uprawnień do zapisu dzięki przypisaniu odpowiedniej etykiety do żądania ściągnięcia. Jeśli pracujesz w repozytorium, w którym zaimplementowano automatyzację komentarza, użyj komentarzy z hasztagami wymienionych w poniższej tabeli, aby przypisać etykiety, etykiety zmiany lub zamknąć żądanie ściągnięcia. Pracownicy firmy Microsoft również zostaną powiadomieni pocztą e-mail o sprawdzeniu i zaakceptowaniu żądań ściągnięcia publicznego repozytorium zawsze, gdy dla artykułów Twojego autorstwa zostaną zaproponowane zmiany.

Komentarz z hasztagiem Wyniki działania Dostępność repozytorium
#sign-off Gdy autor artykułu wpisze komentarz #sign-off w strumieniu komentarza, zostanie przypisana etykieta gotowe do scalenia. Ta etykieta umożliwia recenzentom w repozytorium dowiedzenie się, kiedy żądanie ściągnięcia jest gotowe do przeglądu/scalenia.

Jeśli współautor, który nie jest wymienionym autorem, spróbuje zaakceptować publiczne żądanie ściągnięcia za pomocą komentarza #sign-off, zostanie napisany komunikat do żądania ściągnięcia wskazujący, że tylko autor może przypisać etykietę.
Publiczne i prywatne
#hold-off Autorzy mogą wpisać #hold-off w komentarzu do żądania ściągnięcia, aby usunąć etykietę gotowe do scalenia — w przypadku zmiany zdania lub popełnienia błędu. W prywatnym repozytorium powoduje to przypisanie etykiety nie scalaj. Publiczne i prywatne
#please-close Autorzy mogą wpisać #please-close w strumieniu komentarza, aby zamknąć żądanie ściągnięcia, jeśli postanowią nie scalać zmian. Publiczne

Po rozwiązaniu problemów i zaakceptowaniu żądania ściągnięcia zmiany są scalane z powrotem z gałęzią nadrzędną, a żądanie ściągnięcia jest zamykane.

Publikowanie

Żądanie ściągnięcia musi zostać scalone przez recenzenta żądania, aby zmiany mogły zostać uwzględnione w następnym zaplanowanym przebiegu publikowania. Żądania ściągnięcia są zwykle przeglądane/scalane w takiej kolejności, w jakiej zostały przesłane. Jeśli żądanie ściągnięcia wymaga scalenia w ramach określonego przebiegu publikowania, skontaktuj się wcześniej z recenzentem żądania, aby upewnić się, że scalanie zostanie przeprowadzone przed publikowaniem.

Zatwierdzone i scalone zmiany są pobierane w ramach procesu publikowania w witrynie docs.microsoft.com. Czas publikowania różni się w zależności od zespołu zarządzającego repozytorium, w którym wprowadzasz zmiany. Artykuły opublikowane na poniższych stronach są zwykle wdrażane od poniedziałku do piątku ok. 10:30 i 15:30 czasu pacyficznego:

Artykuły mogą zostać wyświetlone online do 45 minut po opublikowaniu. Po opublikowaniu artykułu możesz sprawdzić zmiany, używając odpowiedniego adresu URL: https://docs.microsoft.com/<path-to-your-article-without-the-md-extension>.

Następne kroki

Gotowe. Tworzenie zawartości w witrynie docs.microsoft.com zostało zakończone.