Zarządzają i publikują dokumentację w ramach cyklu wydawniczego Kubernetesa
Jak zacząć?
Każdy może otworzyć zgłoszenie dotyczące dokumentacji lub zaproponować zmianę poprzez
pull request (PR) do
repozytorium GitHub kubernetes/website.
Aby móc sprawnie funkcjonować w społeczności Kubernetes,
wymagana jest pewna biegłość w korzystaniu z
git-a i
GitHub-a.
Aby zaangażować się w prace nad dokumentacją należy:
flowchart TB
subgraph third[Otwórz PR]
direction TB
U[ ] -.-
Q[Ulepsz zawartość] --- N[Dodaj nową]
N --- O[Przetłumacz dokumentację]
O --- P[Zarządzaj dokumentacją przy kolejnych wydaniach K8s]
end
subgraph second[Recenzuj]
direction TB
T[ ] -.-
D[Przejrzyj repozytorium kubernetes/website] --- E[Pobierz generator stron statycznych Hugo]
E --- F[Zrozum podstawowe polecenia GitHub-a]
F --- G[Zrecenzuj otwarty PR i zmień procesy recenzji]
end
subgraph first[Zapisz się]
direction TB
S[ ] -.-
B[Podpisz CNCF Contributor License Agreement] --- C[Dołącz do Slack-a sig-docs]
C --- V[Zapisz się na listę kubernetes-sig-docs]
V --- M[Weź udział w cotygodniowych spotkaniach sig-docs]
end
A([fa:fa-user Nowy uczestnik]) --> first
A --> second
A --> third
A --> H[Zapytaj!!!]
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
Schemat 1. - Jak rozpocząć współpracę
Schemat 1 przeznaczony jest dla osób, które chcą zacząć współtworzyć Kubernetesa. Przejdź część lub wszystkie kroki opisane w częściach Zapisz się i Recenzuj. Teraz już możesz tworzyć nowe PR, zgodnie z sugestiami w Otwórz PR. I jak zawsze, pytania mile widziane!
Do realizacji niektórych zadań potrzeba wyższego poziomu zaufania i odpowiednich uprawnień w organizacji Kubernetes.
Zajrzyj do Participating in SIG Docs po więcej szczegółów dotyczących
ról i uprawnień.
Pierwsze kroki
Zapoznaj się z krokami opisanymi na schemacie 2, aby się lepiej przygotować.
flowchart LR
subgraph second[Pierwszy wkład]
direction TB
S[ ] -.-
G[Obejrzyj PR-y innych uczestników K8s] -->
A[Przejrzyj listę zgłoszonych spraw na kubernetes/website po pomysł na nowy PR] --> B[Otwórz PR!!]
end
subgraph first[Sugerowane przygotowanie]
direction TB
T[ ] -.-
D[Przeczytaj wprowadzenie dla współtwórców] -->E[Przeczytaj K8s content and style guides]
E --> F[Poczytaj o typach zawartości stron i skrótach 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,D,E,F,G grey
class S,T spacewhite
class first,second white
Schemat 2. - Jak się przygotować
Przeczytaj Contribution overview,
aby dowiedzieć się o różnych sposobach współpracy.
SIG Docs to grupa, która publikuje
i utrzymuje dokumentację Kubernetesa i jej stronę www. Zaangażowanie się w prace SIG Docs
to doskonała okazja dla współtwórców Kubernetesa (rozwijających nowe funkcjonalności
lub działających w innych obszarach), aby wywierać wpływ na cały projekt Kubernetes.
Aby włączyć się w komunikację w ramach SIG Docs, możesz:
Dołączyć do spotkania SIG Docs na Slacku organizowanego w tych tygodniach, kiedy nie ma spotkania na Zoomie. Informacja o spotkaniu zawsze ogłaszana jest na #sig-docs. W rozmowach prowadzonych w różnych wątkach na tym kanale można brać udział do 24 godzin od chwili ogłoszenia.
Inne sposoby współpracy
Odwiedź stronę społeczności Kubernetesa. Korzystaj z Twittera i Stack Overflow, dowiedz się o spotkaniach lokalnych grup Kubernetesa, różnych wydarzeniach i nie tylko.
Recenzenci i
Zatwierdzający SIG Docs wykonują
kilka dodatkowych czynności podczas przeglądania zmiany.
Co tydzień określony zatwierdzający zgłasza się na ochotnika do klasyfikowania i
przeglądania pull requestów. Osoba ta nazywana jest "PR Wranglerem" tygodnia. Zapoznaj się z
harmonogramem PR Wranglerów aby uzyskać
więcej informacji. Aby zostać PR Wranglerem, weź udział w cotygodniowym
spotkaniu SIG Docs i zgłoś się na ochotnika. Nawet jeśli nie jesteś w harmonogramie na
bieżący tydzień, nadal możesz przeglądać pull requesty (PR), które nie są już aktywnie przeglądane.
Oprócz rotacji, bot przypisuje recenzentów i
zatwierdzających dla PR na podstawie właścicieli odpowiednich plików.
Wszystko opisane w Przeglądaniu pull request
ma zastosowanie, ale recenzenci i zatwierdzający powinni również zrobić następujące rzeczy:
Używanie polecenia Prow /assign do przypisania konkretnego recenzenta do PR w razie
potrzeby. Jest to szczególnie ważne, gdy trzeba poprosić o przegląd techniczny od współtwórców kodu.
Informacja:
Spójrz na pole reviewers w części front-matter na górze
pliku Markdown, aby zobaczyć, kto może zapewnić recenzję techniczną.
Korzystanie z opcji GitHub Request Changes, gdy jest to możliwe, aby zasugerować zmiany autorowi PR.
Zmiana statusu recenzji w GitHub za pomocą poleceń Prow
/approve lub /lgtm, jeśli Twoje sugestie zostały wprowadzone.
Wprowadzenie zmian do PR innej osoby
Pozostawianie komentarzy na PR jest pomocne, ale mogą wystąpić
sytuacje, gdy zamiast tego będziesz musiał dokonać zatwierdzenia w PR innej osoby.
Nie "przejmuj" pracy innej osoby, chyba że wyraźnie cię o to
poprosi lub chcesz wznowić dawno porzucony PR. Chociaż może to być
szybsze w krótkim terminie, pozbawia to osobę szansy na wniesienie wkładu.
Proces, którego używasz, zależy od tego, czy musisz edytować plik,
który jest już w zakresie PR, czy plik, którego PR jeszcze nie dotknął.
Nie możesz commitować do PR kogoś innego, jeśli którakolwiek
z poniższych rzeczy jest prawdziwa:
Jeśli autor PR przesłał swoją gałąź bezpośrednio do
https://github.com/kubernetes/website/ repozytorium. Tylko recenzent
z dostępem do zapisu może wprowadzać zmiany do PR innego użytkownika.
Informacja:
Zachęć autora do wypchnięcia swojej gałęzi do
swojego forka przed otwarciem PR następnym razem.
Autor PR wyraźnie nie zezwala na edycje przez zatwierdzających.
Polecenia do przeglądania Prow
Prow to
oparty na Kubernetesie system CI/CD, który uruchamia zadania dla pull requestów
(PR). Prow umożliwia uruchamianie komendy w stylu chatbota do obsługi działań GitHub w
całej organizacji Kubernetesa, takich jak
dodawanie i usuwanie etykiet, zamykanie problemów i przydzielanie
zatwierdzającego. Wprowadzaj komendy Prow jako komentarze do GitHub, używając formatu /<command-name>.
Najczęściej używane przez recenzentów i zatwierdzających polecenia prow to:
Polecenia do przeglądania Prow
Komenda Prow
Rola
Opis
/lgtm
Członkowie organizacji
Sygnalizuje, że zakończyłeś przeglądanie PR i jesteś zadowolony ze zmian.
/approve
Zatwierdzający
Zatwierdza PR do scalania.
/assign
Każdy
Przypisuje osobę do przejrzenia lub zatwierdzenia PR
/close
Członkowie organizacji
Zamknięcie zgłoszenia lub PR.
/hold
Każdy
Dodaje etykietę do-not-merge/hold, wskazującą, że PR nie może być automatycznie scalony.
/hold cancel
Anyone
Usuwa etykietę do-not-merge/hold.
Aby zobaczyć polecenia, których można używać w PR, zapoznaj się z
Komendy Prow.
Ten filtr
w odniesieniu do GitHub Issue znajduje problemy, które mogą wymagać kategoryzowania.
Rozwiązywanie problemu
Zweryfikuj problem
Upewnij się, że zgłoszenie dotyczy dokumentacji strony internetowej. Niektóre problemy mogą zostać
szybko zamknięte poprzez udzielenie odpowiedzi na pytanie lub skierowanie zgłaszającego do zasobu. Szczegóły
znajdują się w sekcji Prośby o wsparcie lub zgłoszenia błędów w kodzie.
Oceń, czy problem ma podstawy.
Dodaj etykietę triage/needs-information, jeśli problem nie zawiera wystarczających
szczegółów, aby można było podjąć działania, lub jeśli szablon nie jest wypełniony odpowiednio.
Zamknij problem, jeśli ma zarówno etykiety lifecycle/stale, jak i triage/needs-information.
Według własnego uznania, przejmij odpowiedzialność za problem i zgłoś PR w jego
sprawie (szczególnie jeśli jest to szybkie lub dotyczy pracy, którą już wykonujesz).
Zagadnienia są zazwyczaj otwierane i zamykane szybko. Jednak
czasami zagadnienie jest nieaktywne po jego otwarciu. Innym
razem zagadnienie może wymagać pozostania otwartym dłużej niż 90 dni.
Etykiety cyklu życia zgłoszeń
Etykieta
Opis
lifecycle/stale
Po 90 dniach bez aktywności, problem jest automatycznie oznaczany jako przestarzały. Problem zostanie automatycznie zamknięty, jeśli cykl życia nie zostanie ręcznie cofnięty za pomocą polecenia /remove-lifecycle stale.
lifecycle/frozen
Zgłoszenie z tą etykietą nie stanie się nieaktywny po 90 dniach bezczynności. Użytkownik ręcznie dodaje tę etykietę do problemów, które muszą pozostać otwarte znacznie dłużej niż 90 dni, takich jak te z etykietą priority/important-longterm.
Obsługa specjalnych typów problemów
Zespół SIG Docs napotyka następujące typy problemów na
tyle często, że warto udokumentować sposób ich rozwiązywania.
Zduplikowane zgłoszenie
Jeśli dla jednego problemu jest otwartych kilka zgłoszeń, połącz je w jedno
zgłoszenie. Należy zdecydować, które zgłoszenie pozostawić otwarte (lub otworzyć
nowe zgłoszenie), a następnie przenieść wszystkie istotne informacje i połączyć
powiązane zgłoszenia. Na koniec oznacz wszystkie inne zgłoszenia opisujące ten sam
problem etykietą triage/duplicate i zamknij je. Posiadanie tylko jednego
zgłoszenia do pracy zmniejsza zamieszanie i unika powielania pracy nad tym samym problemem.
Problemy z martwymi linkami
Jeśli problem martwego linku znajduje się w dokumentacji API lub kubectl, przypisz im
/priority critical-urgent, dopóki problem nie zostanie w pełni zrozumiany. Wszystkim innym problemom z
martwymi linkami przypisz /priority important-longterm, ponieważ muszą być naprawione ręcznie.
Problemy z blogiem
Zakładamy, że wpisy na blogu Kubernetesa z
biegiem czasu tracą swoją aktualność. Z tego powodu
utrzymujemy jedynie artykuły nie starsze niż rok. Jeśli zgłoszenie dotyczy
wpisu starszego niż rok, zamknij je bez naprawiania.
Wnioski o wsparcie lub zgłoszenia błędów w kodzie
Część zgłoszeń dotyczących dokumentacji tak naprawdę odnosi się do problemów z
kodem źródłowym lub stanowi prośby o wsparcie, gdy coś (np. samouczek) nie działa prawidłowo.
W przypadku problemów niezwiązanych z dokumentacją, zamknij problem z
etykietą kind/support i komentarzem kierującym wnioskodawcę do miejsc
wsparcia (Slack, Stack Overflow) oraz, jeśli to istotne, do repozytorium, aby zgłosić problem
z błędami w funkcjach (kubernetes/kubernetes to świetne miejsce na początek).
Przykładowa odpowiedź na prośbę o wsparcie:
This issue sounds more like a request for support and less
like an issue specifically for docs. I encourage you to bring
your question to the `#kubernetes-users` channel in
[Kubernetes slack](https://slack.k8s.io/). You can also search
resources like
[Stack Overflow](https://stackoverflow.com/questions/tagged/kubernetes)
for answers to similar questions.
You can also open issues for Kubernetes functionality in
https://github.com/kubernetes/kubernetes.
If this is a documentation issue, please re-open this issue.
Przykładowa odpowiedź na zgłoszenie błędu w kodzie:
This sounds more like an issue with the code than an issue with
the documentation. Please open an issue at
https://github.com/kubernetes/kubernetes/issues.
If this is a documentation issue, please re-open this issue.
Scalanie (ang. squashing)
Jako osoba zatwierdzająca, podczas przeglądania pull requestów (PRs),
mogą wystąpić różne sytuacje, w których możesz zrobić następujące rzeczy:
Poinstruuj współtwórcę, aby połączył swoje commity.
Scal commity współtwórcy.
Poradź współtwórcy, aby jeszcze nie scalał zmian.
Zapobiegaj squaszowaniu.
Zalecanie łączenia commitów współtwórców: Nowy współtwórca może nie
wiedzieć, że powinien łączyć commity w swoich pull requestach (PR). W
takim przypadku należy mu to doradzić, podać linki do przydatnych
informacji i zaoferować pomoc, jeśli będzie jej potrzebował. Niektóre przydatne linki:
Scalanie commitów współtwórców: Jeśli współtwórca
może mieć trudności ze scaleniem commitów lub istnieje
presja czasu na połączenie PR, możesz wykonać scalanie za niego:
W PR, jeśli współtwórca umożliwia opiekunom zarządzanie PR,
możesz scalić commity i zaktualizować fork. Przed scaleniem
doradź, aby zapisano i wypchnęto najnowsze zmiany do PR. Po
scaleniu doradź, aby pobrano scalony commit do swojej lokalnej kopii.
Możesz skłonić GitHub do połączenia commitów, używając etykiety, tak aby Tide /
GitHub wykonał scalenie, lub klikając przycisk Squash commits podczas scalania PR.
Doradź współtwórcom, aby unikali scalania
Jeśli jakiś commit wprowadza coś błędnego lub nierozsądnego, a ostatni
commit cofa ten błąd, nie scalaj tych commitów. Mimo że zakładka "Files
changed" w PR na GitHubie oraz podgląd Netlify będą wyglądały OK, to
połączenie tego PR może stworzyć konflikty scalania lub rebase dla innych
osób. Interweniuj w miarę potrzeby, aby uniknąć tego ryzyka dla innych współtwórców.
Nigdy nie scalaj
Jeśli uruchamiasz lokalizację lub wydajesz dokumentację dla nowej wersji i scalasz
gałąź, która nie pochodzi z forka użytkownika, nigdy nie łącz zmian w jeden commit.
Niezachowanie scalania jest kluczowe, ponieważ musisz zachować historię commitów dla tych plików.
2 - 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.