Wprowadzanie istotnych zmian w dokumentacji platformy Microsoft Learn

Ważne

Wszystkie repozytoria, które publikują w usłudze Microsoft Learn, przyjęły kodeks postępowania firmy Microsoft typu open source lub kodeks postępowania programu .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 są objęte learn.microsoft.com Warunki użytkowania. Wszelkie zmiany wygenerują komentarz w żądaniu ściągnięcia z prośbą o przesłanie umowy licencyjnej udziału online (CLA), jeśli nie jesteś pracownikiem firmy Microsoft. Zanim scalimy żądanie ściągnięcia, musisz wypełnić formularz online.

W tym artykule pokazano, jak zmienić artykuł w witrynie Microsoft Learn przy użyciu lokalnych narzędzi i jest odpowiedni dla współautora, który musi wprowadzić ważną zmianę lub będzie częstym współautorem repozytorium. Często współautorzy zwykle mają trwające lub długotrwałe zmiany, które przechodzą przez wiele cykli kompilacji/weryfikacji/przemieszczania lub obejmują wiele dni przed zalogowaniem się do żądania ściągnięcia (PR).

Przykłady tego typu zmian to:

• Wprowadzenie wielu zmian. Na przykład twoje współtworzenie (dodatki, zmiany lub usunięcia) może obejmować wiele artykułów i muszą zostać zatwierdzone i przetestowane jako jedna jednostka pracy w jednym żądaniu ściągnięcia.
• Utworzenie i opublikowanie nowego artykułu, co zwykle wymaga bardziej zaawansowanego edytora lokalnego.
• Dodawanie nowych obrazów lub aktualizowanie obrazów, co zwykle wymaga jednoczesnego utworzenia nowego media podkatalogu, utworzenia plików obrazów, zaktualizowania linków do obrazów w artykułach i podglądu plików Markdown w edytorze lokalnym w celu przetestowania renderowania obrazów.
• Aktualizowanie artykułu przez wiele dni przed opublikowaniem. W takich przypadkach zazwyczaj należy regularnie integrować inne zmiany występujące w gałęzi domyślnej. Jest to łatwiejsze w przypadku powłoki Git Bash i edytowania lokalnego. Jeśli to zrobisz za pośrednictwem edytora internetowego usługi GitHub, możesz również uruchomić ryzyko utraty zmian i poczekać przed zatwierdzeniem zmian.
• Ciągłe aktualizowanie tego samego artykułu po otwarciu żądania ściągnięcia. Mimo że w tym celu możesz użyć edytora internetowego Usługi GitHub, możesz utworzyć wiele zaległych żądania ściągnięcia dla tego samego pliku, co może powodować konflikt ze sobą.

Wymagania wstępne

• Zidentyfikuj repozytorium GitHub, które przechowuje dokumentację, którą chcesz edytować.
• Utwórz konto usługi GitHub, jeśli go nie masz.
• Zainstaluj narzędzia Git i Markdown.
• Konfigurowanie lokalnego repozytorium Git.
• Zapoznaj się z podstawami usług Git i GitHub (opcjonalnie).

Tworzenie i wyewidencjonowywanie gałęzi roboczej

Aby rozpocząć, utwórz nową gałąź roboczą w repozytorium lokalnym, aby przechwycić proponowane zmiany. Aby uzyskać więcej informacji na temat gałęzi, zobacz Podstawy usług Git i GitHub.

W tym samouczku jest używana powłoka Git Bash i program Visual Studio Code, ale możesz użyć dowolnego preferowanego klienta i edytora Git.

1. W programie VS Code otwórz folder repozytorium lokalnego klonu. W menu Plik wybierz pozycję Otwórz folder i przejdź do folderu na maszynie.

2. Wybierz pozycję Widok w górnym menu, a następnie wybierz pozycję Terminal , aby otworzyć zintegrowany terminal.

3. W zintegrowanym terminalu upewnij się, że jesteś w folderze repozytorium.

4. Przed utworzeniem gałęzi roboczej upewnij się, że lokalna gałąź główna jest bieżąca ze wszystkimi elementami w głównej gałęzi repozytorium produkcyjnego. To zadanie zapewnia, że gałąź robocza przechwytuje wszelkie zmiany, które wystąpiły w repozytorium produkcyjnym od czasu ostatniej synchronizacji z nim.

   1. Przejdź do gałęzi głównej w repozytorium lokalnym:

      git checkout main 
      

   2. Upewnij się, że lokalna gałąź główna jest bieżąca:

      git pull upstream main 
      

5. Utwórz lokalną gałąź roboczą na podstawie głównej:

   git checkout -b <branch-name>
   

   <branch-name> jest symbolem zastępczym. Po uruchomieniu polecenia zastąp go unikatową i zrozumiałą nazwą gałęzi i usuń nawiasy kątowe.

6. Wypchnij lokalną gałąź roboczą do gałęzi zdalnej w rozwidleniu usługi GitHub:

   git push origin <branch-name> -u
   

   Opcja -u łączy lokalne i zdalne gałęzie. Ta opcja umożliwia wypychanie zatwierdzeń do rozwidlenia przez wprowadzenie tylko git push zamiast git push origin <branch-name>.

Znajdowanie źródłowego pliku Markdown

Aby edytować artykuł, znajdź plik źródłowy artykułu w klonie repozytorium lokalnego. W programie VS Code uzyskaj dostęp do plików Markdown repozytorium za pośrednictwem Eksploratora plików (ikona dokumentu na lewym górnym pasku bocznym). W Eksploratorze plików jest wyświetlana struktura folderów repozytorium i możesz przejść do pliku, który chcesz edytować.

