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.
Jeśli chcesz dowiedzieć się, jak wnosić wkład do dokumentacji lub innych części tej strony, przeczytaj Wnoszenie wkładu do dokumentacji Kubernetes. Jeśli chcesz pomóc przy oficjalnych blogach Kubernetesa, przeczytaj Wnoszenie wkładu do blogów Kubernetesa.
Możesz również przeczytać CNCF stronę o wnoszeniu wkładu do 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:
Zespół blogowy, będący częścią SIG Docs, pomaga zarządzać oficjalnymi blogami. Aby dowiedzieć się więcej, przeczytaj jak współtworzyć blogi 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.
Aby zaangażować się w tworzenie dokumentacji:
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 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ń.
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.
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
kubernetes/website,
aby znaleźć problemy, które są dobrymi punktami wyjścia.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:
#sig-docs na Slacku Kubernetes.
I nie zapomnij się przedstawić!kubernetes-sig-docs,
gdzie odbywają się szersze dyskusje i zapisywane są oficjalne decyzje.#sig-docs i dodawane do
kalendarza spotkań społeczności Kubernetes.
Będziesz musiał pobrać klienta Zoom lub zadzwonić z telefonu.#sig-docs. Możesz wnieść swój wkład w dowolny z wątków do 24 godzin po ogłoszeniu spotkania.Naucz się pracować z lokalną kopią repozytorium.
Zredaguj funkcje w wydaniu.
Weź udział w SIG Docs i zostań członkiem lub recenzentem.
Rozpocznij lub pomóż w lokalizacji.
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.
Jeśli chcesz zasugerować ulepszenia do istniejącej treści lub zauważysz błąd, otwórz zgłoszenie.
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.
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:
Pamiętaj o następujących rzeczach przy zgłaszaniu problemu:
#. Na przykład: Introduced by #987654.Ta sekcja zawiera informacje, które powinieneś znać przed dodaniem nowej treści.
Istnieją również dedykowane strony dotyczące pisania studiów przypadków oraz artykułów na bloga.
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.
/content/en/docs/. Część dokumentacji referencyjnej jest
automatycznie generowana ze skryptów w katalogu update-imported-docs/./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/.Wszyscy współtwórcy Kubernetesa muszą przeczytać Przewodnik dla Współtwórców i podpisać Umowę Licencyjną Współtwórcy (CLA) .
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.
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.36, należy dodać zmiany w dokumentacji do gałęzi dev-1.36. |
| Treść w innych językach (lokalizacje) | Użyj konwencji danej lokalizacji. Zobacz Strategia rozgałęzień lokalizacji po więcej informacji. |
Jeśli nadal nie masz pewności, którą gałąź wybrać, zapytaj na #sig-docs na Slacku.
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.
Katalog narzędzi dla współtwórców dokumentacji
w repozytorium
kubernetes/website zawiera narzędzia, wspierające proces współtworzenia dokumentacji.
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.
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.
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 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:
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.
dev-1.36 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.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.
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.
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.
Jeśli Twój PR nie został jeszcze scalony z gałęzią dev-1.36
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).
W tej sekcji opisano, jak dokonać przeglądu treści.
Ta strona pokazuje, jak zlokalizować dokumentację na inny język.
Możesz pomóc w dodaniu lub poprawieniu treści istniejącej lokalizacji. W Kubernetes Slack, możesz znaleźć kanał dla każdej lokalizacji. Istnieje również ogólny kanal Slack dla lokalizacji dokumentacji SIG, gdzie możesz się przywitać.
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.
Najpierw, utwórz własny fork repozytorium kubernetes/website.
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>.
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.
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.
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.
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.
Następnie dodaj swój zespół lokalizacyjny Kubernetesa do
sig-docs/teams.yaml.
Aby uzyskać przykład dodawania zespołu lokalizacyjnego, zobacz PR
dodający hiszpański zespół lokalizacyjny.
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.
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.
Aby uzyskać przykład dodawania etykiety, zobacz PR dotyczący dodawania etykiety języka włoskiego.
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:
[languages.de]
title = "Kubernetes"
languageName = "Deutsch (German)"
weight = 5
contentDir = "content/de"
languagedirection = "ltr"
[languages.de.params]
time_format_blog = "02.01.2006"
language_alternatives = ["en"]
description = "Produktionsreife Container-Orchestrierung"
languageNameLatinScript = "Deutsch"
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 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 i18n
dla zlokalizowanych ciągów
; spójrz na istniejące lokalizacje jako przykład.
Na przykład, dla języka niemieckiego, ciągi znaków znajdują się w pliku i18n/de/de.toml.
Otwórz PR w repozytorium cncf/foundation,
aby
dodać kodeks postępowania w swoim języku.
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ą:
sig-docs-**-reviews utworzony w Dodaj swój zespół lokalizacyjny w GitHub.sig-docs-**-owners utworzony w Dodaj swój zespół lokalizacyjny w GitHub.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-reviews
approvers:
- sig-docs-es-owners
labels:
- area/localization
- 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.
Dla każdego zespołu dodaj listę użytkowników GitHub, o której mowa w Dodaj swój zespół lokalizacyjny w GitHub, w porządku alfabetycznym.
--- a/OWNERS_ALIASES
+++ b/OWNERS_ALIASES
@@ -48,6 +48,14 @@ aliases:
- stewart-yu
- xiangpengzhao
- zhangxiaoyu-zidif
+ sig-docs-es-owners: # Admins for Spanish content
+ - alexbrand
+ - raelga
+ sig-docs-es-reviews: # PR reviews for Spanish content
+ - alexbrand
+ - electrocucaracha
+ - glo-pena
+ - raelga
sig-docs-fr-owners: # Admins for French content
- perriea
- remyleone
Następnie, otwórz pull request
(PR), aby dodać lokalizację do repozytorium
kubernetes/website. PR musi zawierać całą
wymaganą minimalną zawartość, zanim może zostać zatwierdzony.
Aby uzyskać przykład dodawania nowej lokalizacji, zobacz PR umożliwiający dokumentację w języku francuskim.
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:
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.
Gdy lokalizacja spełnia wymagania dotyczące przepływu pracy i minimalnej wymaganej zawartości, SIG Docs wykonuje następujące czynności:
Lokalizowanie całej dokumentacji Kubernetes to ogromne zadanie. Można zacząć od małych kroków i z czasem się rozwijać.
W minimalnym zakresie wszystkie lokalizacje muszą zawierać:
| Opis | URL |
|---|---|
| Strona główna | Wszystkie adresy URL nagłówków i podnagłówków |
| Konfiguracja | Wszystkie adresy URL nagłówków i podnagłówków |
| Samouczki | Podstawy Kubernetesa, Witaj Minikube |
| Ciągi znaków strony | Wszystkie ciągi znaków strony w nowym zlokalizowanym pliku TOML |
| Wydania | Wszystkie URL-e nagłówków i podnagłówków |
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:
mkdir -p content/de/docs/tutorials
cp -ra content/en/docs/tutorials/kubernetes-basics/ content/de/docs/tutorials/
Narzędzia tłumaczeniowe mogą przyspieszyć proces tłumaczenia. Na przykład, niektórzy edytorzy oferują wtyczki do szybkiego tłumaczenia tekstu.
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ą.
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.
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.
Aby znaleźć pliki źródłowe dla docelowej wersji:
Przejdź do repozytorium strony internetowej Kubernetes pod adresem https://github.com/kubernetes/website.
Wybierz gałąź dla swojej docelowej wersji z poniższej tabeli:
| Wersja docelowa | Gałąź |
|---|---|
| Najnowsza wersja | main |
| Poprzednia wersja | release-1.34 |
| Następna wersja | dev-1.36 |
Gałąź main zawiera treści dla bieżącego wydania
v1.35. Zespół wydawniczy tworzy gałąź
release-1.35 przed następnym wydaniem: v1.36.
Lokalizacje muszą zawierać treści
i18n/en/en.toml w
nowym pliku specyficznym dla danego języka.
Na przykład używając języka niemieckiego: i18n/de/de.toml.
Dodaj nowy katalog lokalizacyjny i plik
do i18n/. Na przykład, z niemieckim (de):
mkdir -p i18n/de
cp i18n/en/en.toml i18n/de/de.toml
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]
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.
Jako zespół lokalizacyjny, możesz sformalizować najlepsze praktyki, które stosuje twój zespół, tworząc przewodnik lokalizacyjny specyficzny dla danego języka.
Na przykład, zapoznaj się z Koreańskiego przedownika lokalizacji, który zawiera treści na następujące tematy:
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.
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.
Aby współpracować nad gałęzią lokalizacyjną:
Członek zespołu @kubernetes/website-maintainers otwiera gałąź lokalizacyjną z gałęzi źródłowej na https://github.com/kubernetes/website.
Twój zespół zatwierdzający dołączył do zespołu
@kubernetes/website-maintainers, gdy dodałeś swój zespół ds. lokalizacji
do repozytorium kubernetes/org.
Zalecamy następujący schemat nazywania gałęzi:
dev-<wersja źródłowa>-<kod języka>.<kamień milowy zespołu>
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:
main musi zostać scalona z main.release-1.34 musi być scalona z release-1.34.main, ale
nie została scalona z main przed utworzeniem nowej gałęzi wydania
release-1.35, scal ją zarówno z main, jak i z nową gałęzią
wydania release-1.35. Aby scalić swoją gałąź lokalizacyjną z
nową gałęzią wydania release-1.35, musisz przełączyć gałąź
(ang. upstream branch) dla swojej gałęzi lokalizacyjnej na release-1.35.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. Idiff_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".
SIG Docs chętnie przyjmuje nową treść oraz korekty w angielskiej wersji źródłowej.
SIG Docs jest jedną z special interest group w ramach projektu Kubernetes, skoncentrowaną na pisaniu, aktualizowaniu i utrzymywaniu dokumentacji dla całego Kubernetesa. Zobacz SIG Docs z repozytorium społeczności na GitHubie aby uzyskać więcej informacji o SIG.
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.
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.
Automatyzacja w SIG Docs opiera się na dwóch różnych mechanizmach: zespołach GitHub i plikach OWNERS.
Istnieją dwie kategorie zespołów SIG Docs na GitHubie:
@sig-docs-{language}-owners są zatwierdzającymi i liderami@sig-docs-{language}-reviews są recenzentamiKaż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.
Projekt Kubernetesa wykorzystuje narzędzie automatyzacji o nazwie prow do automatyzacji związanej z problemami i pull requestami w GitHub. Repozytorium strony internetowej Kubernetesa używa dwóch wtyczek prow:
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.
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.
lgtm, jak i approve, nie ma etykiet
hold, i wszystkie testy przechodzą pomyślnie, pull request łączy się automatycznie./hold lub wstrzymanie komentarza /lgtm).lgtm, dodając komentarz /lgtm./approve. Niektórzy zatwierdzający pełnią również dodatkowe specyficzne
role, takie jak PR Wrangler
lub przewodniczący SIG Docs.Więcej informacji na temat wnoszenia wkładu w dokumentację Kubernetesa można znaleźć w:
Tematy w tej sekcji opisują, jak aktualizować (czyli ponownie wygenerować) materiały źródłowe (ang. reference documentation) Kubernetesa.
Aby zbudować materiały źródłowe, zapoznaj się z następującym przewodnikiem:
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:
Musisz mieć zainstalowane następujące narzędzia:
Twoja zmienna środowiskowa GOPATH musi być ustawiona, a
lokalizacja etcd musi znajdować się w zmiennej środowiskowej PATH.
Musisz wiedzieć, jak utworzyć pull requesta do repozytorium GitHub. Zwykle obejmuje to utworzenie forka tego repozytorium. Aby uzyskać więcej informacji, zobacz Tworzenie pull requesta oraz Standardowy proces fork i pull request w GitHub.
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.
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>.
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ę.
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":
kubernetes/kubernetes/staging/src/k8s.io/api/apps/v1/types.go
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
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.
Przejdź do <k8s-base> i uruchom te skrypty:
./hack/update-codegen.sh
./hack/update-openapi-spec.sh
Uruchom git status, aby zobaczyć, co zostało wygenerowane.
On branch master
...
modified: api/openapi-spec/swagger.json
modified: api/openapi-spec/v3/apis__apps__v1_openapi.json
modified: pkg/generated/openapi/zz_generated.openapi.go
modified: staging/src/k8s.io/api/apps/v1/generated.proto
modified: staging/src/k8s.io/api/apps/v1/types_swagger_doc_generated.go
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.
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.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.35, a Ty chcesz wprowadzić swoją zmianę również do gałęzi release-1.34.
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.34. 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.
Kiedy masz w toku swój pull request dla zastosowania cherry picka ze swoim jednym commitem do gałęzi release-1.34, kolejnym krokiem jest uruchomienie tych skryptów w gałęzi release-1.34 w swoim lokalnym środowisku.
./hack/update-codegen.sh
./hack/update-openapi-spec.sh
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.34.
W tym momencie zarówno gałąź master, jak i gałąź release-1.34 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.34 niekoniecznie są
takie same jak wygenerowane pliki w gałęzi master. Wygenerowane pliki w gałęzi release-1.34
zawierają elementy API wyłącznie z Kubernetesa 1.34. Wygenerowane pliki w gałęzi master mogą
zawierać elementy API, które nie znajdują się w 1.34, ale są w trakcie rozwoju dla 1.35.
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.
Jesteś teraz gotowy do zapoznania się z przewodnikiem generowania materiałów źródłowych dla API Kubernetesa , aby wygenerować opublikowane materiały źródłowe API Kubernetesa.
kubectlTa strona pokazuje, jak wygenerować materiały źródłowe polecenia kubectl.
Potrzebujesz maszyny z systemem operacyjnym Linux lub macOS.
Musisz mieć zainstalowane następujące narzędzia:
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.
Utwórz lokalną przestrzeń roboczą i ustaw swoje GOPATH:
mkdir -p $HOME/<workspace>
export GOPATH=$HOME/<workspace>
Utwórz lokalną kopię następujących repozytoriów:
go get -u github.com/spf13/pflag
go get -u github.com/spf13/cobra
go get -u gopkg.in/yaml.v2
go get -u github.com/kubernetes-sigs/reference-docs
Jeśli nie masz jeszcze repozytorium kubernetes/website, pobierz je teraz:
git clone https://github.com/<your-username>/website $GOPATH/src/github.com/<your-username>/website
Zrób klon repozytorium kubernetes/kubernetes jako k8s.io/kubernetes:
git clone https://github.com/kubernetes/kubernetes $GOPATH/src/k8s.io/kubernetes
Usuń pakiet spf13 z $GOPATH/src/k8s.io/kubernetes/vendor/github.com:
rm -rf $GOPATH/src/k8s.io/kubernetes/vendor/github.com/spf13
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.34.0, możesz użyć tych poleceń:
cd <k8s-base>
git checkout v1.34.0
git pull https://github.com/kubernetes/kubernetes 1.34.0
Jeśli nie musisz edytować kodu źródłowego kubectl, postępuj zgodnie z
instrukcjami dotyczącymi Ustawiania zmiennych kompilacji.
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.
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.35 i chcesz przenieść swoją zmianę do gałęzi release-1.34. Aby uzyskać instrukcje, jak to zrobić, zobacz Proponowanie Cherry Pick.
Monitoruj swój cherry pick pull request, aż zostanie scalone z gałęzią wydania.
Przejdź do <rdocs-base>. W swoim wierszu poleceń ustaw następujące zmienne środowiskowe.
K8S_ROOT na <k8s-base>.K8S_WEBROOT na <web-base>.K8S_RELEASE na wersję dokumentacji, którą chcesz zbudować. Na przykład,
jeśli chcesz zbudować dokumentację dla Kubernetesa
1.34, ustaw K8S_RELEASE na 1.34.Na przykład:
export K8S_WEBROOT=$GOPATH/src/github.com/<your-username>/website
export K8S_ROOT=$GOPATH/src/k8s.io/kubernetes
export K8S_RELEASE=1.34
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
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.34.0, przejdź do tagu v1.34.
Upewnij się, że Twoja lokalna gałąź jest aktualna.
cd <k8s-base>
git checkout v1.34.0
git pull https://github.com/kubernetes/kubernetes v1.34.0
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>.
Zweryfikuj, czy te dwa pliki zostały wygenerowane:
[ -e "<rdocs-base>/gen-kubectldocs/generators/build/index.html" ] && echo "index.html built" || echo "no index.html"
[ -e "<rdocs-base>/gen-kubectldocs/generators/build/navData.js" ] && echo "navData.js built" || echo "no navData.js"
Zweryfikuj, czy wszystkie wygenerowane pliki zostały skopiowane do Twojego <web-base>:
cd <web-base>
git status
Wynik powinien zawierać zmodyfikowane pliki:
static/docs/reference/generated/kubectl/kubectl-commands.html
static/docs/reference/generated/kubectl/navData.js
Wynik może również zawierać:
static/docs/reference/generated/kubectl/scroll.js
static/docs/reference/generated/kubectl/stylesheet.css
static/docs/reference/generated/kubectl/tabvisibility.js
static/docs/reference/generated/kubectl/node_modules/bootstrap/dist/css/bootstrap.min.css
static/docs/reference/generated/kubectl/node_modules/highlight.js/styles/default.css
static/docs/reference/generated/kubectl/node_modules/jquery.scrollto/jquery.scrollTo.min.js
static/docs/reference/generated/kubectl/node_modules/jquery/dist/jquery.min.js
static/docs/reference/generated/kubectl/node_modules/font-awesome/css/font-awesome.min.css
Zbuduj dokumentację Kubernetes w lokalnym <web-base>.
cd <web-base>
git submodule update --init --recursive --depth 1 # if not already done
make container-serve
Zobacz podgląd lokalny.
Uruchom git add i git commit, aby zatwierdzić pliki.
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.
Ta strona demonstruje generowanie materiałów źródłowych dotyczących metryk.
Potrzebujesz maszyny z systemem operacyjnym Linux lub macOS.
Musisz mieć zainstalowane następujące narzędzia:
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.
Generowanie metryk odbywa się w repozytorium Kubernetesa. Aby sklonować repozytorium, przejdź do katalogu, w którym chcesz, aby klon istniał.
Następnie wykonaj następujące polecenie:
git clone https://www.github.com/kubernetes/kubernetes
To tworzy folder kubernetes w bieżącym katalogu roboczym.
W sklonowanym repozytorium Kubernetesa
zlokalizuj katalog test/instrumentation/documentation.
Dokumentacja metryk jest generowana w tym katalogu.
Przy każdej wersji dodawane są nowe metryki. Po uruchomieniu skryptu generatora dokumentacji metryk, skopiuj dokumentację metryk na stronę internetową Kubernetesa i opublikuj zaktualizowaną dokumentację metryk.
Aby wygenerować najnowsze metryki, upewnij się, że znajdujesz się w katalogu głównym sklonowanego katalogu Kubernetesa. Następnie wykonaj następujące polecenie:
./test/instrumentation/update-documentation.sh
Aby sprawdzić zmiany, wykonaj:
git status
Wynik jest podobny do:
./test/instrumentation/documentation/documentation.md
./test/instrumentation/documentation/documentation-list.yaml
Ustaw zmienną środowiskową głównego katalogu strony Kubernetesa.
Wykonaj następujące polecenie, aby ustawić główny katalog witryny:
export WEBSITE_ROOT=<path to website root>
Skopiuj wygenerowany plik metryk do repozytorium witryny Kubernetesa.
cp ./test/instrumentation/documentation/documentation.md "${WEBSITE_ROOT}/content/en/docs/reference/instrumentation/metrics.md"
chown, aby zmienić własność pliku na swojego użytkownika.Aby utworzyć pull request, postępuj zgodnie z instrukcjami w Otwarcie pull requesta.
Ta strona pokazuje, jak zbudować strony materiałów źródłowych komponentów i narzędzi Kubernetesa.
Rozpocznij od sekcji wymagania wstępne w przewodniku "szybki start materiałów źródłowych"
Postępuj zgodnie z Szybki start, aby wygenerować strony materiałów źródłowych dla komponentów i narzędzi Kubernetesa.
Potrzebujesz maszyny z systemem operacyjnym Linux lub macOS.
Musisz mieć zainstalowane następujące narzędzia:
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.
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.
Dokumentacja Kubernetesa obejmuje kilka typów treści stron:
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:
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 = "다음 내용"
Każdy typ zawartości nieformalnie definiuje swoją oczekiwaną strukturę strony. Twórz zawartość strony, korzystając z sugerowanych sekcji strony.
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:
overview, ustaw kontekst tematu za pomocą pojedynczego akapitu.body wyjaśnij koncepcję.whatsnext, podaj wypunktowaną listę tematów (maksymalnie 5), aby dowiedzieć się więcej o koncepcji.Strona adnotacje jest opublikowanym przykładem strony koncepcyjnej.
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.
Każdą sekcję uzupełnij treścią. Użyj następujących wytycznych:
#). Sekcje są automatycznie tytułowane przez szablon.overview użyj akapitu, aby ustawić kontekst dla całego tematu.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.steps używaj numerowanych list.steps.whatsnext, podaj listę punktowaną z maksymalnie 5 tematami,
które mogą zainteresować czytelnika jako kolejne tematy do przeczytania.Przykład opublikowanego tematu zadania to Korzystanie z proxy HTTP do uzyskania dostępu do API Kubernetesa.
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żdą sekcję uzupełnij treścią. Użyj następujących wytycznych:
#). Sekcje są automatycznie tytułowane przez szablon.overview użyj akapitu, aby ustawić kontekst dla całego tematu.prerequisites używaj, jeśli to możliwe, list
punktowanych. Dodaj dodatkowe wymagania wstępne poniżej tych domyślnie uwzględnionych.objectives, używaj list wypunktowanych.lessoncontent, użyj mieszanki list
numerowanych i treści narracyjnej w zależności od potrzeb.cleanup, użyj numerowanych list, aby opisać
kroki niezbędne do posprzątania stanu klastra po zakończeniu zadania.whatsnext, podaj listę punktowaną z maksymalnie 5 tematami,
które mogą zainteresować czytelnika jako kolejne tematy do przeczytania.Przykładem opublikowanego tematu samouczka jest Uruchamianie aplikacji bezstanowej przy użyciu Deployment.
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ń.
Członkowie SIG Docs mogą proponować usprawnienia.
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.
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:
Koordynowanie wydania to zazwyczaj zobowiązanie na 3-4 miesiące, a obowiązek ten jest rotacyjnie przejmowany przez zatwierdzających SIG Docs.
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ą:
Obecni Ambasadorzy Nowych Współtwórców są ogłaszani na każdym spotkaniu SIG-Docs oraz w kanale Kubernetes #sig-docs.
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.
Członkowie SIG Docs mogą pełnić funkcję współprzewodniczącego SIG Docs.
Członek zespołu Kubernetesa musi spełniać następujące wymagania, aby zostać współprzewodniczącym:
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ą:
Aby zaplanować i przeprowadzać efektywne spotkania, te wytyczne pokazują, co robić, jak to robić i dlaczego.
Przestrzegaj kodeksu postępowania społeczności:
Ustaw klarowną agendę:
W przypadku cotygodniowych spotkań, skopiuj i wklej notatki z poprzedniego tygodnia do sekcji "Past meetings" w notatkach.
Współpracuj nad dokładnymi notatkami:
Przypisz zadania jasno i precyzyjnie:
Moderuj w razie potrzeby:
Szanuj czas ludzi:
Rozpoczynaj i kończ spotkania o czasie.
Używaj Zoom efektywnie:
Kiedy będziesz gotowy do rozpoczęcia nagrywania, kliknij Zapisz w chmurze.
Gdy będziesz gotowy, aby zatrzymać nagrywanie, kliknij Stop.
Film przesyła się automatycznie na YouTube.
Zobacz: k/community/sig-docs/offboarding.md
Ta strona zawiera informacje o dashboardzie analitycznym kubernetes.io.
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.
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.
Na tej stronie znajdziesz wskazówki i wytyczne przydatne przy tłumaczeniu dokumentacji Kubernetesa na język polski.
Dokumentem nadrzędnym jest angielski opis stylu dokumentacji.
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.
Kubernetes jest nazwą własną, liczba pojedyncza, rodzaj męski. Odmieniamy: Kubernetesa, Kubernetesem itp. W uzasadnionych przypadkach można stosować też "system Kubernetes".
Odmieniamy zgodnie z ogólnymi zasadami - poda, deploymentu itp.
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.
| Termin angielski | Tłumaczenie |
|---|---|
| container | kontener |
| control plane | warstwa sterowania |
| Deployment | Deployment |
| horizontal scaling | skalowanie horyzontalne |
| Pod | Pod |
| rolling update | aktualizacje stopniowe |
| volume | volume (opcjonalnie: wolumin) |
| worker node | węzeł roboczy |