Istnieje wiele sposobów, aby wnieść wkład do Kubernetes. Możesz pracować nad projektami
nowych funkcji, możesz dokumentować kod, który już mamy, możesz pisać do naszych
blogów. Jest więcej: możesz implementować te nowe funkcje lub naprawiać błędy.
Możesz pomóc ludziom dołączyć do naszej społeczności współtwórców lub wspierać istniejących współtwórców.
We wszystkich tych sposobach, aby mieć wpływ na projekt, my -
Kubernetes - stworzyliśmy dedykowaną stronę internetową: https://k8s.dev/.
Możesz tam przejść, aby dowiedzieć się więcej o wnoszeniu wkładu do Kubernetes.
Możesz również przeczytać
CNCFstronę o
wnoszeniu
wkładu do Kubernetes.
1 - Współtworzenie dokumentacji Kubernetes
Ta strona jest utrzymywana przez Kubernetes SIG Docs.
Projekt Kubernetes chętnie przyjmie pomoc od wszystkich współtwórców, zarówno nowych, jak i doświadczonych!
Współtwórcy dokumentacji Kubernetesa:
Ulepszają istniejącą treść
Tworzą nowe treści
Tłumaczą dokumentację
Zarządzają i publikują części dokumentacji cyklu wydawniczego Kubernetesa
Każdy może otworzyć zgłoszenie dotyczące
dokumentacji lub wnieść zmianę za pomocą pull request
(PR) w repozytorium kubernetes/website na GitHubie.
Musisz umieć
sprawnie korzystać z
git i GitHub,
aby efektywnie pracować w społeczności Kubernetesa.
flowchart TB
subgraph third[Otwórz PR]
direction TB
U[ ] -.-
Q[Popraw treść] --- N[Utwórz treść]
N --- O[Tłumacz dokumentację]
O --- P[Zarządzaj/publikuj części dokumentów w cyklu wydania K8s]
end
subgraph second[Przegląd]
direction TB
T[ ] -.-
D[Przejrzyj repozytorium kubernetes/website] --- E[Sprawdź generator stron statycznych Hugo]
E --- F[Zrozum podstawowe komendy GitHub]
F --- G[Przejrzyj otwarte PR i procesy przeglądu zmian]
end
subgraph first[Rejestracja]
direction TB
S[ ] -.-
B[Podpisz umowę o licencję wniesienia wkładu CNCF] --- C[Dołącz do kanału Slack sig-docs]
C --- V[Dołącz do listy mailowej kubernetes-sig-docs]
V --- M[Uczestnicz w cotygodniowych spotkaniach sig-docs lub spotkaniach na Slacku]
end
A([fa:fa-user Nowy Współtwórca]) --> first
A --> second
A --> third
A --> H[Pytaj!!!]
classDef grey fill:#dddddd,stroke:#ffffff,stroke-width:px,color:#000000, font-size:15px;
classDef white fill:#ffffff,stroke:#000,stroke-width:px,color:#000,font-weight:bold
classDef spacewhite fill:#ffffff,stroke:#fff,stroke-width:0px,color:#000
class A,B,C,D,E,F,G,H,M,Q,N,O,P,V grey
class S,T,U spacewhite
class first,second,third white
Rysunek 1. Jak zacząć jako nowy współtwórca.
Rysunek 1 przedstawia plan działania dla nowych współtwórców. Możesz
podążać za niektórymi lub wszystkimi krokami dotyczącymi Sign up i
Review. Teraz możesz otwierać PR spełniające Twoje cele kontrybucji -
niektóre z nich znajdziesz w sekcji Open PR. Jak zawsze, pytania są mile widziane!
Niektóre zadania wymagają większego zaufania i większego dostępu w
organizacji Kubernetes. Zobacz
Udział w SIG Docs po więcej szczegółów na temat ról i uprawnień.
Twoja pierwsza kontrybucja
Aby przygotować się do twojej pierwszej kontrybucji, warto wcześniej przeanalizować
kilka kroków. Rysunek 2 przedstawia ich schemat, a szczegółowe informacje znajdują się poniżej.
flowchart LR
subgraph second[Pierwszy wkład]
direction TB
S[ ] -.-
G[Przeglądaj PR od innych członków K8s] -->
A[Sprawdź listę zgłoszeń kubernetes/website dobre na pierwszy PR] --> B[Otwórz PR!!]
end
subgraph first[Zalecane przygotowanie]
direction TB
T[ ] -.-
D[Przeczytaj współtworzenie nowych treści] -->E[Przeczytaj przewodniki po treści K8s i stylach]
E --> F[Poznaj typy treści stron Hugo i shortcode'y]
end
first ----> second
classDef grey fill:#dddddd,stroke:#ffffff,stroke-width:px,color:#000000, font-size:15px;
classDef white fill:#ffffff,stroke:#000,stroke-width:px,color:#000,font-weight:bold
classDef spacewhite fill:#ffffff,stroke:#fff,stroke-width:0px,color:#000
class A,B,D,E,F,G grey
class S,T spacewhite
class first,second white
Rysunek 2. Przygotowanie do twojej pierwszej kontrybucji.
Rozpoczęcie współpracy nad projektem może być wyzwaniem.
Ambasadorzy Nowych Współtwórców pomogą Ci
przejść przez pierwsze kroki. Możesz skontaktować się z nimi na
Kubernetes Slack, najlepiej na kanale #sig-docs. Istnieje również rozmowa powitalna dla nowych współtwórców,
która
odbywa się w pierwszy wtorek każdego miesiąca. Możesz tu
wchodzić w interakcje z Ambasadorami Nowych Współtwórców i uzyskać odpowiedzi na swoje pytania.
SIG Docs to grupa współtwórców, którzy
publikują i utrzymują dokumentację Kubernetesa oraz stronę internetową.
Zaangażowanie się w SIG Docs to doskonały sposób dla współtwórców
Kubernetes (rozwój funkcji lub inne) na wywarcie dużego wpływu na projekt Kubernetesa.
SIG Dokumentacja komunikuje się za pomocą różnych metod:
Dołącz do asynchronicznego spotkania SIG Docs na Slacku w tygodniach, kiedy
spotkanie wideo na Zoomie na żywo się nie odbywa. Spotkania są zawsze ogłaszane na
#sig-docs. Możesz wnieść swój wkład w dowolny z wątków do 24 godzin po ogłoszeniu spotkania.
Inne sposoby wnoszenia wkładu
Odwiedź stronę społeczności Kubernetesa. Skorzystaj z Twittera lub
Stack Overflow, dowiedz się o lokalnych spotkaniach i wydarzeniach Kubernetesa i nie tylko.
Ta sekcja zawiera informacje, które
powinieneś znać przed dodaniem nowej treści.
flowchart LR
subgraph second[Zanim zaczniesz]
direction TB
S[ ] -.-
A[Podpisz CNCF CLA] --> B[Wybierz gałąź Git]
B --> C[Jeden język na PR]
C --> F[Sprawdź narzędzia dla współtwórców]
end
subgraph first[Podstawy współtworzenia]
direction TB
T[ ] -.-
D[Pisz dokumentację w Markdown i buduj stronę za pomocą Hugo] --- E[Kod źródłowy w GitHub]
E --- G[Folder '/content/../docs' zawiera dokumentację w wielu językach]
G --- H[Zapoznaj się z typami stron i shortcode'ami w Hugo]
end
first ----> second
classDef grey fill:#dddddd,stroke:#ffffff,stroke-width:px,color:#000000, font-size:15px;
classDef white fill:#ffffff,stroke:#000,stroke-width:px,color:#000,font-weight:bold
classDef spacewhite fill:#ffffff,stroke:#fff,stroke-width:0px,color:#000
class A,B,C,D,E,F,G,H grey
class S,T spacewhite
class first,second white
Rysunek - Przygotowanie nowej treści
Powyższy rysunek przedstawia informacje, które powinieneś znać przed
przesłaniem nowej treści. Szczegóły znajdują się poniżej.
Podstawy kontrybucji
Napisz dokumentację Kubernetesa w formacie Markdown i
zbuduj stronę Kubernetesa za pomocą Hugo.
Dokumentacja Kubernetesa używa CommonMark jako swojej wersji Markdown.
Źródło znajduje się na GitHub.
Dokumentację Kubernetesa można znaleźć w
/content/en/docs/. Część dokumentacji referencyjnej jest
automatycznie generowana ze skryptów w katalogu update-imported-docs/.
Oprócz standardowych kodów Hugo, w naszej dokumentacji
używamy wielu niestandardowych kodów Hugo,
aby kontrolować prezentację treści.
Dokumentacja jest dostępna w wielu językach w katalogu /content/. Każdy język
ma własny folder z dwuliterowym kodem określonym przez
standard ISO 639-1 . Na
przykład, źródło dokumentacji angielskiej jest przechowywane w /content/en/docs/.
Aby uzyskać więcej informacji na temat wnoszenia wkładu
do dokumentacji w wielu językach lub rozpoczęcia nowego
tłumaczenia, zobacz Lokalizowanie.
Pull requesty od autorów, którzy nie podpisali umowy CLA, nie
przechodzą testów automatycznych. Imię i adres e-mail, które podasz,
muszą zgadzać się z tymi ustawionymi w twoim git config, a twoje
imię i adres e-mail w git muszą być takie same jak te używane dla CNCF CLA.
Wybierz gałąź w Git
Podczas otwierania pull requesta musisz
wiedzieć z góry, na której gałęzi oprzeć swoją pracę.
Scenariusz
Gałąź
Istniejąca lub nowa treść w języku angielskim dla bieżącego wydania
main
Treść dla wydania zmiany funkcji
Gałąź, która odpowiada głównej i mniejszej wersji, w której znajduje się zmiana funkcji, używając wzorca dev-<version>. Na przykład, jeśli funkcja zmienia się w wydaniu v1.34, należy dodać zmiany w dokumentacji do gałęzi dev-1.34.
Jeśli nadal nie masz pewności, którą gałąź wybrać, zapytaj na #sig-docs na Slacku.
Informacja:
Jeśli już zgłosiłeś swoj pull request i wiesz, że była to
niepoprawna gałąź bazowa, możesz ją zmienić (ty i tylko ty, zgłaszający).
Języki na PR
Ogranicz żądania pull request do jednego języka na PR.
Jeśli musisz wprowadzić identyczną zmianę w tym samym
fragmencie kodu w wielu językach, otwórz osobne PR dla każdego języka.
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.
Więcej o publikowaniu nowych funkcji na blogu przeczytasz w
sekcji komunikaty po wydaniu.
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.34 w repozytorium kubernetes/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.
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 gatedefaultValue:<true or false> # Set to true if enabled by default, false otherwisefromVersion:<Version> # Version from which the feature gate is availabletoVersion:<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:falsefromVersion:"1.12"toVersion:"1.12"- stage:beta defaultValue:truefromVersion:"1.13"# Added a `toVersion` to the previous stage.toVersion:"1.18"# Added 'stable' stage block to existing stages.- stage:stabledefaultValue:truefromVersion:"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.34
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).
3 - Zgłaszanie propozycji poprawy treści
Jeśli zauważysz problem z dokumentacją Kubernetesa lub masz pomysł na nową treść, otwórz zgłoszenie. Wszystko, czego potrzebujesz, to konto GitHub i przeglądarka internetowa.
W większości przypadków nowa praca nad dokumentacją Kubernetesa rozpoczyna się od zgłoszenia na
GitHubie. Współtwórcy Kubernetesa następnie przeglądają, kategoryzują i tagują zgłoszenia. Następnie
Ty lub inny członek społeczności Kubernetesa otwiera pull requesta z poprawkami rozwiązującymi problem.
Otwarcie zgłoszenia
Jeśli chcesz zasugerować ulepszenia do istniejącej treści lub zauważysz błąd, otwórz zgłoszenie.
Kliknij link Create an issue na prawym pasku bocznym. Przekieruje
Cię to na stronę z problemem w GitHub wstępnie wypełnioną kilkoma nagłówkami.
Opisz problem lub sugestię poprawy. Podaj jak najwięcej szczegółów.
Kliknij Submit new issue.
Po przesłaniu, od czasu do czasu sprawdzaj swoje zgłoszenie lub włącz
powiadomienia GitHub. Recenzenci i inni członkowie społeczności mogą
zadawać pytania, zanim będą mogli podjąć działania w sprawie Twojego zgłoszenia.
Sugestia nowej treści
Jeśli masz pomysł na nowe treści, ale nie jesteś pewien, gdzie powinny
się one znaleźć, możesz nadal utworzyć zgłoszenie. Wykonaj jeden z kroków:
Wybierz istniejącą stronę w sekcji, do której Twoim zdaniem należy treść, i kliknij Create an issue.
Przejdź do GitHub i utwórz zgłoszenie bezpośrednio.
Jak tworzyć świetne zgłoszenia
Pamiętaj o następujących rzeczach przy zgłaszaniu problemu:
Podaj jasny opis problemu. Opisz, co konkretnie
jest brakujące, nieaktualne, błędne lub wymaga poprawy.
Wyjaśnij, jaki konkretny wpływ ma ten problem na użytkowników.
W przypadku problemów o dużym zakresie, podziel je na mniejsze zagadnienia, aby
łatwiej było nad nimi pracować. Na przykład, "Napraw dokumentację
dotyczącą bezpieczeństwa" jest zbyt ogólne, ale "Dodaj szczegóły do tematu
'Ograniczanie dostępu do sieci'" jest na tyle precyzyjne, by można było podjąć działanie.
Przeszukaj istniejące zgłoszenia, aby sprawdzić, czy jest
coś związanego lub podobnego do nowego zgłoszenia.
Jeśli nowe zgłoszenie dotyczy innego zgłoszenia lub pull requesta,
odwołaj się do niego poprzez podanie pełnego adresu URL lub numeru zgłoszenia lub pull
requesta poprzedzonego znakiem #. Na przykład: Introduced by #987654.
Przestrzegaj Kodeksu postępowania.
Szanuj innych współtwórców. Na przykład,
"Dokumentacja jest okropna" nie jest ani pomocną ani uprzejmą opinią.
4 - Przeglądanie zmian
W tej sekcji opisano, jak dokonać przeglądu treści.
5 - Tłumaczenie i adaptacja językowa dokumentacji Kubernetes
Ta strona pokazuje, jak
zlokalizować dokumentację
na inny język.
Aby uzyskać dodatkowe szczegóły dotyczące kontrybucji do
konkretnej lokalizacji, poszukaj zlokalizowanej wersji tej strony.
Znajdź swój dwuliterowy kod języka
Najpierw zapoznaj się ze standardem ISO 639-1
w
celu znalezienia dwuliterowego kodu języka dla
lokalizacji. Na przykład dwuliterowy kod dla języka polskiego to pl.
Niektóre języki używają małej wersji kodu kraju, jak
zdefiniowano w ISO-3166, wraz z ich kodami językowymi. Na
przykład kod języka portugalskiego (brazylijskiego) to pt-br.
Następnie, sklonuj swój fork i przejdź do niego za pomocą cd:
git clone https://github.com/<nazwa-użytkownika>/website
cd website
Katalog zawartości witryny zawiera podkatalogi dla każdego języka.
Lokalizacja, przy której chcesz pomóc, znajduje się w content/<kod-dwuliterowy>.
Zaproponuj zmiany
Stwórz lub zaktualizuj wybraną przez Ciebie zlokalizowaną stronę na podstawie
oryginału w języku angielskim. Zobacz zlokalizuj treść po więcej szczegółów.
Jeśli zauważysz błąd techniczny lub inny problem z dokumentacją źródłową
(angielską), najpierw powinieneś naprawić dokumentację źródłową, a
następnie powtórzyć równoważną poprawkę, aktualizując lokalizację, nad którą pracujesz.
Limituj zmiany w pull requestach do jednej lokalizacji. Przeglądanie pull
requestów, które zmieniają zawartość w wielu lokalizacjach, jest problematyczne.
Postępuj zgodnie z Sugestie dotyczące ulepszenia treści,
aby zaproponować zmiany w tej lokalizacji.
Proces jest podobny do proponowania zmian w oryginalnej (angielskiej) treści.
Rozpocznij nową lokalizację
Jeśli chcesz, aby dokumentacja Kubernetes została przetłumaczona
na nowy język, oto co musisz zrobić:
Ponieważ współtwórcy nie mogą zatwierdzać własnych pull request,
potrzebujesz co najmniej dwóch współtwórców, aby rozpocząć lokalizację.
Wszystkie zespoły zajmujące się lokalizacją muszą być samowystarczalne.
Strona internetowa Kubernetes chętnie udostępni Twoje prace, ale to do Ciebie
należy ich przetłumaczenie oraz aktualizowanie istniejących zlokalizowanych treści.
Będziesz musiał znać dwuliterowy kod językowy dla swojego języka.
Zapoznaj się z standardem ISO 639-1,
aby znaleźć dwuliterowy kod językowy dla
swojej lokalizacji. Na przykład dwuliterowy kod dla języka polskiego to pl.
Jeśli język, dla którego zaczynasz lokalizację, jest używany w różnych
miejscach z istotnymi różnicami między wariantami, może mieć sens
połączenie małej litery kodu kraju ISO-3166 z dwuliterowym kodem językowym. Na
przykład, brazylijska odmiana języka portugalskiego jest lokalizowana jako pt-br.
Gdy rozpoczynasz nową lokalizację, musisz
przetłumaczyć całą minimalnie wymaganą zawartość,
zanim projekt Kubernetesa
będzie mógł opublikować zmiany na stronie internetowej.
SIG Docs może pomóc Ci pracować na osobnej gałęzi, abyś
mógł stopniowo dążyć do osiągnięcia tego celu.
Znajdź społeczność
Daj znać zespołowi Kubernetes SIG Docs, jeśli jesteś zainteresowany
tworzeniem lokalizacji! Dołącz do kanłu Slack SIG Docs
oraz kanłu Slack SIG Docs Localizations.
Inne zespoły
zajmujące się lokalizacją chętnie pomogą Ci zacząć i odpowiedzą na Twoje pytania.
Proszę również rozważyć udział w spotkaniu podgrupy lokalizacyjnej SIG Docs.
Misją
podgrupy lokalizacyjnej SIG Docs jest współpraca z zespołami lokalizacyjnymi SIG
Docs w celu współpracy nad definiowaniem i dokumentowaniem procesów tworzenia
zlokalizowanych przewodników wkładu. Ponadto, podgrupa lokalizacyjna SIG Docs
poszukuje możliwości tworzenia i udostępniania wspólnych narzędzi wśród
zespołów lokalizacyjnych oraz identyfikuje nowe wymagania dla zespołu kierowniczego SIG
Docs. Jeśli masz pytania dotyczące tego spotkania, zapytaj na kanale
Slack SIG Docs Localizations.
Możesz również utworzyć kanał Slack dla swojej lokalizacji w repozytorium
kubernetes/community. Przykład dodawania kanału Slack znajdziesz w PR dla
dodawania kanału dla perskiego.
Dołącz do organizacji Kubernetesa na GitHubie
Kiedy otworzysz PR lokalizacyjny, możesz zostać członkiem
organizacji Kubernetesa na GitHubie. Każda osoba w zespole musi
utworzyć własne Żądanie Członkostwa w Organizacji
w repozytorium kubernetes/org.
Członkowie @kubernetes/sig-docs-**-owners mogą zatwierdzać PRy, które zmieniają zawartość
w (i tylko w) twoim katalogu lokalizacyjnym: /content/**/. Dla
każdej lokalizacji, zespół @kubernetes/sig-docs-**-reviews automatyzuje
przypisywanie recenzji dla nowych PRów. Członkowie @kubernetes/website-maintainers mogą
tworzyć nowe gałęzie lokalizacyjne, aby koordynować wysiłki tłumaczeniowe.
Członkowie @kubernetes/website-milestone-maintainers mogą używać
komendy Prow/milestone, aby przypisać kamień milowy do problemów lub PRów.
Skonfiguruj przepływ pracy
Następnie dodaj etykietę GitHub dla swojej lokalizacji w
repozytorium kubernetes/test-infra. Etykieta pozwala
filtrować zgłoszenia i pull requesty dla Twojego konkretnego języka.
Strona internetowa Kubernetesa wykorzystuje Hugo jako swoją strukturę
sieciową. Konfiguracja Hugo dla strony internetowej znajduje się w pliku hugo.toml.
Trzeba
będzie zmodyfikować hugo.toml, aby obsługiwać nową lokalizację.
Dodaj blok konfiguracyjny dla nowego języka do hugo.toml pod istniejącym blokiem
[languages]. Blok dla języka niemieckiego wygląda na przykład tak:
Pasek wyboru języka wyświetla wartość dla languageName.
Przypisz "nazwa języka w ojczystym piśmie i języku (angielska nazwa
języka w łacińskim piśmie)" do languageName. Na przykład,
languageName = "한국어 (Korean)" lub languageName = "Deutsch (German)".
languageNameLatinScript można użyć do uzyskania nazwy języka w
alfabecie łacińskim i użycia jej w motywie. Przypisz "nazwa języka w
alfabecie łacińskim" do languageNameLatinScript. Na przykład,
languageNameLatinScript ="Korean" lub languageNameLatinScript = "Deutsch".
Parametr weight określa kolejność języków na pasku wyboru języka. Niższa
wartość weight ma pierwszeństwo, co skutkuje tym, że język pojawia się jako pierwszy.
Przy przypisywaniu parametru weight ważne jest, aby zbadać
istniejący blok języków i dostosować ich wartości, aby zapewnić, że są w
uporządkowanej kolejności względem wszystkich języków, w tym każdego nowo dodanego języka.
Aby uzyskać więcej informacji na temat wsparcia wielojęzycznego Hugo,
zobacz Multilingual mode.
Dodaj nowy katalog lokalizacyjny
Dodaj podkatalog specyficzny dla języka do folderu
content w
repozytorium. Na przykład dwuliterowy kod dla języka niemieckiego to de:
mkdir content/de
Musisz również utworzyć katalog wewnątrz data/i18n dla
zlokalizowanych ciągów; spójrz na istniejące
lokalizacje jako przykład. Aby użyć tych nowych ciągów, musisz również
utworzyć dowiązanie symboliczne (ang. symbolic link) z
i18n/<localization>.toml do rzeczywistej konfiguracji ciągów w
data/i18n/<localization>/<localization>.toml (pamiętaj o zatwierdzeniu dowiązania symbolicznego).
Na przykład, dla języka niemieckiego ciągi znaków znajdują się w
data/i18n/de/de.toml, a i18n/de.toml jest dowiązaniem symbolicznym do data/i18n/de/de.toml.
Zlokalizuj kodeks postępowania społeczności
Otwórz PR w repozytorium cncf/foundation,
aby
dodać kodeks postępowania w swoim języku.
Skonfiguruj pliki OWNERS
Aby ustawić role każdego użytkownika wnoszącego wkład do
lokalizacji, utwórz plik OWNERS w podkatalogu specyficznym dla języka za pomocą:
reviewers: Lista zespołów Kubernetesa z rolami recenzentów, w tym przypadku,
labels: Lista etykiet GitHub, które zostaną automatycznie zastosowane do PR, w tym
przypadku etykieta językowa utworzona w Konfiguracja przepływu pracy.
Więcej informacji na temat pliku OWNERS można znaleźć na
stronie go.k8s.io/owners.
Plik Spanish OWNERS
z kodem języka es wygląda następująco:
# See the OWNERS docs at https://go.k8s.io/owners# This is the localization project for Spanish.# Teams and members are visible at https://github.com/orgs/kubernetes/teams.reviewers:- sig-docs-es-reviewsapprovers:- sig-docs-es-ownerslabels:- language/es
Po dodaniu pliku OWNERS specyficznego dla danego języka, zaktualizuj
główny plik OWNERS_ALIASES
z nowymi zespołami
Kubernetesa dla lokalizacji, sig-docs-**-owners i sig-docs-**-reviews.
Aby poprowadzić innych współtwórców lokalizacji, dodaj nowy
plik README-**.md
na najwyższym poziomie kubernetes/website,
gdzie ** to dwuliterowy kod
języka. Na przykład, niemiecki plik README nosiłby nazwę README-de.md.
Prowadź współtwórców lokalizacji w zlokalizowanym pliku README-**.md.
Zawieraj te same informacje, które znajdują się w README.md, a także:
Punkt kontaktowy dla projektu lokalizacyjnego
Wszelkie informacje specyficzne dla lokalizacji
Po utworzeniu zlokalizowanego pliku README, dodaj link do tego
pliku z głównego angielskiego README.md i dołącz informacje
kontaktowe w języku angielskim. Możesz podać ID GitHub, adres e-mail,
kanał Slack, lub inną metodę kontaktu. Musisz
również podać link do zlokalizowanego Kodeksu Postępowania Społeczności.
Uruchom swoje nowe lokalizacje
Gdy lokalizacja spełnia wymagania dotyczące przepływu pracy i
minimalnej wymaganej zawartości, SIG Docs wykonuje następujące czynności:
Przetłumaczone dokumenty muszą znajdować się we własnym podkatalogu content/**/, ale
powinny podążać tą samą ścieżką URL co źródła dla języka angielskiego. Na przykład, aby
przygotować samouczek Podstawy Kubernetesa do tłumaczenia na
język niemiecki, utwórz podkatalog w katalogu content/de/ i skopiuj angielskie źródło lub katalog:
Narzędzia tłumaczeniowe mogą przyspieszyć proces tłumaczenia. Na
przykład, niektórzy edytorzy oferują wtyczki do szybkiego tłumaczenia tekstu.
Uwaga:
Tłumaczenia generowane maszynowo nie są wystarczające same w sobie.
Lokalizacja wymaga rozbudowanej recenzji ludzkiej, aby spełnić minimalne standardy jakości.
Aby zapewnić dokładność gramatyczną i znaczeniową, członkowie Twojego zespołu ds.
lokalizacji powinni dokładnie przejrzeć wszystkie tłumaczenia generowane maszynowo przed publikacją.
Lokalizuj obrazy SVG
Projekt Kubernetes zaleca używanie obrazów wektorowych (SVG), gdy to możliwe, ponieważ zespołowi
zajmującemu się lokalizacją znacznie łatwiej jest je edytować. Jeśli
znajdziesz obraz rastrowy (ang. a raster image), który wymaga lokalizacji, rozważ najpierw
przerysowanie wersji angielskiej jako obrazu wektorowego, a następnie dokonanie lokalizacji.
Kiedy tłumaczysz tekst w obrazach SVG (Scalable Vector
Graphics), należy przestrzegać pewnych wytycznych, aby
zapewnić dokładność i zachować spójność między wersjami
językowymi. Obrazy SVG są powszechnie używane w dokumentacji
Kubernetesa do ilustrowania koncepcji, przepływów pracy i diagramów.
Identyfikacja tekstu do przetłumaczenia: Zacznij od zidentyfikowania
elementów tekstowych wewnątrz obrazu SVG, które wymagają tłumaczenia. Elementy te
zazwyczaj obejmują etykiety, podpisy, adnotacje lub jakikolwiek tekst przekazujący informacje.
Edycja plików SVG: Pliki SVG opierają się na XML, co oznacza, że można je
edytować za pomocą edytora tekstu. Jednak warto zauważyć, że większość
obrazów w dokumentacji Kubernetes konwertuje już tekst na krzywe w celu
uniknięcia problemów z kompatybilnością czcionek. W takich przypadkach zaleca się
użycie specjalistycznego oprogramowania do edycji SVG, takiego jak Inkscape,
aby edytować, otworzyć plik SVG i zlokalizować elementy tekstowe wymagające tłumaczenia.
Tłumaczenie tekstu: Zamień oryginalny tekst na przetłumaczoną
wersję w wybranym języku. Upewnij się, że przetłumaczony tekst dokładnie
oddaje zamierzone znaczenie i mieści się w dostępnej przestrzeni
obrazu. Rodzina czcionek Open Sans powinna być używana przy pracy z językami, które
korzystają z alfabetu łacińskiego. Możesz pobrać krój pisma Open Sans
stąd: Open Sans Typeface.
Konwersja tekstu na krzywe: Jak już wspomniano, aby rozwiązać
problemy z kompatybilnością czcionek, zaleca się konwersję przetłumaczonego
tekstu na krzywe lub ścieżki. Konwersja tekstu na krzywe zapewnia, że
końcowy obraz wyświetla przetłumaczony tekst poprawnie, nawet jeśli system
użytkownika nie posiada dokładnie tej samej czcionki użytej w oryginalnym pliku SVG.
Przeglądanie i testowanie: Po dokonaniu niezbędnych tłumaczeń i
konwersji tekstu na krzywe, zapisz i przejrzyj zaktualizowany obraz SVG, aby
upewnić się, że tekst jest prawidłowo wyświetlany i wyrównany. Sprawdź
Podglądaj swoje zmiany lokalnie.
Pliki źródłowe
Localizacje muszą być oparte na angielskich plikach z konkretnego wydania
wybranego przez zespół lokalizacyjny. Każdy zespół lokalizacyjny może
zdecydować, które wydanie będzie celem, określane poniżej jako docelowa wersja.
Gałąź main zawiera treści dla bieżącego wydania
v1.33. Zespół wydawniczy tworzy gałąź
release-1.33 przed następnym wydaniem: v1.34.
Ciągi znaków strony (ang. site strings) w i18n
Lokalizacje muszą zawierać treści
data/i18n/en/en.toml w
nowym pliku specyficznym dla danego języka. Na przykład
używając języka niemieckiego: data/i18n/de/de.toml.
Dodaj nowy katalog lokalizacyjny i plik do
data/i18n/. Na przykład, z niemieckim (de):
Przejrzyj komentarze na początku pliku, aby dostosować je do
swojego lokalnego języka, a następnie przetłumacz wartość każdego ciągu.
Na przykład, oto niemiecki tekst zastępczy dla formularza wyszukiwania:
[ui_search_placeholder]
other = "Suchen"
Lokalizacja ciągów tekstowych witryny pozwala dostosować tekst i funkcje w całej
witrynie: na przykład prawny tekst dotyczący praw autorskich w stopce na każdej stronie.
Przewodnik lokalizacyjny specyficzny dla języka
Jako zespół lokalizacyjny, możesz sformalizować najlepsze praktyki, które
stosuje twój zespół, tworząc przewodnik lokalizacyjny specyficzny dla danego języka.
Słownik terminów zlokalizowanych i niezlokalizowanych
Konwencje Markdown
Terminologia obiektów API Kubernetesa
Spotkania Zoom specyficzne dla języka
Jeśli projekt lokalizacyjny wymaga osobnego terminu spotkania, skontaktuj się z
współprzewodniczącym SIG Docs lub liderem technicznym, aby utworzyć nowe
cykliczne spotkanie w Zoomie i zaproszenie do kalendarza. Jest to potrzebne tylko
wtedy, gdy zespół jest wystarczająco duży, aby utrzymać i potrzebować osobnego spotkania.
Zgodnie z polityką CNCF, zespoły lokalizacyjne muszą przesyłać swoje
spotkania na playlistę YouTube SIG Docs. Współprzewodniczący SIG Docs lub Tech
Lead mogą pomóc w tym procesie, dopóki SIG Docs go nie zautomatyzuje.
Strategia gałęzi
Ponieważ projekty lokalizacyjne są wysoko współpracującymi
przedsięwzięciami, zachęcamy zespoły do pracy we wspólnych gałęziach
lokalizacyjnych - zwłaszcza na początku, kiedy lokalizacja nie jest jeszcze aktywna.
Na przykład, osoba zatwierdzająca w niemieckim zespole lokalizacyjnym
otwiera gałąź lokalizacyjną dev-1.12-de.1 bezpośrednio w
repozytorium kubernetes/website, bazując na gałęzi źródłowej dla Kubernetes v1.12.
Indywidualni współtwórcy otwierają
gałęzie z funkcjami w oparciu o gałąź lokalizacyjną.
Na przykład, niemiecki współtwórca otwiera pull request z
zmianami do kubernetes:dev-1.12-de.1 z username:local-branch-name.
Osoby zatwierdzające przeglądają i scalają gałęzie funkcji z gałęzią lokalizacji.
Okresowo, zatwierdzający łączy gałąź lokalizacyjną z jej
gałęzią źródłową, otwierając i zatwierdzając nowy pull request.
Upewnij się, że scaliłeś commity przed zatwierdzeniem pull request.
Powtarzaj kroki od 1 do 4 według potrzeb, aż lokalizacja zostanie
ukończona. Na przykład, kolejne niemieckie
gałęzie lokalizacyjne to: dev-1.12-de.2, dev-1.12-de.3, itd.
Zespoły muszą scalić zlokalizowane treści do tej
samej gałęzi, z której pochodziła treść. Na przykład:
Gałąź lokalizacji pochodząca z main musi zostać scalona z main.
Gałąź lokalizacyjna pochodząca z
release-1.32 musi być scalona z release-1.32.
Informacja:
Jeśli Twoja gałąź lokalizacyjna została utworzona z gałęzi main, ale
nie została scalona z main przed utworzeniem nowej gałęzi wydania
release-1.33, scal ją zarówno z main, jak i z nową gałęzią
wydania release-1.33. Aby scalić swoją gałąź lokalizacyjną z
nową gałęzią wydania release-1.33, musisz przełączyć gałąź
(ang. upstream branch) dla swojej gałęzi lokalizacyjnej na release-1.33.
Na początku każdego kamienia milowego zespołu warto
otworzyć zgłoszenie porównujące zmiany w upstream pomiędzy
poprzednią gałęzią lokalizacyjną a obecną gałęzią
lokalizacyjną. Istnieją dwa skrypty do porównywania zmian upstream.
upstream_changes.py
jest przydatne do sprawdzania zmian wprowadzonych do konkretnego pliku. I
diff_l10n_branches.py
jest przydatny do
tworzenia listy nieaktualnych plików dla konkretnej gałęzi lokalizacyjnej.
Podczas gdy tylko zatwierdzający mogą otworzyć nową gałąź
lokalizacyjną i scalać pull requesty, każdy może otworzyć pull request dla
nowej gałęzi lokalizacyjnej. Nie są wymagane żadne specjalne uprawnienia.
Aby uzyskać więcej informacji na temat pracy z forków lub bezpośrednio z
repozytorium, zobacz "fork and clone the repo".
Kontrybucje do projektu głównego
SIG Docs chętnie przyjmuje nową treść oraz korekty w angielskiej wersji źródłowej.
SIG Docs zaprasza do współpracy nad treścią i recenzjami wszystkich współtwórców. Każdy
może otworzyć pull request (PR) i każdy jest mile widziany do zgłaszania
problemów dotyczących treści lub komentowania pull requestów w trakcie ich realizacji.
Możesz również zostać członkiem,
recenzentem
lub zatwierdzającym.
Te role wymagają większego dostępu i wiążą się z pewnymi
obowiązkami w zakresie zatwierdzania i wprowadzania zmian. Zobacz
community-membership,
aby uzyskać więcej informacji na temat tego, jak działa członkostwo w społeczności Kubernetesa.
Reszta tego dokumentu przedstawia unikalne sposoby, w jakie te role funkcjonują
w ramach SIG Docs, które odpowiada za utrzymanie jednego z najbardziej
widocznych publicznie aspektów Kubernetesa -- strony internetowej i dokumentacji Kubernetes.
SIG Docs przewodniczący
Każda SIG, w tym SIG Docs, wybiera jednego lub więcej członków SIG do
pełnienia roli przewodniczących. Są oni punktami kontaktowymi pomiędzy SIG
Docs a innymi częściami organizacji Kubernetesa. Wymagają szerokiej wiedzy na
temat struktury projektu Kubernetes jako całości oraz tego, jak SIG
Docs działa w jej ramach. Zobacz Kierownictwo
z aktualną listą przewodniczących.
Zespoły i automatyzacja SIG Docs
Automatyzacja w SIG Docs opiera się na dwóch
różnych mechanizmach: zespołach GitHub i plikach OWNERS.
Zespoły GitHub
Istnieją dwie kategorie zespołów SIG Docs na GitHubie:
@sig-docs-{language}-owners są zatwierdzającymi i liderami
@sig-docs-{language}-reviews są recenzentami
Każdy z nich może być przywoływany za pomocą @nazwa w
komentarzach na GitHubie, aby komunikować się z wszystkimi w tej grupie.
Czasami zespoły Prow i GitHub nakładają się na siebie, ale nie
dokładnie pasują. W celu przypisywania problemów, pull requestów i
wsparcia zatwierdzeń PR, automatyzacja korzysta z informacji z plików OWNERS.
Te dwie wtyczki używają plików
OWNERS i
OWNERS_ALIASES w
głównym katalogu repozytorium kubernetes/website na
GitHubie, aby kontrolować jak prow działa w ramach tego repozytorium.
Plik OWNERS zawiera listę osób, które są recenzentami i zatwierdzającymi SIG
Docs. Pliki OWNERS mogą również istnieć w podkatalogach i mogą nadpisywać osoby,
które mogą działać jako recenzent lub zatwierdzający dla plików w tym podkatalogu
i jego potomnych. Więcej informacji na temat plików OWNERS można znaleźć w
OWNERS.
Ponadto, pojedynczy plik Markdown może wymieniać osoby przeglądające i zatwierdzające w swojej
sekcji front-matter, albo poprzez wymienienie indywidualnych nazw użytkowników GitHub, albo grup GitHub.
Połączenie plików OWNERS i danych front-matter w plikach Markdown
determinuje porady, jakie właściciele PR otrzymują od zautomatyzowanych
systemów, dotyczące tego, kogo poprosić o techniczny i redakcyjny przegląd ich PR.
Jak działa scalanie (ang. merging)
Kiedy pull request zostanie scalony z gałęzią używaną do publikowania treści, ta treść
jest publikowana na https://kubernetes.io. Aby zapewnić wysoką jakość naszych publikowanych treści,
ograniczamy scalanie pull requestów do zatwierdzających SIG Docs. Oto jak to działa.
Gdy pull request ma zarówno etykiety lgtm, jak i approve, nie ma etykiet
hold, i wszystkie testy przechodzą pomyślnie, pull request łączy się automatycznie.
Członkowie organizacji Kubernetesa i zatwierdzający z SIG Docs mogą
dodawać komentarze w celu wstrzymania automatycznemu scaleniu danego pull
requesta (poprzez dodanie komentarza /hold lub wstrzymanie komentarza /lgtm).
Każdy członek Kubernetesa może dodać etykietę lgtm, dodając komentarz /lgtm.
Tylko zatwierdzający SIG Docs mogą scalić pull request dodając
komentarz /approve. Niektórzy zatwierdzający pełnią również dodatkowe specyficzne
role, takie jak PR Wrangler
lub przewodniczący SIG Docs.
Co dalej?
Więcej informacji na temat wnoszenia wkładu w dokumentację Kubernetesa można znaleźć w:
Ta strona pokazuje, jak wnieść wkład do projektu kubernetes/kubernetes. Możesz
naprawiać błędy znalezione w dokumentacji API Kubernetesa lub w treściach dla
komponentów Kubernetesa, takich jak kubeadm, kube-apiserver i kube-controller-manager.
Jeśli zamiast tego chcesz wygenerować ponownie materiały źródłowe dla API Kubernetesa lub
komponentów kube-* z kodu źródłowego, zapoznaj się z następującymi instrukcjami:
Materiały źródłowe dla API Kubernetesa oraz komponentów kube-*, takich jak
kube-apiserver, kube-controller-manager, są automatycznie generowane z kodu
źródłowego w głównym repozytorium Kubernetes.
Kiedy zauważysz błędy w wygenerowanej dokumentacji, możesz
rozważyć stworzenie poprawki, aby naprawić je w projekcie źródłowym.
Sklonuj repozytorium Kubernetesa
Jeśli nie posiadasz jeszcze repozytorium kubernetes/kubernetes, pobierz je teraz:
mkdir $GOPATH/src
cd$GOPATH/src
go get github.com/kubernetes/kubernetes
Określ katalog bazowy swojej kopii repozytorium
kubernetes/kubernetes. Na przykład, jeśli
wykonywano wcześniejszy krok w celu pobrania tego repozytorium, to
twój katalog bazowy to $GOPATH/src/github.com/kubernetes/kubernetes.
Pozostałe kroki odnoszą się do twojego katalogu bazowego jako <k8s-base>.
Określ katalog główny swojego klonu repozytorium
kubernetes-sigs/reference-docs. Na
przykład, jeśli wykonałeś wcześniejszy krok, aby pobrać repozytorium, twój
katalog główny to $GOPATH/src/github.com/kubernetes-sigs/reference-docs.
Pozostałe kroki odnoszą się do twojego katalogu głównego jako <rdocs-base>.
Edytowanie kodu źródłowego Kubernetesa
Dokumentacja materiałów źródłowych API Kubernetesa jest automatycznie
generowana z specyfikacji OpenAPI, która jest tworzona na podstawie kodu źródłowego
Kubernetesa. Jeśli chcesz zmienić dokumentację materiałów
źródłowych API, pierwszym krokiem jest zmiana w kodzie źródłowym Kubernetesa.
Dokumentacja dla komponentów kube-* jest także generowana z
oryginalnego kodu źródłowego. Musisz zmienić kod związany z
komponentem, który chcesz naprawić, aby naprawić generowaną dokumentację.
Wprowadź zmiany do kodu źródłowego w repozytorium głównym
Informacja:
Poniższe kroki są przykładowe, nie stanowią ogólnej
procedury. Szczegóły w Twojej sytuacji będą się różnić.
Oto przykład edytowania komentarza w kodzie źródłowym Kubernetesa.
W swoim lokalnym repozytorium kubernetes/kubernetes,
przełącz się na domyślną gałąź i upewnij się, że jest aktualna:
cd <k8s-base>
git checkout master
git pull https://github.com/kubernetes/kubernetes master
Przypuśćmy, że ten plik źródłowy w tej domyślnej gałęzi zawiera literówkę "atmost":
W swoim lokalnym środowisku otwórz plik types.go i zmień "atmost" na "at most".
Zweryfikuj, czy zmieniłeś plik:
git status
Wynik pokazuje, że znajdujesz się na gałęzi
głównej, a plik źródłowy types.go został zmodyfikowany:
On branch master
...
modified: staging/src/k8s.io/api/apps/v1/types.go
Zatwierdź swój edytowany plik
Uruchom git add i git commit, aby zatwierdzić zmiany, które do tej pory wprowadziłeś. W
kolejnym kroku wykonasz drugi commit. Ważne jest, aby utrzymać zmiany rozdzielone na dwa commity.
Generowanie specyfikacji OpenAPI i powiązanych plików
Sprawdź zawartość pliku api/openapi-spec/swagger.json, aby upewnić
się, że literówka została poprawiona. Na przykład, możesz uruchomić
git diff -a api/openapi-spec/swagger.json. Jest to ważne, ponieważ
swagger.json jest wejściem do drugiego etapu procesu generowania materiałów źródłowych.
Uruchom git add i git commit, aby zatwierdzić swoje zmiany. Teraz masz dwa commity: jeden, który
zawiera edytowany plik types.go, oraz drugi, który zawiera wygenerowaną specyfikację
OpenAPI i powiązane pliki. Zachowaj te dwa commity oddzielnie. To znaczy, nie łącz tych commitów.
Prześlij swoje zmiany jako pull request
do gałęzi
master w repozytorium kubernetes/kubernetes.
Monitoruj swój pull
request (PR) i odpowiadaj na uwagi recenzentów w miarę
potrzeby. Kontynuuj monitorowanie swojego PR, aż zostanie ono scalone.
PR 57758 jest
przykładem pull requesta, który naprawia literówkę w kodzie źródłowym Kubernetesa.
Informacja:
Określenie właściwego pliku źródłowego do zmiany może być
skomplikowane. W podanym przykładzie, główny plik źródłowy znajduje się w
katalogu staging w repozytorium kubernetes/kubernetes. Jednak w Twojej
sytuacji katalog staging może nie być właściwym miejscem do jego
znalezienia. Aby uzyskać wskazówki, sprawdź pliki README w
repozytorium kubernetes/kubernetes
oraz w powiązanych repozytoriach, takich jak
kubernetes/apiserver.
Zrób cherry pick swojego commita do gałęzi wydania
W poprzednim rozdziale edytowałeś plik w głównej gałęzi (master branch) i uruchomiłeś
skrypty, aby wygenerować specyfikację OpenAPI oraz powiązane pliki. Następnie przesłałeś swoje
zmiany w PR (ang. pull request) do głównej gałęzi repozytorium kubernetes/kubernetes. Teraz
załóżmy, że chcesz wprowadzić swoją zmianę także do gałęzi wydania (release branch). Na przykład,
załóżmy, że główna gałąź jest używana do opracowywania wersji Kubernetesa
1.33, a Ty chcesz wprowadzić swoją zmianę również do gałęzi release-1.32.
Przypomnij sobie, że twój pull request zawiera dwa commity: jeden dla edycji types.go i jeden dla
plików wygenerowanych przez skrypty. Następnym krokiem jest zaproponowanie cherry pick twojego
pierwszego commita do gałęzi release-1.32. Chodzi o to, aby cherry pickować commit,
który edytował types.go, ale nie commit, który zawiera wyniki uruchomienia skryptów. Instrukcje
znajdziesz w Propose a Cherry Pick.
Informacja:
Propozycja cherry pick wymaga posiadania uprawnienia do ustawienia etykiety i
kamienia milowego w swoim PR (ang. pull request). Jeśli nie masz tych uprawnień,
będziesz musiał współpracować z kimś, kto może ustawić etykietę i kamień milowy za Ciebie.
Kiedy masz w toku swój pull request dla zastosowania cherry picka ze swoim jednym
commitem do gałęzi release-1.32, kolejnym krokiem jest uruchomienie tych
skryptów w gałęzi release-1.32 w swoim lokalnym środowisku.
Teraz dodaj commit do swojego pull requesta związanego z cherry pickiem, który
zawiera niedawno wygenerowaną specyfikację OpenAPI i powiązane pliki. Monitoruj
swojego pull requesta, aż zostanie scalony z gałęzią release-1.32.
W tym momencie zarówno gałąź master, jak i gałąź release-1.32 mają zaktualizowany plik
types.go oraz zestaw wygenerowanych plików, które odzwierciedlają zmiany wprowadzone do types.go. Należy zauważyć, że
wygenerowana specyfikacja OpenAPI i inne wygenerowane pliki w gałęzi release-1.32 niekoniecznie są
takie same jak wygenerowane pliki w gałęzi master. Wygenerowane pliki w gałęzi release-1.32
zawierają elementy API wyłącznie z Kubernetesa 1.32. Wygenerowane pliki w gałęzi master mogą
zawierać elementy API, które nie znajdują się w 1.32, ale są w trakcie rozwoju dla 1.33.
Generowanie opublikowanych materiałów źródłowych
Poprzednia sekcja pokazała, jak edytować plik
źródłowy, a następnie generować kilka plików, w tym
api/openapi-spec/swagger.json w repozytorium
kubernetes/kubernetes. Plik swagger.json to plik definicji
OpenAPI używany do generowania materiałów źródłowych API.
Docker (Wymagany tylko do odniesień do poleceń kubectl)
Twoja zmienna środowiskowa PATH musi zawierać wymagane narzędzia do budowania, takie jak binaria Go i python.
Musisz wiedzieć, jak utworzyć pull requesta do repozytorium na GitHubie.
Wymaga to utworzenia własnego forka repozytorium. Aby uzyskać więcej informacji,
zobacz Praca z lokalnej kopii.
Skonfiguruj lokalne repozytoria
Utwórz lokalną przestrzeń roboczą i ustaw swoje GOPATH:
Repozytorium kubernetes/kubernetes dostarcza kod źródłowy kubectl oraz kustomize.
Określ katalog bazowy twojej kopii repozytorium
kubernetes/kubernetes. Na przykład,
jeśli postępowałeś zgodnie z poprzednim krokiem, aby pobrać
repozytorium, twój katalog bazowy to $GOPATH/src/k8s.io/kubernetes.
Kolejne kroki odwołują się do twojego katalogu bazowego jako <k8s-base>.
Określ katalog bazowy klonu Twojego repozytorium
kubernetes/website. Na przykład, jeśli
wykonałeś poprzedni krok, aby pobrać repozytorium, Twoim katalogiem bazowym
jest $GOPATH/src/github.com/<your-username>/website.
Kolejne kroki odnoszą się do Twojego katalogu bazowego jako <web-base>.
Określ katalog główny dla Twojej kopii repozytorium
kubernetes-sigs/reference-docs. Na przykład,
jeśli postępowałeś zgodnie z poprzednim krokiem, aby uzyskać repozytorium,
Twoim katalogiem głównym będzie $GOPATH/src/github.com/kubernetes-sigs/reference-docs.
Dalsze kroki odnoszą się do Twojego katalogu głównego jako <rdocs-base>.
W swoim lokalnym repozytorium k8s.io/kubernetes przejdź do interesującej Cię
gałęzi i upewnij się, że jest ona aktualna. Na przykład, jeśli chcesz wygenerować
dokumentację dla Kubernetesa 1.32.0, możesz użyć tych poleceń:
cd <k8s-base>
git checkout v1.32.0
git pull https://github.com/kubernetes/kubernetes 1.32.0
Jeśli nie musisz edytować kodu źródłowego kubectl, postępuj zgodnie z
instrukcjami dotyczącymi Ustawiania zmiennych kompilacji.
Edytowanie kodu źródłowego kubectl
Materiały źródłowe polecenia kubectl są automatycznie generowana z kodu źródłowego kubectl.
Jeśli chcesz zmienić materiały źródłowe, pierwszym krokiem jest zmiana
jednego lub więcej komentarzy w kodzie źródłowym kubectl. Wprowadź zmianę w swoim
lokalnym repozytorium kubernetes/kubernetes, a następnie zgłoś pull requesta do
gałęzi master na github.com/kubernetes/kubernetes.
PR 56673 jest
przykładem pull requesta, który poprawia literówkę w kodzie źródłowym kubectl.
Monitoruj swój pull request (PR) i odpowiadaj na komentarze recenzentów. Kontynuuj
monitorowanie swojego PR, aż zostanie scalony z docelową gałęzią w repozytorium kubernetes/kubernetes.
Zrób cherry pick do gałęzi wydania
Twoja zmiana znajduje się teraz w głównej gałęzi, która jest używana do
rozwoju następnego wydania Kubernetesa. Jeśli chcesz, aby twoja
zmiana pojawiła się w wersji dokumentacji Kubernetesa, która została już
wydana, musisz zaproponować włączenie twojej zmiany do gałęzi wydania.
Na przykład, załóżmy, że gałąź master jest używana do rozwijania Kubernetes
1.33 i chcesz przenieść swoją zmianę do gałęzi
release-1.32. Aby uzyskać instrukcje, jak to zrobić, zobacz
Proponowanie Cherry Pick.
Monitoruj swój cherry pick pull request, aż zostanie scalone z gałęzią wydania.
Informacja:
Proponowanie cherry pick wymaga posiadania uprawnień do ustawiania etykiety oraz
kamienia milowego w swoim pull requeście. Jeśli nie posiadasz tych uprawnień,
będziesz musiał współpracować z kimś, kto może ustawić etykietę i kamień milowy za Ciebie.
Ustaw zmienne budowania
Przejdź do <rdocs-base>. W swoim wierszu poleceń ustaw następujące zmienne środowiskowe.
Ustaw K8S_ROOT na <k8s-base>.
Ustaw K8S_WEBROOT na <web-base>.
Ustaw K8S_RELEASE na wersję dokumentacji, którą chcesz zbudować. Na przykład,
jeśli chcesz zbudować dokumentację dla Kubernetesa
1.32, ustaw K8S_RELEASE na 1.32.
Uruchomienie budowania (ang. build target) createversiondirs tworzy katalog z
wersjonowaniem i kopiuje pliki konfiguracyjne kubectl dotyczące materiałów źródłowych do tego
katalogu. Nazwa katalogu z wersjonowaniem jest zgodna z wzorcem v<major>_<minor>.
W katalogu <rdocs-base>, uruchom następujący cel budowania:
cd <rdocs-base>
make createversiondirs
Sprawdź tag wydania w k8s.io/kubernetes
W swoim lokalnym repozytorium <k8s-base>, przejdź do gałęzi, która zawiera
wersję Kubernetesa, którą chcesz udokumentować. Na przykład, jeśli chcesz
wygenerować dokumentację dla Kubernetesa 1.32.0, przejdź do tagu v1.32.
Upewnij się, że Twoja lokalna gałąź jest aktualna.
cd <k8s-base>
git checkout v1.32.0
git pull https://github.com/kubernetes/kubernetes v1.32.0
Uruchom kod generowania dokumentacji
W lokalnym katalogu <rdocs-base>, uruchom cel budowania (ang. build target) copycli. Komenda działa z uprawnieniami root:
cd <rdocs-base>
make copycli
Polecenie copycli czyści tymczasowy katalog kompilacji, generuje pliki poleceń kubectl i
kopiuje zbiorczą stronę HTML materiałów źródłowych poleceń kubectl oraz zasoby do <web-base>.
Zlokalizuj wygenerowane pliki
Zweryfikuj, czy te dwa pliki zostały wygenerowane:
Uruchom git add i git commit, aby zatwierdzić pliki.
Utwórz pull requesta
Utwórz pull requesta do repozytorium kubernetes/website.
Monitoruj swój pull request i odpowiadaj na komentarze z przeglądu.
Kontynuuj monitorowanie swojego pull requesta aż do momentu jego włączenia do głównej gałęzi kodu.
Kilka minut po włączeniu twojego pull requesta, zaktualizowane tematy
materiałów źródłowych będą widoczne w opublikowanej dokumentacji.
Docker (Wymagany tylko do odniesień do poleceń kubectl)
Twoja zmienna środowiskowa PATH musi zawierać wymagane narzędzia do budowania, takie jak binaria Go i python.
Musisz wiedzieć, jak utworzyć pull requesta do repozytorium na GitHubie.
Wymaga to utworzenia własnego forka repozytorium. Aby uzyskać więcej informacji,
zobacz Praca z lokalnej kopii.
8 - Styl dokumentacji
Tematy w tej sekcji zawierają wskazówki dotyczące stylu
pisania, formatowania treści i organizacji, a także
korzystania ze specyficznych dostosowań Hugo dla dokumentacji Kubernetesa.
8.1 - Typy treści
Dokumentacja Kubernetesa obejmuje kilka typów treści stron:
Pojęcia i koncepcje (ang. Concept)
Zadanie (ang. Task)
Samouczek (ang. Tutorial)
Materiały źródłowe (ang. Reference)
Sekcje treści
Każdy typ strony zawiera szereg sekcji zdefiniowanych przez
komentarze Markdown i nagłówki HTML. Możesz dodać nagłówki
do swojej strony za pomocą kodu heading. Komentarze i
nagłówki pomagają utrzymać odpowiednią strukturę strony dla danego typu.
Przykłady komentarzy w Markdown definiujących sekcje strony:
<!-- overview -->
<!-- body -->
Aby utworzyć typowe nagłówki na swoich
stronach, użyj kodu heading z nazwą nagłówka.
Przykłady nazw nagłówków:
whatsnext - co dalej
prerequisites - wymagania wstępne
objectives - cele
cleanup - sprzątanie
synopsis - streszczenie
seealso - zobacz także
options - opcje
Na przykład, aby utworzyć nagłówek whatsnext, dodaj kod nagłówka z nazwą "whatsnext":
## {{% heading "whatsnext" %}}
Możesz zadeklarować nagłówek prerequisites w następujący sposób:
## {{% heading "prerequisites" %}}
Kod heading oczekuje jednego parametru typu
string. Ten parametr nagłówka odpowiada prefiksowi zmiennej
w plikach i18n/<lang>/<lang>.toml. Na przykład:
i18n/en/en.toml:
[whatsnext_heading]
other = "What's next"
i18n/ko/ko.toml:
[whatsnext_heading]
other = "다음 내용"
Typy zawartości
Każdy typ zawartości nieformalnie definiuje swoją oczekiwaną strukturę
strony. Twórz zawartość strony, korzystając z sugerowanych sekcji strony.
Pojęcie (ang. Concept)
Strona z pojęciami wyjaśnia określony aspekt Kubernetesa. Na
przykład, strona koncepcyjna może opisywać obiekt Deployment w
Kubernetesie i wyjaśniać jego rolę jako aplikacji po wdrożeniu,
skalowaniu i aktualizacji. Zazwyczaj strony koncepcyjne nie
zawierają instrukcji krok po kroku, lecz odsyłają do zadań lub samouczków.
Aby napisać nową stronę z pojęciem, utwórz plik Markdown w
podkatalogu katalogu /content/en/docs/concepts, z następującymi sekcjami:
Strony koncepcyjne są podzielone na trzy sekcje:
Sekcja strony
overview - przegląd
body - treść
whatsnext - co dalej
Sekcje overview i body pojawiają się jako komentarze na stronie z
koncepcjami. Możesz dodać sekcję whatsnext do swojej strony za pomocą kodu heading.
Wypełnij każdą sekcję treścią. Postępuj zgodnie z tymi wytycznymi:
Organizuj treści za pomocą nagłówków H2 i H3.
Dla overview, ustaw kontekst tematu za pomocą pojedynczego akapitu.
Dla body wyjaśnij koncepcję.
Dla whatsnext, podaj wypunktowaną listę tematów (maksymalnie 5), aby dowiedzieć się więcej o koncepcji.
Strona adnotacje jest opublikowanym przykładem strony koncepcyjnej.
Zadanie (ang. Task)
Strony opisujące wykonywanie zadań zawierają minimum
wyjaśnień, ale zwykle podają odnośniki do
dokumentacji objaśniającej pojęcia i szerszy kontekst danego tematu.
Aby napisać nową stronę zadania, utwórz plik Markdown w
podkatalogu katalogu /content/en/docs/tasks, z następującymi sekcjami:
Sekcja strony
overview - przegląd
prerequisites - wymagania wstępne
steps - kroki
discussion - dyskusja
whatsnext - co dalej
Sekcje overview, steps i discussion pojawiają się jako komentarze
na stronie zadania. Możesz dodać sekcje
prerequisites i whatsnext do swojej strony za pomocą kodu heading.
Użyj nagłówków poziomu H2 lub niższego (z dwoma wiodącymi
znakami #). Sekcje są automatycznie tytułowane przez szablon.
Dla overview użyj akapitu, aby ustawić kontekst dla całego tematu.
Dla prerequisites używaj list punktowanych, kiedy to możliwe. Zaczynaj dodawać dodatkowe
wymagania wstępne poniżej include. Domyślne wymagania wstępne obejmują działający klaster Kubernetesa.
Dla steps używaj numerowanych list.
Do omówienia użyj standardowej treści, aby rozwinąć
informacje zawarte w sekcji steps.
Dla whatsnext, podaj listę punktowaną z maksymalnie 5 tematami,
które mogą zainteresować czytelnika jako kolejne tematy do przeczytania.
Strona samouczka pokazuje, jak osiągnąć cel, który jest bardziej złożony
niż pojedyncze zadanie. Zazwyczaj strona samouczka składa się z kilku
sekcji, z których każda zawiera sekwencję kroków. Na przykład samouczek może
przeprowadzać użytkownika przez przykładowy kod ilustrujący określoną
funkcję Kubernetesa. Samouczki mogą zawierać ogólne wyjaśnienia, ale powinny
odsyłać do powiązanych tematów koncepcyjnych w celu dogłębnego omówienia zagadnienia.
Aby napisać nową stronę samouczka, utwórz plik Markdown w
podkatalogu katalogu /content/en/docs/tutorials, z następującymi sekcjami:
Sekcja strony
overview - przegląd
prerequisites - wymagania wstępne
objectives - cele
lessoncontent - treść lekcji
cleanup - sprzątanie
whatsnext - co dalej
Sekcje overview, objectives i lessoncontent pojawiają się
jako komentarze na stronie samouczka. Możesz dodać sekcje
prerequisites, cleanup i whatsnext do swojej strony za pomocą kodu heading.
Każde narzędzie Kubernetesa ma swoją stronę materiałów źródłowych (ang. reference page), gdzie można znaleźć jego opis i
listę dostępnych opcji. Dokumentacja ta jest generowana przez skrypty, które automatycznie pobierają informacje z poleceń narzędzia.
Strona z odniesieniem do narzędzia ma kilka możliwych sekcji:
Sekcja strony
streszczenie
opcje
opcje z nadrzędnych poleceń
przykłady
zobacz także
Przykłady opublikowanych stron referencyjnych narzędzi to:
Ta strona zakłada, że rozumiesz, jak
tworzyć nowe treści i recenzować pracę innych,
i jesteś gotów nauczyć się więcej
sposobów, jak wnosić wkład. Musisz umieć używać klienta wiersza
poleceń Git jak rownież inne narzędzia do wykonania niektórych z tych zadań.
Po tym, jak przez jakiś czas będziesz wnosić wkład do dokumentacji Kubernetesa,
możesz mieć pomysły na ulepszenie Przewodnika Stylu,
Przewodnika Treści,
narzędzi wykorzystywanych do tworzenia dokumentacji, stylu strony internetowej,
procesów przeglądania i scalania pull requestów, lub innych aspektów dokumentacji. Dla
maksymalnej przejrzystości, tego rodzaju propozycje muszą być omówione podczas
spotkania SIG Docs lub na liście mailingowej kubernetes-sig-docs.
Dodatkowo, może pomóc posiadanie kontekstu
dotyczącego obecnego sposobu działania i przyczyn podejmowania
wcześniejszych decyzji, zanim zaproponujesz radykalne zmiany. Najszybszym sposobem
uzyskania odpowiedzi na pytania dotyczące obecnego działania dokumentacji jest
zadanie ich na kanale #sig-docs na Slacku kubernetes.slack.com
Po odbyciu dyskusji i osiągnięciu porozumienia przez SIG w sprawie
pożądanego wyniku, możesz pracować nad proponowanymi zmianami w sposób
najbardziej odpowiedni. Na przykład, aktualizacja wytycznych stylu lub
funkcjonalności strony internetowej może wymagać otwarcia pull requesta, podczas gdy
zmiana związana z testowaniem dokumentacji może wymagać współpracy z sig-testing.
Koordynowanie dokumentacji do wydania Kubernetes
Zatwierdzający
SIG Docs mogą koordynować dokumentację dla wydania Kubernetesa.
Każde wydanie Kubernetesa jest koordynowane przez zespół osób
uczestniczących w sig-release (ang. Special Interest Group - SIG).
Inni członkowie zespołu wydania dla danego wydania to ogólny lider
wydania, a także przedstawiciele sig-testing i innych. Aby
dowiedzieć się więcej o procesach wydania Kubernetesa, odwiedź
https://github.com/kubernetes/sig-release.
Przedstawiciel SIG Docs dla danego wydania koordynuje następujące zadania:
Monitoruje arkusz śledzący funkcje w poszukiwaniu nowych lub zmienionych
funkcji mających wpływ na dokumentację. Jeśli dokumentacja dla danej
funkcji nie będzie gotowa na wydanie, funkcja może nie zostać dopuszczona do wydania.
Uczestniczy regularnie w spotkaniach sig-release i
przekazuje aktualizacje dotyczące statusu dokumentacji dla wydania.
Przegląda i poprawia dokumentację funkcji
napisaną przez SIG odpowiedzialny za wdrożenie tej funkcji.
Scala pull requesty związane z wydaniem i
utrzymuje gałąź Git na potrzeby wydania.
Mentoruje innych współtwórców SIG Docs, którzy chcą nauczyć
się, jak pełnić tę rolę w przyszłości. Jest to znane jako "shadowing".
Publikuje zmiany w dokumentacji związane z
wydaniem, gdy artefakty wydania zostaną opublikowane.
Koordynowanie wydania to zazwyczaj zobowiązanie na 3-4 miesiące, a
obowiązek ten jest rotacyjnie przejmowany przez zatwierdzających SIG Docs.
Pomoganie jako Ambasador Nowego Współtwórcy
Zatwierdzający
SIG Docs mogą pełnić rolę Ambasadorów dla Nowych Współtwórców.
Ambasadorzy Nowych Współtwórców witają nowych współtwórców w
SIG-Docs, proponują PR-y nowym współtwórcom i mentoruują nowych współtwórców
podczas składania przez nich pierwszych kilku PR-ów.
Obowiązki Ambasadorów Nowych Współtwórców obejmują:
Prowadzenie comiesięcznego spotkania w celu pomocy i mentorowania nowych współtwórców.
Obecni Ambasadorzy Nowych Współtwórców są ogłaszani na każdym spotkaniu SIG-Docs oraz w kanale Kubernetes #sig-docs.
Sponsoruj nowego współtwórcę
Recenzenci
SIG Docs mogą sponsorować nowych współtwórców.
Po pomyślnym przesłaniu 5 merytorycznych pull requestów do jednego lub
więcej repozytoriów Kubernetesa, nowy współtwórca może
ubiegać się o członkostwo
w organizacji Kubernetes. Członkostwo
współtwórcy musi być poparte przez dwóch sponsorów, którzy są już recenzentami.
Nowi współtwórcy dokumentacji mogą ubiegać się o sponsorów, pytając na
kanale #sig-docs w instancji Kubernetes na Slacku
lub na liście mailingowej SIG Docs.
Jeśli jesteś pewny pracy
wnioskodawcy, możesz dobrowolnie go sponsorować. Gdy złożą swoje podanie o
członkostwo, odpowiedz na aplikację z "+1" i dołącz szczegóły, dlaczego uważasz, że
wnioskodawca jest odpowiednią osobą do członkostwa w organizacji Kubernetes.
Pełnij rolę współprzewodniczącego SIG
Członkowie SIG Docs
mogą pełnić funkcję współprzewodniczącego SIG Docs.
Wymagania wstępne
Członek zespołu Kubernetesa musi spełniać następujące wymagania, aby zostać współprzewodniczącym:
Rozumieć przepływy pracy i narzędzi SIG Docs: git, Hugo, lokalizacja, podprojekt bloga
Być zatwierdzonym przez społeczność SIG Docs bezpośrednio lub poprzez konsensus bierny.
Poświać co najmniej 5 godzin tygodniowo (a często więcej) na pełnienie roli przez minimum 6 miesięcy
Odpowiedzialności
Rola współprzewodniczącego jest rolą usługową: współprzewodniczący buduje potencjał współpracowników, zajmuje się procesami i polityką, organizuje i prowadzi spotkania, planuje "PR wranglers", promuje dokumentację w społeczności Kubernetesa, dba o to, aby dokumentacja odnosiła sukcesy w cyklach wydawniczych Kubernetes oraz utrzymuje SIG Docs skupione na efektywnych priorytetach.
Obowiązki obejmują:
Koncentrowanie działań SIG Docs na tym, by dzięki świetnej dokumentacji zwiększać komfort i satysfakcję programistów.
Bycie przykładem w przestrzeganiu kodeksu postępowania społeczności i dbanie, by inni członkowie SIG również się do niego stosowali.
Douczanie się i ustalanie najlepszych praktyk dla SIG, aktualizując wytyczne dotyczące wkładu
Planowanie i prowadzenie spotkań SIG: cotygodniowe aktualizacje statusu, kwartalne sesje retrospekcyjne/planistyczne oraz inne według potrzeby
Planowanie i realizacja sprintów dokumentacyjnych podczas wydarzeń KubeCon i innych konferencji
Rekrutowanie i działanie jako rzecznik SIG Docs w imieniu CNCF i jego platynowych partnerów, w tym Google, Oracle, Azure, IBM i Huawei.
Utrzymywanie płynnego działania SIG
Prowadzenie efektywnych spotkań
Aby zaplanować i przeprowadzać efektywne spotkania, te wytyczne pokazują, co robić, jak to robić i dlaczego.
Ten dashboard został zbudowany przy użyciu Google Looker Studio i pokazuje informacje zebrane na kubernetes.io przy użyciu Google Analytics 4 od sierpnia 2022 roku.
Korzystanie z dashboardu
Domyślnie dashboard pokazuje wszystkie zebrane analizy z ostatnich 30 dni. Użyj selektora dat, aby zobaczyć dane z innego zakresu dat. Inne opcje filtrowania pozwalają na przeglądanie danych w oparciu o lokalizację użytkownika, urządzenie używane do dostępu do witryny, tłumaczenie używanych dokumentów i więcej.
Jeśli zauważysz problem z tym dashboardem lub chcesz zgłosić jakieś usprawnienia, proszę otwórz zgłoszenie.
11 - Tłumaczenie dokumentacji na język polski
Na tej stronie znajdziesz wskazówki i wytyczne przydatne przy tłumaczeniu dokumentacji Kubernetesa na język polski.
Staramy się, aby styl tłumaczenia był jak najbardziej naturalny. W przypadku dokumentacji technicznej może być to trudne zadanie,
szczególnie gdy chcemy utrzymać precyzję tłumaczenia.
Zależy nam na unikaniu sytuacji, kiedy tekst zaczyna sprawiać wrażenie przetłumaczonego maszynowo.
Pamiętajmy też, że oficjalna wykładnia zawsze znajduje się w tekście angielskim. Polskie tłumaczenie ma ułatwić pierwsze kroki osobom,
które zaczynają swoją przygodę z Kubernetesem.
Wytyczne szczegółowe
Odmiana terminu Kubernetes
Kubernetes jest nazwą własną, liczba pojedyncza, rodzaj męski. Odmieniamy: Kubernetesa, Kubernetesem itp.
W uzasadnionych przypadkach można stosować też "system Kubernetes".
Odmiana terminów Pod, Deployment
Odmieniamy zgodnie z ogólnymi zasadami - poda, deploymentu itp.
Ujednolicony słownik
W sieci dostępne są słowniki terminów informatycznych. Poniższa tabela zawiera słowa specyficzne dla Kubernetesa i inne często używane wyrażenia.