Jeśli nie możesz znaleźć pliku, odwiedź artykuł w witrynie Microsoft Learn i wybierz ikonę ołówka Edytuj . Lokalizacja folderu względnego w repozytorium GitHub jest wyświetlana w adresie URL. Oto przykładowy adres URL linku do edycji :

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

Oto przykładowa lokalizacja pliku dla tego adresu URL.

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

Edytowanie pliku

1. Otwórz plik w programie VS Code, wybierając go.
2. Wprowadź zmiany.
3. Zapisz zmiany, wybierając pozycję Zapisz plik>. Użyj opcji Zapisz wszystko , aby zapisać wiele plików jednocześnie.

Zatwierdzanie i wypychanie zmian

W przypadku istotnych zmian lub przejrzenia artykułu pod kątem aktualności zaktualizuj ms.date blok metadanych w górnej części pliku. Sformatuj datę jako mm/dd/rrrr.

Możesz użyć terminalu programu VS Code lub interfejsu użytkownika programu VS Code, aby zatwierdzić i wypchnąć zmiany.

VS Code Terminal

1. Uruchom polecenie , git status aby sprawdzić, czy na liście zmienionych plików są wyświetlane tylko edytowane pliki.

   git status
   

2. git add Uruchom polecenie, a następnie ścieżkę pliku i nazwę pliku, aby przygotować zmieniony plik.

   git add folder-name/file-name.md
   

   Jeśli zmieniono wiele plików, wprowadź git add polecenie dla każdego pliku.

   Alternatywnie możesz uruchomić git add . (zanotuj okres po add), aby automatycznie przygotować wszystkie wprowadzone zmiany. Ta metoda jest szybsza, ale może powodować problemy, dołączając zmiany wprowadzone przypadkowo.

3. Uruchom ponownie polecenie git status , aby potwierdzić, jakie zmiany zostały przygotowane.

4. git commit Uruchom polecenie, a następnie komunikat zatwierdzenia, aby zapisać zmiany w lokalnym sklonowanym repozytorium.

   git commit -m "your commit message"
   

5. Uruchom polecenie git push , aby wypchnąć zmiany.

   git push
   

Interfejs użytkownika programu VS Code

Możesz utworzyć i wypchnąć zatwierdzenie przy użyciu funkcji integracji z usługą Git programu VS Code. Pamiętaj, aby kontynuować pracę na tym samym komputerze. Jeśli przełączysz maszyny, nie będziesz mieć najnowszej wersji gałęzi roboczej, aby kontynuować.

1. Upewnij się, że repozytorium lokalne nadal ma wyewidencjonowane tę samą gałąź roboczą. W interfejsie użytkownika programu VS Code gałąź jest wyświetlana w lewym dolnym rogu. Nazwa gałęzi działa również jako przycisk przełączania gałęzi.

   

2. Na lewym pasku bocznym programu VS Code wybierz narzędzie rozwidlenia, aby wyświetlić okienko Kontrola źródła: Git .

   

   Edytowany plik jest wyświetlany w obszarze Zmiany z tekstem M po prawej stronie, aby wskazać, że został zmodyfikowany. Nowe pliki są wyświetlane z identyfikatorem U (bez śledzenia) i usuniętymi plikami są wyświetlane z D.

3. Przygotuj zmiany. Zatrzymaj wskaźnik myszy na wierszu Zmiany , aż pojawi się ikona + . Wybierz tę ikonę. Ta akcja jest odpowiednikiem git add polecenia . Plik zostanie wyświetlony w sekcji Zmiany etapowe.

4. Wprowadź komunikat zatwierdzenia, taki jak "aktualizuj datę metadanych" w polu tekstowym Komunikat , a następnie wybierz znacznik wyboru.

   

5. Wypchnij zatwierdzenie. Wybierz przycisk Synchronizuj zmiany, który jest wyświetlany poniżej bloku zatwierdzania komunikatów.

   

Gotowe! Kod jest teraz gotowy do otwarcia żądania ściągnięcia w repozytorium GitHub.

Chcesz poprawić przesłaną zawartość? To łatwe! Powtórz powyższe kroki, zaczynając od pozycji Edytuj plik, aby wprowadzić zmiany w tej samej gałęzi, a następnie zatwierdzić i wypchnąć ponownie (nie trzeba konfigurować serwera nadrzędnego na kolejnych wypychaniach tej samej gałęzi). Ogólnie rzecz biorąc, gałęzie są używane do oddzielania strumieni pracy, więc nie trzeba tworzyć nowej gałęzi, chyba że wszystko będzie gotowe do pracy nad czymś innym.

Wprowadź kolejną zmianę

Chcesz wprowadzić inną zmianę, niepowiązaną z tą? Wróć do gałęzi domyślnej, pobierz z repozytorium nadrzędnego, aby zaktualizować rozwidlenie i wyewidencjonuj nową gałąź. Uruchom następujące polecenia w aplikacji Git Bash:

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

Jesteś teraz w nowej gałęzi połączonej z gałęzią zdalną i możesz wprowadzić więcej zmian. Jesteś dobrze w drodze, aby stać się współautorem ekspertów!

Następne kroki

• Jeśli powyższe kroki zostały wykonane, nadszedł czas, aby otworzyć żądanie ściągnięcia w celu scalenia zmian z gałęzią główną.
• Aby dowiedzieć się więcej o tematach, takich jak składnia rozszerzeń języka Markdown i Markdown, zapoznaj się z dokumentacją języka Markdown.