Dokumentowanie funkcji nowego wydania
Każda główna wersja Kubernetesa wprowadza nowe funkcje, które wymagają dokumentacji. Nowe wersje przynoszą również aktualizacje do istniejących funkcji i dokumentacji (na przykład awansowanie funkcji z wersji alpha do beta).
Zazwyczaj SIG odpowiedzialny za funkcję przesyła szkic dokumentacji
funkcji jako pull request do odpowiedniego gałęzi rozwojowej w repozytorium
kubernetes/website, a ktoś z zespołu SIG Docs dostarcza uwagi redakcyjne
lub edytuje szkic bezpośrednio. Ta sekcja opisuje konwencje dotyczące
rozgałęzień (ang. branching) oraz proces stosowany podczas wydania przez obie grupy.
Dla współtwórców dokumentacji
Ogólnie rzecz biorąc, współtwórcy dokumentacji nie piszą treści od podstaw na potrzeby wydania. Zamiast tego współpracują z SIG tworzącym nową funkcję, aby dopracować szkic dokumentacji i przygotować go do wydania.
Po wybraniu fukncji do udokumentowania lub wsparcia, zapytaj o nią na kanale
Slack #sig-docs, podczas cotygodniowego spotkania SIG Docs lub bezpośrednio w
zgłoszeniu PR wystawionym przez SIG odpowiedzialny za funkcje. Jeśli otrzymasz
zgodę, możesz edytować PR za pomocą jednej z technik opisanych w
Wprowadź zmiany do PR innej osoby.
Dowiedz się o nadchodzących funkcjach
Aby dowiedzieć się o nadchodzących funkcjach, weź udział w cotygodniowym spotkaniu SIG Release (zobacz stronę społeczności w celu uzyskania informacji o nadchodzących spotkaniach) i monitoruj dokumentację dotyczącą wydania w repozytorium kubernetes/sig-release. Każde wydanie ma podkatalog w katalogu /sig-release/tree/master/releases/. Podkatalog zawiera harmonogram wydania, szkic notatek do wydania oraz dokument z listą każdej osoby w zespole wydania.
Harmonogram wersji zawiera linki do wszystkich innych dokumentów, spotkań, protokołów spotkań i kamieni milowych związanych z wydaniem. Zawiera również informacje o celach i harmonogramie wydania oraz wszelkich specjalnych procesach wdrożonych dla tego wydania. Pod koniec dokumentu zdefiniowano kilka terminów związanych z wydaniem.
Ten dokument zawiera również link do Arkusza śledzenia funkcji, który jest oficjalnym sposobem na poznanie wszystkich nowych funkcji planowanych do wprowadzenia w wydaniu.
Dokumentacja zespołu odpowiadającego za kolejne wydanie zawiera listę osób do przypisanych do różnych ról. Jeśli nie jest jasne, do kogo się zwrócić w sprawie konkretnej funkcji lub pytania, które masz, możesz skorzystać z jednego z dwóch rozwiązań: weź udział w spotkaniu zespołu, aby zadać swoje pytanie, lub skontaktuj się z liderem wydania, aby mógł Cię odpowiednio skierować.
Szkic notatek z wydania to dobre miejsce, aby dowiedzieć się o specyficznych funkcjach, zmianach, przestarzałych elementach i innych kwestiach dotyczących wydania. Ponieważ treść nie jest ostateczna aż do późnego etapu, warto zachować ostrożność.
Arkusz śledzenia funkcji
Arkusz śledzenia funkcji dla danej wersji Kubernetesa wymienia każdą funkcję, która jest planowana do wydania. Każdy element zawiera nazwę funkcji, link do głównego problemu na GitHubie, poziom stabilności (Alpha, Beta lub Stable), SIG i osobę odpowiedzialną za jej wdrożenie, czy wymaga dokumentacji, projekt notatki o wydaniu dla funkcji oraz czy została zintegrowana. Pamiętaj o następujących zasadach:
- Funkcje w wersji Beta i Stable są zazwyczaj priorytetowane wyżej w dokumentacji niż funkcje w wersji Alfa.
- Trudno jest przetestować (a tym samym udokumentować) funkcję, która nie została zmergowana, lub przynajmniej jest uważana za kompletną w swoim PR.
- Określenie, czy funkcja wymaga dokumentacji, jest procesem manualnym. Nawet jeśli funkcja nie jest oznaczona jako wymagająca dokumentacji, może być konieczne jej udokumentowanie.
Dla developerów lub innych członków SIG
Ta sekcja zawiera informacje dla członków innych SIG Kubernetesów dokumentujących nowe funkcje na potrzeby wydania.
Jeśli jesteś członkiem SIG, który rozwija nową funkcję dla
Kubernetesa, musisz współpracować z SIG Docs, aby mieć pewność, że
Twoja funkcja zostanie udokumentowana na czas przed wydaniem.
Sprawdź arkusz śledzenia funkcji
lub sprawdź kanał Slack
Kubernetes #sig-release, aby zweryfikować szczegóły harmonogramu i terminy.
Otwórz tymczasowy PR
- Otwórz szkic pull requestu do gałęzi
dev-1.33w repozytoriumkubernetes/website, z małym commitem, który później zmienisz. Aby utworzyć szkic pull requestu, użyj rozwijanego menu Create Pull Request i wybierz Create Draft Pull Request, następnie kliknij Draft Pull Request. - Edytuj opis pull requesta, aby zawierał linki do PR-ów w kubernetes/kubernetes oraz zgłoszeń w kubernetes/enhancements.
- Zostaw komentarz w powiązanym zgłoszeniu w tym repozytorium kubernetes/enhancements z linkiem do PR, aby powiadomić osobę zajmującą się dokumentacją tej wersji, że dokumentacja dotycząca funkcji jest w przygotowaniu i powinna być śledzona w tym wydaniu.
Jeśli Twoja funkcjonalność nie wymaga żadnych zmian w dokumentacji, upewnij się, że zespół
sig-release o tym wie, wspominając o tym na kanale Slack #sig-release. Jeśli funkcjonalność wymaga
dokumentacji, ale PR nie został utworzony, funkcjonalność może zostać usunięta z kamienia milowego.
PR gotowy do przeglądu
Kiedy będziesz gotowy, wypełnij swój tymczasowy PR dokumentacją funkcji i zmień stan PR z roboczego na ready for review. Aby oznaczyć pull request jako gotowy do przeglądu, przejdź do pola scalania (ang. merge box) i kliknij Ready for review.
Najlepiej jak potrafisz opisz swoją funkcję i sposób jej użycia. Jeśli
potrzebujesz pomocy w strukturyzacji swojej dokumentacji, zapytaj na kanale Slack #sig-docs.
Gdy ukończysz swój materiał, osoba odpowiedzialna za dokumentację przypisana do Twojej funkcji go przegląda. Aby zapewnić dokładność techniczną, treść może również wymagać przeglądu technicznego przez odpowiednie SIG-i. Skorzystaj z ich sugestii, aby dopracować treść do stanu gotowego do wydania.
Jeśli twoja funkcja wymaga dokumentacji, a pierwsza wersja treści nie zostanie dostarczona, funkcja może zostać usunięta z kamienia milowego.
Bramki funkcji (ang. feature gates)
Jeśli Twoja funkcja jest funkcją Alfa lub Beta i jest włączana warunkowo
bramką funkcji (ang. feature gate), potrzebujesz dla niej pliku bramki
funkcji wewnątrz content/en/docs/reference/command-line-tools-reference/feature-gates/.
Nazwa pliku powinna być nazwą bramki funkcji z sufiksem .md.
Możesz spojrzeć na inne pliki już znajdujące się w tym samym katalogu, aby
uzyskać wskazówkę, jak powinien wyglądać Twój plik. Zwykle wystarczy jeden
akapit; dla dłuższych wyjaśnień dodaj dokumentację w innym miejscu i dodaj do niej link.
Aby upewnić się, że twój feature gate pojawi się w tabeli Alpha/Beta Feature gates, dodaj następujące informacje do sekcji front matter w pliku Markdown z opisem:
stages:
- stage: <alpha/beta/stable/deprecated> # Specify the development stage of the feature gate
defaultValue: <true or false> # Set to true if enabled by default, false otherwise
fromVersion: <Version> # Version from which the feature gate is available
toVersion: <Version> # (Optional) The version until which the feature gate is available
W przypadku nowych bramek funkcji wymagany jest również osobny opis
bramki funkcji; utwórz nowy plik Markdown w
content/en/docs/reference/command-line-tools-reference/feature-gates/ (użyj innych plików jako szablonu).
Gdy zmieniasz bramkę funkcji z domyślnie wyłączonej na domyślnie włączoną,
może być konieczne zmienienie również innej
dokumentacji (nie tylko listy bramek funkcji). Uważaj na zwroty takie jak „Pole
exampleSetting jest polem beta i jest domyślnie
wyłączone. Możesz je włączyć, włączając bramkę funkcji ProcessExampleThings.”
Jeśli Twoja funkcja osiągnęła status GA lub została oznaczona jako
przestarzała, dodaj dodatkowy wpis stage w ramach bloku stages w pliku opisu. Upewnij się,
że etapy Alpha i Beta pozostają nienaruszone. Ten krok przenosi bramkę
funkcji z Feature gates for Alpha/Beta
do
Feature gates for graduated or deprecated features.
Na przykład:
stages:
- stage: alpha
defaultValue: false
fromVersion: "1.12"
toVersion: "1.12"
- stage: beta
defaultValue: true
fromVersion: "1.13"
# Added a `toVersion` to the previous stage.
toVersion: "1.18"
# Added 'stable' stage block to existing stages.
- stage: stable
defaultValue: true
fromVersion: "1.19"
toVersion: "1.27"Ostatecznie Kubernetes przestanie w ogóle uwzględniać bramę funkcji.
Aby zasygnalizować usunięcie bramy funkcji, uwzględnij removed: true w
przedniej części odpowiedniego pliku opisu. Wprowadzenie tej zmiany
oznacza, że informacje o bramie funkcji przenoszą się z
Skróty funkcji dla ukończonych lub przestarzałych funkcji do dedykowanej
strony
zatytułowanej Skróty funkcji (usunięte),
łącznie z jej opisem.
Wszystkie PR-y zostały zrecenzowane i są gotowe do scalenia
Jeśli Twój PR nie został jeszcze scalony z gałęzią dev-1.33
przed terminem wydania, współpracuj z osobą odpowiedzialną za dokumentację i zarządzającą wydaniem,
aby dodać go przed terminem. Jeśli Twoja funkcja potrzebuje dokumentacji, a
dokumentacja nie jest gotowa, funkcja może zostać usunięta z bieżącego planu (milestone).