Є багато способів зробити внесок у Kubernetes. Ви можете працювати над дизайном нових можливостей, документувати наявний код, писати для наших блогів. Це ще не все: ви можете реалізовувати нові можливості або виправляти помилки. Ви можете допомагати людям приєднатися до нашої спільноти учасників або підтримувати наявних учасників.
Для всіх цих способів вплинути на проєкт ми — Kubernetes — створили окремий вебсайт: https://k8s.dev/. Там можна дізнатися більше про участь у розвитку Kubernetes.
Якщо ви хочете дізнатися саме про внесок у документацію чи інші частини цього вебсайту, прочитайте Покращення документації Kubernetes. Якщо ви хочете допомогти саме з офіційними блогами Kubernetes, прочитайте Дописи у блог Kubernetes.
Також можна прочитати сторінкуCNCF про участь у розвитку Kubernetes.
1 - Покращення документації Kubernetes
Цей вебсайт підтримує Kubernetes SIG Docs. Проєкт Kubernetes вітає допомогу від усіх учасників, як нових, так і досвідчених!
Учасники, які працюють над документацією Kubernetes:
Покращують наявний вміст
Створюють новий вміст
Перекладають документацію
Керують частинами документації в циклі випуску Kubernetes і публікують їх
Команда блогу, що входить до SIG Docs, допомагає керувати офіційними блогами. Щоб дізнатися більше, прочитайте Дописи у блог Kubernetes.
Будь-хто може відкрити тікет щодо документації або запропонувати зміну через pull request (PR) до репозиторію GitHub kubernetes/website. Щоб ефективно працювати в спільноті Kubernetes, вам потрібно впевнено користуватися git і GitHub.
flowchart TB
subgraph third[Створення PR]
direction TB
U[ ] -.-
Q[Зробіть покращення] --- N[Створіть новий вміст]
N --- O[Перекладіть документацію]
O --- P[Керуйте/Публікуйте документацію релізного циклу K8s]
end
subgraph second[Огляд]
direction TB
T[ ] -.-
D[Огляньте репозиторій kubernetes/website] --- E[Ознайомтесь з генератором статичних сайтів Hugo]
E --- F[Зрозумійте основні команди GitHub]
F --- G[Ознайомтеся з відкритими PR і процесами рецензування змін]
end
subgraph first[Реєстрація]
direction TB
S[ ] -.-
B[Підпишіть CNCF Contributor License Agreement] --- C[Приєднайтесь до каналу sig-docs в Slack]
C --- V[Приєднайтесь до списку розсилки kubernetes-sig-docs]
V --- M[Відвідуйте тижневі заходи sig-docs чи зустрічі в slack]
end
A([fa:fa-user Новий учасник]) --> first
A --> second
A --> third
A --> H[Ставте питання!!!]
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
Схема 1. Початок роботи для нового учасника.
На схемі 1 показано дорожню карту для нових учасників. Ви можете виконати деякі або всі кроки з Реєстрація та Огляд. Після цього ви готові відкривати PR, які досягають ваших цілей внеску, — деякі з них наведено в Створення PR. І знову: запитання завжди вітаються!
Деякі завдання потребують більшої довіри та ширшого доступу в організації Kubernetes. Докладніше про ролі й дозволи див. Участь у SIG Docs.
Ваш перший внесок
Підготуватися до першого внеску можна, заздалегідь ознайомившись із кількома кроками. На схемі 2 показано ці кроки, а подробиці наведено далі.
flowchart LR
subgraph second[Перший внесок]
direction TB
S[ ] -.-
G[Зробіть огляд PR від інших учасників K8s] -->
A[Ознайомтесь з переліком тікетів на kubernetes/website щоб знайти щось для першого PR] --> B[Створіть PR!!]
end
subgraph first[Підготовчі кроки]
direction TB
T[ ] -.-
D[Ознайомтесь з описом внеску] -->E[Ознайомтесь з настановами щодо вмісту та стилю K8s]
E --> F[Дізнайтесь про типи вмісту сторінок Hugo та їх shortcodes]
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
Схема 2. Підготовка до першого внеску.
Прочитайте огляд внеску, щоб дізнатися про різні способи зробити внесок.
Перший внесок може здатися надто складним. New Contributor Ambassadors готові допомогти вам із першими кількома внесками. Звернутися до них можна в Kubernetes Slack, бажано в каналі #sig-docs. Також першого вівторка кожного місяця відбувається New Contributors Meet and Greet call. Там можна поспілкуватися з New Contributor Ambassadors і отримати відповіді на свої запитання.
Приєднуйтеся до SIG Docs
SIG Docs — це група учасників, які публікують і підтримують документацію Kubernetes та вебсайт. Участь у SIG Docs — чудовий спосіб для учасників Kubernetes (і розробників можливостей, і інших) суттєво вплинути на проєкт Kubernetes.
Приєднуйтеся до асинхронної стендап-зустрічі SIG Docs у Slack у ті тижні, коли відеозустріч у Zoom наживо не проводиться. Про зустрічі завжди оголошують у #sig-docs. Долучитися до будь-якого з тредів можна протягом 24 годин після оголошення зустрічі.
Інші способи зробити внесок
Відвідайте сайт спільноти Kubernetes. Беріть участь в Twitter або Stack Overflow, дізнайтеся про місцеві зустрічі та події Kubernetes та інше.
Є два офіційні блоги Kubernetes, а CNCF має власний блог, де ви також можете писати про Kubernetes. У головному блозі Kubernetes ми (проєкт Kubernetes) радо публікуємо статті з різними поглядами та особливими акцентами, що мають стосунок до Kubernetes.
За кількома винятками для особливих випадків, ми публікуємо лише вміст, який ще ніде не подавався й не публікувався.
Головний блог Kubernetes проєкт використовує, щоб повідомляти про нові можливості, звіти спільноти та будь-які новини, які можуть бути цікаві спільноті Kubernetes, зокрема кінцевим користувачам і розробникам. Більшість вмісту блогу стосується подій в основному проєкті, але Kubernetes як проєкт заохочує вас писати й про події в інших частинах екосистеми!
Будь-хто може написати допис у блог і подати його на публікацію. За кількома винятками для особливих випадків, ми публікуємо лише вміст, який ще ніде не подавався й не публікувався.
Блог учасників
Блог учасників Kubernetes орієнтований на людей, які працюють над Kubernetes, більше, ніж на людей, які працюють з Kubernetes. Проєкт Kubernetes навмисно публікує деякі статті в обох блогах.
Будь-хто може написати допис у блог і подати його на рецензування.
Оновлення та підтримка статей
Проєкт Kubernetes не підтримує старіші статті у своїх блогах. Це означає, що будь-яка опублікована стаття, старша за рік, зазвичай не розглядається для тікетів чи pull request із проханням про зміни. Щоб не створювати прецедент, навіть технічно правильні pull request, найімовірніше, буде відхилено.
вилучення або виправлення статей, що містять поради, які тепер є помилковими і небезпечними для виконання
виправлення, які забезпечують коректне відображення наявної статті
Для будь-якої статті, якій понад рік і яка не позначена як evergreen, вебсайт автоматично показує повідомлення про те, що її вміст може бути застарілим.
Статті evergreen
Позначити статтю як evergreen можна, встановивши evergreen: true у front matter.
Ми позначаємо статті блогу як підтримувані (evergreen: true у front matter), лише якщо проєкт Kubernetes може взяти на себе зобовʼязання підтримувати їх безстроково. Деякі статті блогу цілком на це заслуговують; наприклад, команда release comms завжди позначає офіційні анонси випусків як evergreen.
Є два офіційні блоги Kubernetes, а CNCF має власний блог, де ви також можете писати про Kubernetes. У головному блозі Kubernetes ми (проєкт Kubernetes) радо публікуємо статті з різними поглядами та особливими акцентами, що мають стосунок до Kubernetes.
За кількома винятками для особливих випадків, ми публікуємо лише вміст, який ще ніде не подавався й не публікувався.
Написання статей для блогу(ів) Kubernetes
Як автор, ви маєте три різні шляхи до публікації.
Рекомендований шлях
Проєкт Kubernetes рекомендує такий підхід: запропонуйте свою статтю, звʼязавшись із командою блогу. Це можна зробити в Kubernetes Slack (#sig-docs-blog). Статті, які ви хочете опублікувати лише в блозі учасників, можна також запропонувати безпосередньо SIG ContribEx comms.
Якщо з вашою заявкою не буде проблем, команда блогу / SIG ContribEx обʼєднає вас у пару з:
редактором блогу
вашим помічником з написання (writing buddy, іншим автором блогу)
Коли команда обʼєднує вас у пару з іншим автором, ідея в тому, що ви підтримуєте одне одного, рецензуючи чернетку статті іншого автора. Вам не потрібно бути експертом у темі; більшість читачів статті теж не будуть експертами. Ми, команда блогу Kubernetes, називаємо іншого автора помічником з написання (writing buddy).
Редактор супроводжуватиме вас на шляху від чернетки до публікації. Він або може безпосередньо затвердити вашу статтю для публікації, або організує затвердження.
Другий шлях до написання для наших блогів — почати безпосередньо з pull request на GitHub. Насправді команда блогу цього не рекомендує: GitHub дуже зручний для спільної роботи над кодом, але не ідеально підходить для прозових текстів.
Цілком нормально відкрити placeholder pull request лише з порожнім комітом, а потім працювати деінде, перш ніж повернутися до свого placeholder PR.
Як і в рекомендованому шляху, ми спробуємо обʼєднати вас у пару з помічником з написання та редактором блогу. Вони допоможуть вам підготувати статтю до публікації.
Процес створення статті у блозі після випуску
Третій шлях призначено для статей блогу про зміни в Kubernetes, повʼязані з випуском. Щоразу, коли відбувається випуск, команда Release Comms бере на себе графік публікацій у блозі. Люди, які додають можливості до випуску або планують інші зміни, про які проєкт має оголосити, можуть домовитися з Release Comms, щоб їхню статтю запланували, написали, відредагували й зрештою опублікували.
Планування статей
У блозі Kubernetes команда блогу зазвичай планує публікацію статей у будні дні (за григоріанським календарем, який використовується у США та інших країнах). Якщо важливо опублікувати статтю у певну дату, яка припадає на вихідні, команда блогу намагається це врахувати.
однак позначте статтю як чернетку (додайте draft: true у front matter)
Коли бот Prow зіллє ваш PR, стаття буде чернеткою і не буде запланована до публікації. Потім учасник Kubernetes (ви, ваш помічник з написання або хтось із команди блогу) відкриває невеликий подальший PR, який позначає її для публікації. Злиття цього другого PR вивільняє статтю, що доти була чернеткою, і її може бути автоматично опубліковано.
У день, на який заплановано публікацію статті, автоматизація запускає збирання вебсайту, і ваша стаття стає видимою.
Написання статті
Після того як ви запропонуєте статтю, ми заохочуємо вас використовувати HackMD (вебредактор Markdown) або Google Doc, щоб поділитися версією тексту статті, яку можна редагувати. Ваш помічник з написання може прочитати чернетку, а потім або безпосередньо запропонувати зміни, або надати інший відгук. Він також має повідомити вас, якщо ваша чернетка не відповідає настановам щодо блогу.
Водночас ви зазвичай будете його помічником з написання і можете скористатися нашим посібником щодо підтримки його роботи.
Початкові адміністративні кроки
Вам слід підписати CLA, якщо ви ще цього не зробили. Найкраще подбати про це якомога раніше; якщо ви пишете в межах своєї роботи, можливо, доведеться погодити це з юридичним відділом роботодавця або з керівником, щоб переконатися, що вам дозволено підписати.
Початкова чернетка
Команда блогу рекомендує використовувати HackMD (вебредактор Markdown) або Google doc, щоб підготувати й поширити початкову версію тексту статті, яку можна редагувати наживо.
Примітка:
Якщо ви вирішите скористатися Google Docs, можна перевести документ у режим Markdown.
Ваш помічник з написання може коментувати та/або давати відгуки на вашу чернетку і перевірятиме (або має перевіряти), чи відповідає вона настановам. Водночас ви будете його помічником з написання і можете скористатися посібником, який пояснює, як підтримувати його роботу.
Однак на цьому етапі не надто переймайтеся точним форматуванням Markdown.
Якщо у вас є зображення, ви можете вставити растрову копію для отримання перших відгуків. Команда блогу може допомогти вам (пізніше) підготувати ілюстрації до остаточної публікації.
Markdown для публікації
Перегляньте формат Markdown наявних дописів блогу в репозиторії вебсайту на GitHub.
Якщо ви ще не знайомі з ними, прочитайте основи участі. Цей розділ сторінки передбачає, що у вас немає локального клону вашого форку і ви працюєте у вебінтерфейсі GitHub. Проте вам потрібно створити віддалений форк репозиторію вебсайту, якщо ви ще цього не зробили.
У репозиторії GitHub натисніть кнопку Create new file. Назвіть файл допису у форматі /content/en/blog/_posts/YYYY/abbreviated-post-title.md, де …/YYYY/… — підтека з дописами за відповідний рік. Якщо до допису потрібно додати зображення, діаграми тощо, створіть теку /content/blog/en/blog/_posts/YYYY/abbreviated-post-title/ з файлом index.md та додатковими файлами для вашого допису.
Скопіюйте наявний вміст з HackMD або Google Docs і вставте його в редактор. Далі в цьому розділі докладніше описано, що має бути в цьому файлі. Назвіть файл відповідно до запропонованого заголовка допису, але не додавайте дату в назву файлу. Рецензенти блогу разом із вами визначать остаточну назву файлу та дату публікації статті.
Коли ви збережете файл, GitHub проведе вас через процес створення pull request.
Ваш помічник з написання може рецензувати подання й працювати з вами над відгуками та остаточними деталями. Редактор блогу затверджує злиття вашого pull request як чернетки, яку ще не заплановано.
Front matter
Файл Markdown, який ви пишете, має використовувати Hugo front matter у форматі YAML.
Ось приклад:
---layout:blogtitle:"Your Title Here"draft:true# буде змінено на "date: YYYY-MM-DD" перед публікацієюslug:lowercase-text-for-link-goes-here-no-spaces# необовʼязковоauthor:> Author-1 (Affiliation),
Author-2 (Affiliation),
Author-3 (Affiliation)---
спочатку не вказуйте дату для статті та не вставляйте замість неї будь-який замінник дати у front matter (НЕ РОБІТЬ ТАК date: XXXX-XX-XX)
однак позначте статтю як чернетку (додайте draft: true у front matter статті)
Вміст статті
Як найвищий рівень заголовків у статті використовуйте заголовки Markdown другого рівня (##, а не #). Значення title, яке ви задаєте у front matter, стає заголовком першого рівня цієї сторінки.
ми не проти того, щоб автори писали статті у власному стилі, якщо більшість читачів зрозуміють суть викладеного матеріалу
можна використовувати «ми» у статтях блогу, які мають кількох авторів, або якщо у вступі до статті чітко вказано, що автор пише від імені певної групи. Як ви помітите з цього розділу, хоча ми уникаємо використання «ми» у нашій документації, можна робити виправдані винятки.
ми не використовуємо shortcodes Kubernetes для виносок (callouts), як-от {{< caution >}}. Це тому, що виноски призначені для читачів документації, а статті блогу — не документація.
твердження про майбутнє допустимі, хоча в офіційних оголошеннях від імені Kubernetes ми використовуємо їх обережно
прикладам коду в статтях блогу не потрібно використовувати shortcode {{< code_sample >}}, і часто краще (легше підтримувати), якщо вони його не використовують
Схеми та ілюстрації
Для ілюстрацій, діаграм або графіків за можливості використовуйте shortcode figure. Для доступності слід задати атрибут alt.
Для ілюстрацій і технічних схем намагайтеся використовувати векторну графіку. Команда блогу рекомендує SVG замість растрових (bitmap / піксельних) форматів діаграм, а також SVG замість Mermaid (джерело Mermaid можна зберегти в коментарі). Перевагу SVG над Mermaid пояснює те, що коли супровідники оновлюють Mermaid або змінюють відображення діаграм, вони можуть не мати простого способу звʼязатися з автором оригінальної статті, щоб перевірити, чи зміни прийнятні.
Посібник з діаграм призначено для документації Kubernetes, а не для статей блогу. Узгоджуватися з ним все одно добре, але:
немає потреби підписувати діаграми як «Схема 1», «Схема 2» тощо.
Вимога щодо масштабованих (векторних) зображень ускладнює подання статей для менш досвідчених людей; Kubernetes SIG Docs і далі шукає способи знизити цей поріг. Якщо у вас є ідеї, як знизити барʼєр, зголошуйтеся допомогти.
Для інших зображень (наприклад, фотографій) команда блогу наполегливо рекомендує використовувати атрибути alt. Можна використати порожній атрибут alt, якщо засоби доступності взагалі не мають згадувати зображення, але це рідкісна ситуація.
Повідомлення комітів
Коли ви позначаєте pull request як готовий до рецензування, кожне повідомлення коміту має коротко підсумовувати виконану роботу. Перше повідомлення коміту має бути зрозумілим як загальний опис допису в блозі.
Приклади хороших повідомлень комітів:
Add blog post on the foo kubernetes feature
blog: foobar announcement
Приклади поганих повідомлень комітів:
Placeholder commit for announcement about foo
Add blog post
asdf
initial commit
draft post
Обʼєднання комітів (squashing)
Коли ви вважатимете, що стаття готова до злиття, слід виконати squash комітів у вашому pull request; якщо ви не знаєте, як це зробити, можна попросити допомоги в команди блогу.
2.2 - Правила створення постів у блозі
Ці настанови стосуються головного блогу Kubernetes і блогу учасників Kubernetes.
Весь вміст блогів також має відповідати загальній політиці, викладеній у посібнику з вмісту.
Перш ніж ви розпочнете
Переконайтеся, що ви ознайомилися зі вступними розділами сторінки Дописи у блог Kubernetes, не лише щоб дізнатися про два офіційні блоги та відмінності між ними, а й щоб отримати загальне уявлення про процес.
Оригінальний вміст
Проєкт Kubernetes приймає лише оригінальний вміст англійською мовою.
Примітка:
Проєкт Kubernetes не може прийняти вміст для блогу, якщо він вже був надісланий або опублікований поза межами проєкту Kubernetes.
Офіційні блоги не є майданчиком для повторного використання наявного вмісту будь-яких третіх сторін як нового вмісту.
Це обмеження поширюється навіть на просування інших проєктів Linux Foundation і CNCF. Багато проєктів CNCF мають власні блоги. Для дописів про певний проєкт вони часто є кращим вибором, навіть якщо цей проєкт створено спеціально для роботи з Kubernetes (або з Linux тощо).
Релевантний вміст
Статті мають містити вміст, який широко стосується спільноти Kubernetes. Наприклад, стаття має зосереджуватися на upstream Kubernetes, а не на конфігураціях конкретного постачальника. Для статей до головного блогу, які не є дзеркальними статтями, гіперпосилання в статті зазвичай мають вести на офіційну документацію Kubernetes. Зовнішні посилання мають бути різноманітними — наприклад, стаття не повинна містити посилань лише на блог однієї компанії.
Офіційні блоги Kubernetes — це не місце для реклами постачальників або для статей, які просувають конкретні рішення з-поза меж Kubernetes.
Іноді тут потрібен делікатний баланс. Ви можете запитати в Slack (#sig-docs-blog), чи підходить допис для блогу Kubernetes та/або блогу учасників, — не соромтеся звертатися.
Посібник з вмісту беззастережно застосовується до статей блогу і PR, які їх додають. Майте на увазі, що деякі обмеження в посібнику прямо зазначають, що стосуються лише документації; такі позначені обмеження не застосовуються до статей блогу.
Локалізація
Сайт локалізовано багатьма мовами; англійська є «upstream» для всіх інших локалізацій. Навіть якщо ви володієте іншою мовою і хотіли б надати локалізацію, вона має бути в окремому pull request (див. мови в PR).
Авторське право та повторне використання
Ви маєте писати оригінальний вміст і мати дозвіл ліцензувати цей вміст для Cloud Native Computing Foundation (щоб проєкт Kubernetes міг легально його опублікувати). Це означає, що заборонено не лише прямий плагіат: ви не можете писати статтю для блогу, якщо не маєте дозволу виконати умови ліцензії авторського права CNCF (наприклад, якщо ваш роботодавець має політику щодо інтелектуальної власності, яка обмежує, що вам дозволено робити).
Ліцензія блогу дозволяє комерційне використання вмісту в комерційних цілях, але не навпаки.
Групи за інтересами та робочі групи
Теми, повʼязані з участю в діяльності SIG Kubernetes або її результатами, завжди доречні (підтримку для таких дописів див. у роботі Contributor Comms Team).
Проєкт зазвичай віддзеркалює ці статті в обох блогах.
Національні обмеження щодо вмісту
Вебсайт Kubernetes має ліцензію постачальника інтернет-контенту (ICP) від уряду Китаю. Хоча це навряд чи стане проблемою, Kubernetes не може публікувати статті, які були б заблоковані офіційною фільтрацією інтернет-контенту урядом Китаю.
Решта цієї сторінки — додаткові настанови; це не суворі правила, яких мають дотримуватися статті, але рецензенти, імовірно, попросять (і мають просити) відредагувати статті, які явно не відповідають наведеним тут рекомендаціям.
Схеми та ілюстрації
Для ілюстрацій, зокрема схем і діаграм, за можливості використовуйте shortcode figure. Для доступності слід задати атрибут alt.
Для ілюстрацій, технічних схем і подібної графіки використовуйте векторні зображення; рекомендовано надавати перевагу формату SVG.
Статті, які використовують растрові зображення для ілюстрацій, складніше підтримувати, і в деяких випадках команда блогу може попросити авторів доопрацювати статтю, перш ніж вона буде опублікована.
Позачасовість
Дописи в блозі мають бути розраховані на майбутнє
З огляду на швидкість розвитку проєкту SIG Docs надає перевагу позачасовим текстам: вмісту, який не потребуватиме оновлень, щоб лишатися точним для читача.
Додати підручник або оновити офіційну документацію може бути кращим вибором, ніж писати високорівневий огляд у вигляді допису в блозі.
Подумайте про те, щоб винести довгий технічний вміст як заклик до дії в дописі, а зосередитися на проблемній області або на тому, чому читачам це має бути важливо.
Пояснення того, як досягти результату за допомогою Kubernetes; наприклад, розкажіть про ваше вдосконалення базової ідеї rolling deploy, яке зменшує рутинну роботу
Порівняння кількох різних варіантів програмного забезпечення, повʼязаних з Kubernetes і cloud native. Можна посилатися на один із цих варіантів, якщо ви повністю розкриваєте свій конфлікт інтересів / звʼязок із ним.
Історії про проблеми або інциденти, а також про те, як ви їх вирішили
Статті про створення cloud native платформи для конкретних сценаріїв використання
Ваша думка про хороші та погані сторони Kubernetes
Оголошення та історії про частини Kubernetes поза ядром, як-от Gateway API
Повідомлення про важливі вразливості у безпеці Kubernetes
Оновлення проєктів Kubernetes
Підручники та покрокові інструкції
Експертні погляди (thought leadership) щодо Kubernetes і cloud native
Компоненти Kubernetes навмисно модульні, тож писати про наявні точки інтеграції, як-от CNI і CSI, доречно. Якщо ваш допис не є рекламою постачальника, ви також можете писати про те, що розташоване по інший бік цих інтеграцій.
Ось кілька прикладів вмісту, який підходить для блогу учасників Kubernetes:
статті про те, як протестувати ваші зміни у коді Kubernetes
матеріали, що стосуються внеску, який не повʼязаний з кодом
обговорення альфа-можливостей, дизайн яких ще обговорюється
«Знайомство з командою»: статті про робочі групи, групи за інтересами тощо
посібник про те, як писати безпечний код, який стане частиною самого Kubernetes
статті про зустрічі супровідників та результати цих зустрічей
Приклади вмісту, який не буде прийнято
Однак проєкт не публікуватиме:
рекламу постачальників
статтю, яку ви опублікували в інших місцях, навіть якщо це лише ваш власний блог з низьким трафіком
великі шматки вихідного коду прикладу з мінімальними поясненнями
новини про зовнішній проєкт, який працює з Kubernetes або залежить від нього (публікуйте їх у власному блозі зовнішнього проєкту)
статті про використання Kubernetes з конкретним хмарним провайдером
статті, які критикують конкретних людей, групи людей або компанії
статті, які містять важливі технічні помилки або деталі, що вводять в оману (наприклад: якщо ви рекомендуєте вимкнути важливий контроль безпеки у промислових кластерах, тому що це може бути незручно, проєкт Kubernetes, швидше за все, відхилить цю статтю).
2.3 - Віддзеркалення статті в блозі
Є два офіційні блоги Kubernetes, а CNCF має власний блог, де ви також можете писати про Kubernetes. У головному блозі Kubernetes ми (проєкт Kubernetes) радо публікуємо статті з різними поглядами та особливими акцентами, що мають стосунок до Kubernetes.
Деякі статті зʼявляються в обох блогах: є основна версія статті та дзеркальна стаття в іншому блозі.
На цій сторінці описано критерії віддзеркалення, його причини, а також що потрібно зробити, щоб стаття була опублікована в обох блогах.
Перш ніж ви розпочнете
Переконайтеся, що ви ознайомилися зі вступними розділами сторінки Дописи у блог Kubernetes, не лише щоб дізнатися про два офіційні блоги та відмінності між ними, а й щоб отримати загальне уявлення про процес.
Чому ми робимо віддзеркалення
Віддзеркалення майже завжди відбувається з блогу учасників до головного блогу. Проєкт робить це для статей, які стосуються спільноти учасників або її частини, але також цікаві ширшому колу читачів головного блогу Kubernetes.
Як автор (або рецензент), зважте на цільову аудиторію і на те, чи підходить допис для головного блогу. Наприклад, якщо цільова аудиторія — лише учасники Kubernetes, доречнішим може бути блог учасників; якщо допис стосується відкритого коду загалом, він може краще підійти для іншого сайту поза проєктом Kubernetes.
Це міркування про цільову аудиторію однаково стосується як оригінальних, так і дзеркальних статей.
Проєкт Kubernetes готовий віддзеркалити будь-яку статтю блогу, опубліковану на https://kubernetes.dev/blog/ (блог учасників), якщо виконано всі такі критерії:
Віддзеркалена стаття має ту саму дату публікації, що й оригінал (вона також має мати той самий час публікації, але для особливих випадків можна встановити позначку часу до 12 годин пізніше)
Для PR, які додають дзеркальну статтю до головного блогу після того, як оригінальну статтю злито в блог учасників, переконайтеся, що виконано всі такі критерії:
Жодної статті не було опубліковано в головному блозі після того, як оригінальна стаття була опублікована в блозі учасників.
У головному блозі не заплановано публікацій статей між часом публікації оригінальної статті та часом публікації вашої дзеркальної статті.
Це повʼязано з тим, що проєкт Kubernetes не бажає додавати статті до стрічок користувачів, таких як RSS, окрім як у самому кінці стрічки.
Оригінальна стаття не порушує жодних наполегливо рекомендованих настанов рецензування чи норм спільноти
У віддзеркаленій статті буде правильно вказано canonicalUrl у її front matter
Аудиторія оригінальної статті вважатиме її доречною
Вміст статті не виходить за межі тематики цільового блогу, де зʼявиться дзеркальна стаття
Віддзеркалення з головного блогу в блог учасників трапляється рідко, але цілком можливе.
Як віддзеркалити
Ви створюєте PR до іншого Git-репозиторію (зазвичай https://github.com/kubernetes/website), який додає статтю. Це потрібно зробити до злиття статей.
Як автор статті, ви маєте встановити для віддзеркаленої статті канонічну URL-адресу — URL-адресу оригінальної статті (можна скористатися попереднім переглядом, щоб передбачити URL-адресу і заповнити її до фактичної публікації). Для цього використовуйте поле canonicalUrl у front matter.
Після кожного випуску команда Release Comms на певний час бере на себе головний блог і публікує серію додаткових статей, щоб пояснити або оголосити зміни, повʼязані з цим випуском. Ці додаткові статті називають post-release comms (комунікаціями після випуску).
Участь у комунікаціях після випуску
Під час циклу випуску ви як учасник можете долучитися до комунікацій після випуску щодо майбутньої зміни в Kubernetes.
Щоб долучитися, відкрийте чернетку placeholderpull request (PR) до k/website. Спочатку це може бути порожній коміт. Згадайте тікет KEP або інший тікет щодо покращення Kubernetes в описі вашого placeholder PR.
Коли ви відкриваєте чернетку pull request, ви відкриваєте її з main як базовою гілкою, а не з гілкою dev-1.38. Це відрізняється від процесу для змін майбутнього випуску та нових можливостей.
Також слід залишити коментар у відповідному тікеті kubernetes/enhancements з посиланням на PR, щоб повідомити команду Release Comms, яка керує цим випуском. Ваш коментар допоможе команді побачити, що зміну потрібно анонсувати і що ваша SIG вирішила долучитися.
Крім того, в ідеалі слід звʼязатися з командою Release Comms через Slack (канал #release-comms), щоб повідомити, що ви це зробили й хочете долучитися.
Підготовка вмісту статті
Щоб перетворити ваш placeholder PR на щось готове до рецензування, дотримуйтеся звичайного процесу подання статті. Однак для комунікацій після випуску у вас може не бути writing buddy (помічника з написання); натомість команда Release Comms може призначити члена команди, який допоможе спрямовувати вашу роботу.
Слід виконати squash комітів у вашому pull request; якщо ви не знаєте, як це зробити, цілком нормально попросити допомоги в Release Comms або команди блогу.
За умови, що вашу статтю позначено як чернетку (draft: true) у front matter, PR можна злити в будь-який час протягом циклу випуску.
Публікація
Перед самим випуском команда Release Comms перевіряє, який вміст готовий (якщо його не готово до встановленого терміну і ви не отримали винятку, анонс не буде включено). Вона складає графік статей, які вийдуть, і відкриває нові pull request, щоб перевести ці статті з чернеток в опубліковані.
Увага:
Усі ці pull request для фактичної публікації статей після випуску мають бути затримані (команда Prow /hold), доки випуск фактично не відбудеться.
Затверджувачі команди блогу все одно дають остаточну згоду на переведення вмісту з чернетки до прийнятого для публікації. Напередодні дня випуску PR (або кілька PR) для публікації цих анонсів мають мати мітки LGTM (“looks good to me”, «на мою думку, усе добре») та approved, а також мітку do-not-merge/hold, щоб PR не злили зарано.
Після цього Release Comms / команда випуску може зняти hold з цього PR (або набору PR), щойно Git-репозиторій вебсайту буде розморожено після фактичного випуску.
У день, коли кожна стаття запланована до публікації, автоматизація запускає збірку вебсайту, і стаття стає видимою.
2.5 - Допомога у написанні блогу
Є два офіційні блоги Kubernetes, а CNCF має власний блог, де ви також можете писати про Kubernetes. Щоб дізнатися про ці два блоги, прочитайте Дописи у блог Kubernetes.
Коли люди роблять внесок у будь-який із блогів як автори, проєкт Kubernetes обʼєднує авторів у пари як помічників з написання (writing buddies). На цій сторінці пояснено, як виконувати роль помічника.
Перш ніж читати далі, переконайтеся, що ви принаймні ознайомилися із загальним описом подання статті.
Обовʼязки помічника
Як помічник з написання, ви:
допомагаєте команді блогу підготувати статті до злиття та публікації
підтримуєте свого напарника у створенні вмісту, придатного для злиття
рецензуєте статтю, яку написав ваш напарник
Коли команда обʼєднує вас у пару з іншим автором, ідея в тому, що ви підтримуєте одне одного, рецензуючи чернетку статті іншого автора. Більшість людей, які читають статті в блозі Kubernetes, не є експертами; вміст має бути зрозумілим для цієї аудиторії або принаймні належним чином допомагати читачам, які не є експертами.
Команда блогу також допомагає вам обом на шляху від чернетки до публікації. Вона або може безпосередньо затвердити вашу статтю для публікації, або може організувати затвердження.
Підтримка команди блогу
Ваш головний обовʼязок тут — вчасно повідомляти про свої можливості, доступність і прогрес. Якщо минає багато тижнів, а ваш напарник нічого від вас не чує, уся робота триває довше.
Підтримка вашого напарника
Процес складається з двох частин
(Це рекомендований варіант)
Команда блогу рекомендує, щоб головний автор статті налаштував спільне редагування в Google Doc або HackMD (на свій вибір). Потім головний автор надає доступ до цього документа таким людям:
усім співавторам
вам (його помічнику з написання)
в ідеалі — призначеній особі з команди блогу.
Як помічник з написання, ви читаєте чернетку і або безпосередньо пропонуєте зміни, або надаєте відгук в інший спосіб. Автор допису дуже часто водночас є вашим помічником з написання, тож він так само надасть відгук на чернетку вашої статті.
Ваше завдання — порадити найменший набір змін, який зробить статтю придатною для публікації. Якщо діаграма справді не має сенсу або текст справді незрозумілий — надайте відгук. Якщо ж ви трохи інакше бачите формулювання чи пунктуацію, пропустіть це. Дозвольте автору (авторам) статті писати у власному стилі, якщо вони дотримуються настанов щодо блогу.
Коли все буде готово, головний автор відкриє pull request і подасть статтю в Markdown. Потім ви надаєте рецензію.
Деякі автори воліють почати зі спільного редагування; інші одразу переходять до GitHub.
Хоч би який шлях вони обрали, ваше завдання — надати відгук, який дасть змогу команді блогу просто погодити статтю й підтвердити, що її можна злити як чернетку. Що мають зробити автори, див. у Публікація статей у блогах Kubernetes.
Використовуйте функцію пропозицій GitHub, щоб вказати на будь-які необхідні зміни.
Коли Markdown та інший вміст (наприклад, зображення) виглядатимуть правильно, ви надасте офіційну рецензію.
Коли ви вважаєте, що відкритий pull request до блогу достатньо добрий для злиття, додайте до нього коментар /lgtm.
Це вказує інструменту автоматизації репозиторію (Prow), що вміст «looks good to me» (на мою думку, усе добре). Prow просуває справу далі. Команда /lgtm дає змогу зафіксувати вашу думку незалежно від того, чи є ви формально членом проєкту Kubernetes.
Ви або автор (автори) статті маєте повідомити команду блогу, що стаття готова до погодження. Її вже має бути позначено як draft: true у front matter, як пояснено в настановах щодо подання.
Наступні кроки
Для вас як помічника з написання четвертого кроку немає. Щойно pull request буде готовий до злиття, далі все бере на себе команда блогу (або, для сайту учасників, команда contributor comms). Можливо, за результатами відгуків вам доведеться повернутися до попереднього кроку, але зазвичай можна вважати, що ваша робота як помічника завершена.
3 - Пропозиції щодо покращення вмісту
Якщо ви помітили проблему в документації Kubernetes або маєте ідею для нового вмісту, створіть тікет. Усе, що вам потрібно, — обліковий запис GitHub і браузер.
У більшості випадків нова робота над документацією Kubernetes починається з тікета на GitHub. Потім учасники Kubernetes переглядають, класифікують і позначають тікети мітками за потреби. Далі ви або інший учасник спільноти Kubernetes відкриваєте pull request зі змінами, які розвʼязують проблему.
Створення тікета
Якщо ви хочете запропонувати покращення наявного вмісту або помітили помилку, створіть тікет.
Натисніть посилання Створити тікет на правій боковій панелі. Вас буде перенаправлено на сторінку тікета на GitHub з попередньо заповненими заголовками.
Опишіть проблему або пропозицію щодо покращення. Надайте якнайбільше деталей.
Натисніть Submit new issue.
Після подання час від часу перевіряйте свій тікет або ввімкніть сповіщення GitHub. Рецензенти й інші учасники спільноти можуть поставити запитання, перш ніж зможуть щось зробити з вашим тікетом.
Пропонування нового вмісту
Якщо у вас є ідея для нового вмісту, але ви не впевнені, де його розмістити, ви все одно можете створити тікет. Або:
Виберіть наявну сторінку в розділі, до якого, на вашу думку, належить вміст, і натисніть Створити тікет.
Надайте чіткий опис проблеми. Опишіть, що саме відсутнє, застаріле, неправильне або потребує покращення.
Поясніть конкретний вплив проблеми на користувачів.
Обмежте обсяг тікета розумним обсягом роботи. Великі проблеми розбийте на менші тікети. Наприклад, «Виправити документацію з безпеки» — занадто широко, а «Додати подробиці до теми 'Обмеження доступу до мережі'» — достатньо конкретно, щоб з цим можна було працювати.
Пошукайте наявні тікети, щоб побачити, чи є щось повʼязане або схоже на новий тікет.
Якщо новий тікет стосується іншого тікета або pull request, посилайтеся на нього або через повну URL-адресу, або через номер тікета або pull request з префіксом #. Наприклад, Introduced by #987654.
Дотримуйтеся Кодексу поведінки. Поважайте інших учасників. Наприклад, «Документація жахлива» — це не корисний і не ввічливий відгук.
4 - Внесення нового вмісту
У цьому розділі наведено інформацію, яку слід знати, перш ніж додавати новий вміст.
flowchart LR
subgraph second[Перш ніж розпочати]
direction TB
S[ ] -.-
A[Підпишіть CNCF CLA] --> B[Оберіть гілку Git]
B --> C[Одна мова на PR]
C --> F[Ознайомтесь з інструментами для участі]
end
subgraph first[Основи участі]
direction TB
T[ ] -.-
D[Пишіть документи в markdown та збирайте сайт за допомогою Hugo] --- E[сирці на GitHub]
E --- G[Тека '/content/../docs' містить документи для кількох мов]
G --- H[Ознайомтесь з типом вмісту сторінок Hugo та shortcodes]
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
Схема — підготовка до внесення нового вмісту
На схемі вище показано інформацію, яку слід знати, перш ніж подавати новий вміст. Подробиці наведено нижче.
Основи участі
Пишіть документацію Kubernetes у Markdown та збирайте сайт Kubernetes за допомогою Hugo.
Документація Kubernetes використовує CommonMark як свій варіант Markdown.
Вихідний код розміщено на GitHub. Документацію Kubernetes можна знайти в /content/en/docs/. Частина довідкової документації автоматично генерується скриптами в теці update-imported-docs/.
Крім стандартних shortcodes Hugo, ми використовуємо в документації низку власні shortcodes Hugo для керування поданням вмісту.
Вихідний код документації доступний кількома мовами в /content/. Кожна мова має власну теку з дволітерним кодом, визначеним стандартом ISO 639-1. Наприклад, вихідний код англійської документації зберігається в /content/en/docs/.
Докладніше про внесок у документацію кількома мовами або початок нового перекладу див. локалізацію.
Pull request від учасників, які не підписали CLA, не проходять автоматизовані тести. Імʼя та електронна адреса, які ви вказуєте, мають збігатися з тими, що є у вашому git config, а ваші імʼя та електронна адреса в git мають збігатися з тими, що використовуються для CNCF CLA.
Вибір гілки Git
Відкриваючи pull request, потрібно заздалегідь знати, на якій гілці базувати свою роботу.
Сценарій
Гілка
Наявний або новий вміст англійською для поточного випуску
main
Вміст для випуску зі зміною можливостей
Гілка, що відповідає major- і minor-версії, у якій відбувається зміна можливості, за шаблоном dev-<version>. Наприклад, якщо можливість змінюється у випуску v1.38, то додайте зміни до документації у гілку dev-1.38.
Якщо ви досі не впевнені, яку гілку вибрати, запитайте в #sig-docs у Slack.
Примітка:
Якщо ви вже подали свій pull request і знаєте, що базова гілка неправильна, ви (і лише ви, автор PR) можете її змінити.
Мови в одному PR
Обмежуйте pull request однією мовою. Якщо потрібно внести однакову зміну в той самий приклад коду кількома мовами, відкрийте окремий PR для кожної мови.
Інструменти для учасників
Тека інструментів для учасників у репозиторії kubernetes/website містить інструменти, які допоможуть вам робити внесок легше.
Before you're going to open a new PR, previewing your changes is recommended. A preview lets you catch build errors or markdown formatting problems.
Попередній перегляд змін локально
Ви можете або зібрати образ контейнера вебсайту, або запустити Hugo локально. Збирання образу контейнера повільніше, але показує shortcodes Hugo, що може бути корисним для налагодження.
Примітка:
Наведені нижче команди стандартно використовують Docker як рушій контейнерів. Щоб змінити цю поведінку, задайте змінну середовища CONTAINER_ENGINE.
Створіть образ контейнера локально Цей крок необхідний лише у випадку, якщо ви тестуєте зміни в самому інструменті Hugo
# Запустіть це в терміналі (якщо потрібно)make container-image
Завантажте залежності субмодуля у свій локальний репозиторій:
# Запустіть це в терміналіmake module-init
Запустіть Hugo в контейнері:
# Запустіть це в терміналіmake container-serve
У браузері перейдіть за адресою http://localhost:1313. Hugo відстежує зміни та за потреби перебудовує сайт.
Щоб зупинити локальний екземпляр Hugo, поверніться до терміналу та натисніть Ctrl+C або закрийте вікно терміналу.
Або ж встановіть і використовуйте команду hugo на своєму компʼютері:
У терміналі перейдіть до репозиторію вебсайту Kubernetes і запустіть сервер Hugo:
cd <path_to_your_repo>/website
make serve
Якщо ви працюєте на компʼютері з Windows або не можете виконати команду make, скористайтеся такою командою:
hugo server --config hugo.toml,hugo.server.toml --buildFuture
У браузері перейдіть за адресою http://localhost:1313. Hugo відстежує зміни та за потреби перебудовує сайт.
Щоб зупинити локальний екземпляр Hugo, поверніться до терміналу та натисніть Ctrl+C або закрийте вікно терміналу.
Усунення несправностей
error: failed to transform resource: TOCSS: failed to transform "scss/main.scss" (text/x-scss): this feature is not available in your current Hugo version
З технічних причин Hugo постачається у двох наборах бінарних файлів. Поточний вебсайт працює лише на версії Hugo Extended. На сторінці випусків шукайте архіви з extended у назві. Щоб переконатися, виконайте hugo version і знайдіть слово extended.
Усунення несправностей macOS через забагато відкритих файлів
Якщо ви запускаєте make serve в macOS і отримуєте таку помилку:
ERROR 2020/08/01 19:09:18 Error: listen tcp 127.0.0.1:1313: socket: too many open files
make: *** [serve] Error 1
Спробуйте перевірити поточне обмеження на кількість відкритих файлів:
#!/bin/sh
# These are the original gist links, linking to my gists now.# curl -O https://gist.githubusercontent.com/a2ikm/761c2ab02b7b3935679e55af5d81786a/raw/ab644cb92f216c019a2f032bbf25e258b01d87f9/limit.maxfiles.plist# curl -O https://gist.githubusercontent.com/a2ikm/761c2ab02b7b3935679e55af5d81786a/raw/ab644cb92f216c019a2f032bbf25e258b01d87f9/limit.maxproc.plistcurl -O https://gist.githubusercontent.com/tombigel/d503800a282fcadbee14b537735d202c/raw/ed73cacf82906fdde59976a0c8248cce8b44f906/limit.maxfiles.plist
curl -O https://gist.githubusercontent.com/tombigel/d503800a282fcadbee14b537735d202c/raw/ed73cacf82906fdde59976a0c8248cce8b44f906/limit.maxproc.plist
sudo mv limit.maxfiles.plist /Library/LaunchDaemons
sudo mv limit.maxproc.plist /Library/LaunchDaemons
sudo chown root:wheel /Library/LaunchDaemons/limit.maxfiles.plist
sudo chown root:wheel /Library/LaunchDaemons/limit.maxproc.plist
sudo launchctl load -w /Library/LaunchDaemons/limit.maxfiles.plist
Це працює як для macOS Catalina, так і для Mojave.
Unable to find image 'gcr.io/k8s-staging-sig-docs/k8s-website-hugo:VERSION' locally
Якщо ви запускаєте make container-serve і бачите цю помилку, причиною можуть бути локальні зміни у файлах, визначених у $IMAGE_VERSION файлу Makefile.
Версія образу вебсайту містить хеш, який генерується на основі вмісту перелічених файлів. Наприклад, якщо 1b9242684415 — хеш цих файлів, образ вебсайту називатиметься k8s-website-hugo:v0.133.0-1b9242684415. Виконання make container-serve спробує завантажити такий образ із GCR вебсайту Kubernetes. Якщо це не поточна версія, ви побачите помилку про те, що такого образу немає.
Якщо вам потрібно внести зміни в ці файли й переглянути вебсайт, доведеться зібрати локальний образ замість завантаження готового. Для цього виконайте make container-image.
Інші проблеми
Якщо у вас виникли інші проблеми з локальним запуском вебсайту та/або попереднім переглядом змін, не соромтеся створити тікет у репозиторії GitHub kubernetes/website.
4.2 - Документування можливості для випуску
Кожен великий випуск Kubernetes запроваджує нові можливості, які потребують документації. Нові випуски також приносять оновлення наявних можливостей і документації (наприклад, переведення можливості з alpha до beta).
Зазвичай SIG, відповідальна за можливість, подає чернетку документації можливості як pull request до відповідної гілки розробки репозиторію kubernetes/website, а хтось із команди SIG Docs надає редакторські відгуки або безпосередньо редагує чернетку. У цьому розділі описано домовленості щодо гілок і процес, яких обидві групи дотримуються під час випуску.
Зазвичай автори документації не пишуть вміст для випуску з нуля. Натомість вони працюють із SIG, яка створює нову можливість, щоб доопрацювати чернетку документації й підготувати її до випуску.
Вибравши можливість, яку хочете задокументувати або з якою хочете допомогти, запитайте про неї в Slack-каналі #sig-docs, на щотижневій зустрічі SIG Docs або безпосередньо в PR, поданому SIG цієї можливості. Якщо вам дадуть згоду, ви можете вносити зміни в PR одним зі способів, описаних у Коміти в PR іншої особи.
Дізнайтеся про майбутні можливості
Щоб дізнатися про майбутні можливості, відвідуйте щотижневу зустріч SIG Release (майбутні зустрічі див. на сторінці спільноти) і стежте за документацією конкретного випуску в репозиторії kubernetes/sig-release. Кожен випуск має підтеку в теці /sig-release/tree/master/releases/. Підтека містить розклад випуску, чернетку приміток до випуску та документ зі списком усіх членів команди випуску.
Розклад випуску містить посилання на всі інші документи, зустрічі, протоколи зустрічей і віхи, повʼязані з випуском. Він також містить інформацію про цілі та графік випуску й будь-які особливі процеси для цього випуску. Ближче до кінця документа наведено визначення кількох термінів, повʼязаних із випуском.
Цей документ також містить посилання на Feature tracking sheet — офіційний спосіб дізнатися про всі нові можливості, заплановані до випуску.
Документ команди випуску вказує, хто відповідає за кожну роль у випуску. Якщо незрозуміло, до кого звернутися щодо конкретної можливості чи вашого запитання, або відвідайте зустріч випуску й поставте запитання там, або зверніться до керівника випуску, щоб він вас спрямував.
Чернетка приміток до випуску — гарне місце, щоб дізнатися про конкретні можливості, зміни, застарівання та інше щодо випуску. Вміст не остаточний до пізнього етапу циклу випуску, тож користуйтеся ним обережно.
Таблиця відстеження можливостей
Таблиця відстеження можливостей для конкретного випуску Kubernetes містить перелік усіх можливостей, запланованих для випуску. Кожен рядок містить назву можливості, посилання на її основний тікет на GitHub, рівень стабільності (Alpha, Beta або Stable), SIG та особу, відповідальних за реалізацію, чи потрібна документація, чернетку примітки до випуску для можливості та чи її злито. Майте на увазі таке:
Можливості Beta і Stable зазвичай мають вищий пріоритет документування, ніж можливості Alpha.
Складно протестувати (а отже, і задокументувати) можливість, яку ще не злито або яка принаймні не вважається завершеною у своєму PR.
Визначення того, чи потребує можливість документації, — ручний процес. Навіть якщо можливість не позначено як таку, що потребує документації, вам, можливо, доведеться її задокументувати.
Для розробників або інших учасників SIG
Цей розділ містить інформацію для членів інших SIG Kubernetes, які документують нові можливості для випуску.
Якщо ви член SIG, яка розробляє нову можливість для Kubernetes, вам потрібно працювати з SIG Docs, щоб вашу можливість задокументували вчасно до випуску. Перегляньте таблицю відстеження можливостей або уточніть у Slack-каналі Kubernetes #sig-release подробиці розкладу та терміни.
Відкрийте placeholder PR
Відкрийте чернетку pull request до гілки dev-1.38 у репозиторії kubernetes/website з невеликим комітом, який згодом зміните. Щоб створити чернетку pull request, у спадному меню Create Pull Request виберіть Create Draft Pull Request, а потім натисніть Draft Pull Request.
Залиште коментар у відповідному тікеті kubernetes/enhancements з посиланням на PR, щоб повідомити відповідальну за документацію особу, яка керує цим випуском, що документація можливості готується і її слід відстежувати для випуску.
Якщо ваша можливість не потребує змін документації, переконайтеся, що команда sig-release про це знає, — повідомте в Slack-каналі #sig-release. Якщо можливість потребує документації, але PR не створено, можливість можуть вилучити з milestone.
PR готовий до рецензування
Коли будете готові, наповніть свій placeholder PR документацією можливості та змініть стан PR з чернетки на ready for review. Щоб позначити pull request як готовий до рецензування, перейдіть до блоку злиття й натисніть Ready for review.
Якнайкраще опишіть свою можливість і те, як її використовувати. Якщо вам потрібна допомога зі структурою документації, запитайте в Slack-каналі #sig-docs.
Коли ви завершите вміст, його рецензує особа з документації, призначена для вашої можливості. Для забезпечення технічної точності вміст також може потребувати технічного рецензування від відповідних SIG. Використайте їхні пропозиції, щоб довести вміст до готовності до випуску.
Якщо ваша можливість потребує документації, а першої чернетки вмісту не отримано, можливість можуть вилучити з milestone.
Функціональні можливості (feature gates)
Якщо ваша можливість на етапі Alpha або Beta і прихована за функціональною можливістю (feature gate), для неї потрібен файл функціональної можливості в content/en/docs/reference/command-line-tools-reference/feature-gates/. Назвою файлу має бути назва функціональної можливості з суфіксом .md. Як має виглядати ваш файл, можна подивитися в інших файлах цієї теки. Зазвичай достатньо одного абзацу; для довших пояснень додайте документацію деінде й посилайтеся на неї.
stages:- stage:<alpha/beta/stable/deprecated> # Вкажіть етап розробки функціональної можливостіdefaultValue:<true or false> # Встановіть true, якщо стандартно ввімкнено, інакше falsefromVersion:<Version> # Версія, з якої доступна функціональна можливістьtoVersion:<Version> # (Необовʼязково) Версія, до якої функціональна можливість доступна
Для зовсім нових функціональних можливостей також потрібен окремий опис; створіть новий файл Markdown у content/en/docs/reference/command-line-tools-reference/feature-gates/ (використовуйте інші файли як шаблон).
Коли ви змінюєте функціональну можливість зі стандартно вимкненої на стандартно ввімкнену, може знадобитися змінити й іншу документацію (не лише список функціональних можливостей). Звертайте увагу на формулювання на кшталт «Поле exampleSetting є beta-полем і стандартно вимкнене. Його можна ввімкнути, увімкнувши функціональну можливість ProcessExampleThings.»
stages:- stage:alphadefaultValue:falsefromVersion:"1.12"toVersion:"1.12"- stage:betadefaultValue:truefromVersion:"1.13"# Додано `toVersion` до попереднього етапу.toVersion:"1.18"# Додано блок етапу 'stable' до наявних етапів.- stage:stabledefaultValue:truefromVersion:"1.19"toVersion:"1.27"
Зрештою Kubernetes узагалі перестане включати функціональну можливість. Щоб позначити вилучення функціональної можливості, додайте removed: true у front matter відповідного файлу опису. Після цієї зміни інформація про функціональну можливість разом з її описом переміщується з розділу Функціональні можливості для завершених або застарілих можливостей на окрему сторінку Функціональні можливості (вилучені).
Усі PR відрецензовано й готово до злиття
Якщо ваш PR ще не злито в гілку dev-1.38 до крайнього терміну випуску, працюйте з відповідальною за документацію особою, яка керує випуском, щоб встигнути до терміну. Якщо ваша можливість потребує документації, а документація не готова, можливість можуть вилучити з milestone.
4.3 - Подання прикладів використання
Приклади використання показують, як організації використовують Kubernetes для розвʼязання реальних проблем. Команда маркетингу Kubernetes та члени CNCF разом з вами працюватимуть над усіма прикладами використання.
Приклади використання ретельно рецензують, перш ніж затвердити.
5.1 - Рецензування для затверджувачів та рецензентів
Рецензенти та затверджувачі SIG Docs під час рецензування змін виконують кілька додаткових дій.
Щотижня певний затверджувач документації добровільно береться розглядати (triage) й рецензувати pull request. Ця особа є "PR Wrangler" (відповідальним за PR) на тиждень. Докладніше див. графік PR Wrangler. Щоб стати PR Wrangler, відвідайте щотижневу зустріч SIG Docs і зголосіться. Навіть якщо вас немає в графіку на поточний тиждень, ви все одно можете рецензувати pull request (PR), які ще ніхто активно не рецензує.
Окрім чергування, бот призначає рецензентів і затверджувачів для PR на основі власників змінених файлів.
Усе, що описано в Рецензування pull request, стосується й цього випадку, але рецензенти та затверджувачі мають також:
За потреби призначати конкретного рецензента для PR командою Prow /assign. Це особливо важливо, коли потрібна технічна рецензія від учасників, які працюють над кодом.
Примітка:
Подивіться поле reviewers у front matter на початку файлу Markdown, щоб дізнатися, хто може надати технічну рецензію.
Перевіряти, що PR відповідає посібникам з вмісту і стилю; якщо ні, давати автору посилання на відповідну частину посібника (посібників).
За потреби використовувати в GitHub параметр Request Changes, щоб запропонувати зміни автору PR.
Змінювати статус своєї рецензії в GitHub командами Prow /approve або /lgtm, якщо ваші пропозиції враховано.
Коміти в PR іншої особи
Залишати коментарі до PR корисно, але інколи може знадобитися зробити коміт у PR іншої особи.
Не "перебирайте на себе" роботу іншої людини, якщо вона прямо не попросить вас про це або якщо ви не хочете відновити давно покинутий PR. Хоча в короткій перспективі так може бути швидше, це позбавляє людину можливості зробити внесок.
Процес залежить від того, чи потрібно редагувати файл, який уже входить до PR, чи файл, якого PR ще не торкався.
Ви не можете робити коміти в чужий PR, якщо виконується будь-яка з таких умов:
Автор PR надіслав (push) свою гілку безпосередньо до репозиторію https://github.com/kubernetes/website/. Робити коміти в PR іншого користувача може лише рецензент із правом push.
Примітка:
Заохочуйте автора наступного разу надсилати свою гілку у свій форк, перш ніж відкривати PR.
Автор PR явно забороняє редагування з боку затверджувачів.
Команди Prow для рецензування
Prow — це система CI/CD на основі Kubernetes, яка запускає завдання для pull request (PR). Prow дає змогу виконувати команди в стилі чат-бота для дій GitHub у всій організації Kubernetes, як-от додавання та видалення міток, закриття тікетів і призначення затверджувача. Вводьте команди Prow як коментарі GitHub у форматі /<command-name>.
Найпоширеніші команди Prow, які використовують рецензенти та затверджувачі:
Команди Prow для рецензування
Команда Prow
Обмеження ролей
Опис
/lgtm
Члени організації
Сигналізує, що ви завершили огляд PR і задоволені змінами.
/approve
Затверджувачі
Затверджує PR для злиття.
/assign
Будь-хто
Призначає людину для огляду або затвердження PR
/close
Члени організації
Закриває тікет або PR.
/hold
Будь-хто
Додає мітку do-not-merge/hold, що означає, що PR не може бути автоматично злитий.
/hold cancel
Будь-хто
Видаляє мітку do-not-merge/hold.
Щоб переглянути команди, які можна використовувати в PR, див. довідник команд Prow.
Цей фільтр тікетів GitHub знаходить тікети, які можуть потребувати класифікації.
Класифікація тікета
Перевірте тікет
Переконайтеся, що тікет стосується документації вебсайту. Деякі тікети можна швидко закрити, відповівши на запитання або вказавши автору на ресурс. Докладніше див. розділ Запити на підтримку або звіти про помилки в коді.
Оцініть, чи має тікет сенс.
Додайте мітку triage/needs-information, якщо в тікеті недостатньо подробиць, щоб із ним можна було працювати, або шаблон заповнено неналежно.
Закрийте тікет, якщо він має мітки lifecycle/stale та triage/needs-information.
Додайте мітку пріоритету (докладні визначення міток пріоритету наведено в Issue Triage Guidelines)
Мітки тікетів
Мітка
Опис
priority/critical-urgent
Виконати негайно.
priority/important-soon
Виконати протягом 3 місяців.
priority/important-longterm
Виконати протягом 6 місяців.
priority/backlog
Відкладено на невизначений термін. Виконати, коли будуть ресурси.
priority/awaiting-more-evidence
Зберегти як потенційно важливу проблему, щоб вона не загубилася.
help або good first issue
Підходить для тих, хто має дуже мало досвіду з Kubernetes або SIG Docs. Див. Мітки Help Wanted та Good First Issue для отримання додаткової інформації.
На власний розсуд ви можете взяти тікет на себе й подати для нього PR (особливо якщо це швидко або повʼязано з роботою, яку ви вже виконуєте).
Якщо у вас є запитання щодо класифікації тікета, звертайтеся до каналу #sig-docs у Slack або у розсилку kubernetes-sig-docs.
Додавання та видалення міток тікетів
Щоб додати мітку, залиште коментар в одному з наступних форматів:
/<label-to-add> (наприклад, /good-first-issue)
/<label-category> <label-to-add> (наприклад, /triage needs-information або /language ja)
Щоб видалити мітку, залиште коментар в одному з наступних форматів:
/remove-<label-to-remove> (наприклад, /remove-help)
/remove-<label-category> <label-to-remove> (наприклад, /remove-triage needs-information)
В обох випадках мітка має вже існувати. Якщо ви спробуєте додати мітку, якої не існує, команду буде мовчки проігноровано.
Тікети зазвичай відкривають і закривають швидко. Однак іноді тікет після відкриття стає неактивним. А іноді тікет має залишатися відкритим довше ніж 90 днів.
Мітки життєвого циклу тікета
Мітка
Опис
lifecycle/stale
Після 90 днів без активності тікет автоматично позначається як застарілий. Тікет буде автоматично закрито, якщо життєвий цикл не буде вручну повернуто за допомогою команди /remove-lifecycle stale.
lifecycle/frozen
Тікет з цією міткою не стане застарілим після 90 днів без активності. Користувач вручну додає цю мітку до тікетів, які потрібно залишити відкритими набагато довше 90 днів, таких як ті, що мають мітку priority/important-longterm.
Обробка особливих типів тікетів
SIG Docs стикається з такими типами тікетів досить часто, щоб варто було задокументувати, як їх обробляти.
Дублікати тікетів
Якщо для однієї проблеми відкрито один або кілька тікетів, обʼєднайте їх в один тікет. Вирішіть, який тікет залишити відкритим (або відкрийте новий), потім перенесіть усю потрібну інформацію та повʼяжіть повʼязані тікети. Нарешті, позначте всі інші тікети, що описують ту саму проблему, міткою triage/duplicate і закрийте їх. Один тікет для роботи зменшує плутанину й дає змогу уникнути дублювання роботи над тією самою проблемою.
Проблеми з недійсними посиланнями
Якщо тікет про недійсне посилання стосується документації API або kubectl, присвойте йому мітку /priority critical-urgent, поки проблема не буде повністю зрозуміла. Для всіх інших проблем з недійсними посиланнями використовуйте мітку /priority important-longterm, оскільки їх потрібно виправляти вручну.
Проблеми з блогом
Ми очікуємо, що дописи в блозі Kubernetes з часом застарівають. Тому ми підтримуємо лише дописи, яким менше року. Якщо тікет стосується допису, якому понад рік, зазвичай його слід закрити без виправлення.
Ви можете надіслати посилання на оновлення та підтримку статей як частину повідомлення, яке ви надсилаєте, коли закриваєте PR.
Можна зробити виняток, якщо є відповідне обґрунтування.
Запити на підтримку або звіти про помилки в коді
Деякі тікети щодо документації насправді стосуються проблем із кодом або є проханнями про допомогу, коли щось, наприклад підручник, не працює. Тікети, не повʼязані з документацією, закривайте з міткою kind/support і коментарем, що спрямовує автора до каналів підтримки (Slack, Stack Overflow) і, якщо доречно, до репозиторію, де можна створити тікет про помилки в можливостях (kubernetes/kubernetes — гарне місце для початку).
Приклад відповіді на запит про підтримку:
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.
Приклад відповіді на звіт про помилку в коді:
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.
Обʼєднання комітів (squashing)
Як затверджувач, рецензуючи pull request (PR), ви в різних випадках можете зробити таке:
Порадити автору обʼєднати коміти.
Обʼєднати коміти для автора.
Порадити автору поки що не обʼєднувати коміти.
Запобігти обʼєднанню.
Порада авторам обʼєднати коміти: нові учасники можуть не знати, що коміти у своїх pull request (PR) слід обʼєднувати. Якщо це так, порадьте їм це зробити, дайте посилання на корисну інформацію і запропонуйте організувати допомогу, якщо вона потрібна. Корисні посилання:
Обʼєднання комітів за учасників: якщо учаснику може бути складно обʼєднати коміти або PR потрібно злити терміново, ви можете виконати обʼєднання за нього:
Якщо автор PR дозволяє супровідникам керувати PR, ви можете обʼєднати його коміти й оновити його форк результатом. Перш ніж обʼєднувати, порадьте йому зберегти й надіслати (push) свої останні зміни до PR. Після обʼєднання порадьте йому підтягнути (pull) обʼєднаний коміт у свій локальний клон.
Ви можете змусити GitHub обʼєднати коміти за допомогою мітки, щоб обʼєднання виконали Tide / GitHub, або натиснувши кнопку Squash commits під час злиття PR.
Порада авторам не обʼєднувати коміти
Якщо один коміт робить щось зламане чи нерозумне, а останній коміт скасовує цю помилку, не обʼєднуйте коміти. Хоча вкладка "Files changed" у PR на GitHub і попередній перегляд Netlify виглядатимуть нормально, злиття такого PR може спричинити конфлікти rebase або merge в інших людей. Втручайтеся на власний розсуд, щоб уберегти інших учасників від цього ризику.
Ніколи не обʼєднуйте
Якщо ви запускаєте локалізацію або випускаєте документацію для нової версії, ви зливаєте гілку, яка не походить із форку користувача, — ніколи не обʼєднуйте коміти. Відмова від обʼєднання тут обовʼязкова, бо потрібно зберегти історію комітів для цих файлів.
SIG Docs вітає вміст і рецензії від усіх учасників. Будь-хто може відкрити pull request (PR), і будь-хто може створювати тікети щодо вмісту або коментувати pull request, над якими ще триває робота.
Ви також можете стати членом, рецензентом або затверджувачем. Ці ролі потребують ширшого доступу й передбачають певні обовʼязки щодо затвердження та внесення змін. Докладніше про те, як працює членство в спільноті Kubernetes, див. community-membership.
Решта цього документа описує деякі унікальні способи функціонування цих ролей у SIG Docs, яка відповідає за підтримку одного з найбільш публічно орієнтованих аспектів Kubernetes — вебсайту та документації Kubernetes.
Голова SIG Docs
Кожна SIG, зокрема SIG Docs, обирає одного або кількох членів SIG на роль голів. Вони є контактними особами між SIG Docs та іншими частинами організації Kubernetes. Від них вимагається глибоке знання структури проєкту Kubernetes загалом і того, як у ньому працює SIG Docs. Актуальний список голів див. у Leadership.
Команди та автоматизація SIG Docs
Автоматизація в SIG Docs спирається на два різні механізми: команди GitHub і файли OWNERS.
@sig-docs-{language}-owners — затверджувачі та лідери
@sig-docs-{language}-reviews — рецензенти
До кожної з них можна звернутися через її @name у коментарях на GitHub, щоб написати всім у цій групі.
Іноді команди Prow і GitHub перетинаються, але не збігаються повністю. Для призначення тікетів і pull request, а також для підтримки затвердження PR автоматизація використовує інформацію з файлів OWNERS.
Файли OWNERS та front-matter
Проєкт Kubernetes використовує інструмент автоматизації prow для автоматизації, повʼязаної з тікетами та pull request на GitHub. Репозиторій вебсайту Kubernetes використовує два втулки prow:
blunderbuss
approve
Ці два втулки використовують файли OWNERS та OWNERS_ALIASES на верхньому рівні репозиторію kubernetes/website GitHub для контролю роботи prow у репозиторії.
Файл OWNERS містить список людей, які є рецензентами та затверджувачами SIG Docs. Файли OWNERS також можуть існувати в підтеках та можуть перевизначати, хто може виступати як рецензент або затверджувач файлів у цій теці та вкладених теках. Для отримання додаткової інформації про файли OWNERS в цілому дивіться OWNERS.
Крім того, окремий файл Markdown може містити у своєму front-matter список рецензентів і затверджувачів — окремі імена користувачів GitHub або групи GitHub.
Комбінація файлів OWNERS і front-matter у файлах Markdown визначає поради, які власники PR отримують від автоматизованих систем щодо того, кого попросити про технічне та редакторське рецензування їхнього PR.
Як працює злиття
Коли pull request зливають у гілку, з якої публікується вміст, цей вміст публікується на https://kubernetes.io. Щоб забезпечити високу якість опублікованого вмісту, ми дозволяємо зливати pull request лише затверджувачам SIG Docs. Ось як це працює.
Коли pull request має обидві мітки lgtm та approve, не має міток hold та всі тести проходять успішно, pull request зливається автоматично.
Члени організації Kubernetes і затверджувачі SIG Docs можуть додавати коментарі, щоб запобігти автоматичному злиттю певного pull request (додавши коментар /hold або утримуючись від коментаря /lgtm).
Будь-який член Kubernetes може додати мітку lgtm, додавши коментар /lgtm.
Лише затверджувачі SIG Docs можуть злити pull request, додавши коментар /approve. Деякі затверджувачі також виконують додаткові ролі, як-от відповідальний за PR або голова SIG Docs.
Використовуйте цей скрипт, щоб нагадати учасникам, які не підписали CLA, зробити це.
Надавайте відгуки щодо змін і просіть членів інших SIG про технічне рецензування.
Пропонуйте зміни вмісту безпосередньо в рядках PR (inline suggestions).
Якщо потрібно перевірити вміст, залиште коментар у PR і попросіть більше подробиць.
Призначте відповідні мітки sig/.
За потреби призначте рецензентів із блоку reviewers: у front matter файлу.
Також можна позначити SIG для рецензування, залишивши в PR коментар @kubernetes/<sig>-pr-reviews.
Використовуйте коментар /approve, щоб затвердити PR для злиття. Зливайте PR, коли він готовий.
PR мають отримати коментар /lgtm від іншого члена перед злиттям.
Розгляньте можливість прийняти технічно точний вміст, який не відповідає настановам зі стилю. Затверджуючи зміну, відкрийте новий тікет щодо проблеми зі стилем. Зазвичай такі тікети з виправлення стилю можна оформити як good first issue.
Використання виправлень стилю як good first issue — хороший спосіб мати запас простіших завдань, які допомагають залучати нових учасників.
Обовʼязки відповідального за PR не стосуються PR локалізації (неанглійських PR). Команди локалізації мають власні процеси й команди для рецензування PR своєю мовою. Однак часто корисно перевірити, чи правильно позначено мовні PR, рецензувати невеликі PR, що не залежать від мови (як-от оновлення посилань), або позначати рецензентів чи учасників у довготривалих PR (відкритих понад 6 місяців тому, які не оновлювалися місяць або довше).
Корисні запити GitHub для відповідальних
Такі запити корисні під час роботи відповідального. Після опрацювання цих запитів список PR для рецензування зазвичай невеликий. Ці запити виключають PR локалізації. Усі запити стосуються гілки main, крім останнього.
Без CLA, не можна зливати: Нагадайте учаснику підписати CLA. Якщо і бот, і людина вже нагадали, закрийте PR і нагадайте, що його можна відкрити знову після підписання CLA. Не рецензуйте PR, автори яких не підписали CLA!
Потребує LGTM: Перелік PR, яким потрібен LGTM від члена. Якщо PR потребує технічного рецензування, залучіть одного з рецензентів, запропонованих ботом. Якщо вміст потребує доопрацювання, додайте пропозиції та відгуки в рядках.
Швидкі виграші: Перелік PRʼів до основної гілки без явних блокувань. (змініть "XS" у мітці розміру, коли будете працювати з PRʼами [XS, S, M, L, XL, XXL]).
Не до основної гілки: Якщо PR до гілки dev-, він для майбутнього випуску. Призначте менеджера випуску документації командою /assign @<manager's_github-username>. Якщо PR до старої гілки, допоможіть автору зʼясувати, чи спрямовано його на найкращу гілку.
Корисні команди Prow для відповідальних
# додати мітку англійської мови
/language en
# додати мітку squash до PR, якщо в ньому більше одного коміту
/label tide/merge-method-squash
# перейменувати PR через Prow (наприклад, робота в процесі [WIP] або кращий опис PR)
/retitle [WIP] <TITLE>
Коли закривати pull request
Рецензування й затвердження — один з інструментів, що допомагають тримати чергу PR короткою та актуальною. Ще один інструмент — закриття.
Закривайте PR, якщо:
Автор не підписав CLA протягом двох тижнів.
Автори можуть відкрити PR знову після підписання CLA. Це малоризикований спосіб переконатися, що нічого не зливається без підписаного CLA.
Автор не відповів на коментарі чи відгуки протягом 2 або більше тижнів.
Не бійтеся закривати pull request. Учасники можуть легко відкрити їх знову й продовжити незавершену роботу. Часто саме повідомлення про закриття спонукає автора повернутися й завершити свій внесок.
Щоб закрити pull request, залиште коментар /close у PR.
Примітка:
Бот k8s-triage-robot позначає тікети як застарілі (stale) після 90 днів неактивності. Ще через 30 днів він позначає їх як покинуті (rotten) і закриває. Відповідальні за PR мають закривати тікети після 14–30 днів неактивності.
Програма тіньового відповідального за PR
Наприкінці 2021 року SIG Docs запровадила PR Wrangler Shadow Program. Програму запроваджено, щоб допомогти новим учасникам зрозуміти процес роботи відповідального за PR.
Як стати тіньовим відповідальним за PR
Якщо ви хочете бути тіньовим відповідальним за PR, перейдіть на вікі-сторінку PR Wranglers, щоб переглянути графік відповідальних за PR на цей рік і зареєструватися.
Кожного дня тижневої зміни відповідальний за тікети має:
Щодня розглядати нові тікети й позначати їх мітками. Настанови щодо того, як SIG Docs використовує метадані, див. у Класифікація та категоризація проблем.
Стежити за застарілими (stale) і покинутими (rotten) тікетами в репозиторії kubernetes/website.
Щонайменше 15 нетривіальних внесків у Kubernetes (певна частина з яких має стосуватися kubernetes/website).
Уже неофіційно виконувати цю роль.
Корисні команди Prow для відповідальних за тікети
Нижче наведено деякі команди, які часто використовують відповідальні за тікети:
# повторно відкрити тікет/reopen
# перенести тікети, які не підходять для k/website, до іншого репозиторію/transfer[-issue]# змінити стан покинутих (rotten) тікетів/remove-lifecycle rotten
# змінити стан застарілих (stale) тікетів/remove-lifecycle stale
# призначити тікету SIG/sig <sig_name>
# додати конкретну область/area <area_name>
# для тікетів, що підходять для початківців/good-first-issue
# тікети, що потребують допомоги/help wanted
# позначити тікет як запит на підтримку/kind support
# прийняти тікет за результатами розгляду/triage accepted
# закрити тікет, над яким ми не працюватимемо і який ще не виправлено/close not-planned
Щоб знайти більше команд Prow, зверніться до документації Command Help.
Коли закривати тікети
Для успіху проєкту з відкритим кодом дуже важливо добре керувати тікетами. Але не менш важливо закривати тікети, щоб підтримувати репозиторій і чітко спілкуватися з учасниками та користувачами.
Закривайте тікети, коли:
Про схожу проблему повідомлено більше одного разу. Спочатку позначте тікет як /triage duplicate, повʼяжіть його з основним тікетом, а потім закрийте. Також варто спрямувати користувачів до оригінального тікета.
З наданою інформацією дуже важко зрозуміти й розвʼязати проблему, описану автором. Однак заохочуйте користувача надати більше подробиць або повторно відкрити тікет, якщо він зможе відтворити проблему пізніше.
Та сама функціональність уже реалізована деінде. Цей тікет можна закрити й спрямувати користувача в потрібне місце.
Проблема, про яку повідомлено, наразі не запланована або не відповідає цілям проєкту.
Якщо тікет виглядає як спам і явно не стосується теми.
Якщо проблема повʼязана із зовнішнім обмеженням чи залежністю і проєкт не може на неї вплинути.
Щоб закрити тікет, залиште в ньому коментар /close.
7 - Огляд стилю документації
Матеріали цього розділу містять настанови щодо стилю написання, форматування та організації вмісту, а також використання специфічних для документації Kubernetes налаштувань Hugo.
7.1 - Посібник з вмісту документації
Ця сторінка містить настанови щодо документації Kubernetes.
Якщо у вас є запитання щодо того, що дозволено, приєднайтеся до каналу #sig-docs у Kubernetes Slack і запитайте!
Інформацію про створення нового вмісту для документації Kubernetes див. у посібнику зі стилю.
Огляд
Вихідний код вебсайту Kubernetes, зокрема документації, розміщено в репозиторії kubernetes/website.
Більшість документації Kubernetes розташована в теці kubernetes/website/content/<language_code>/docs і стосується саме проєкту Kubernetes.
Що дозволено
Документація Kubernetes допускає вміст для сторонніх проєктів лише тоді, коли:
Вміст документує програмне забезпечення в проєкті Kubernetes
Вміст документує програмне забезпечення поза проєктом, яке потрібне для роботи Kubernetes
Вміст є канонічним на kubernetes.io або посилається на канонічний вміст в іншому місці
Сторонній вміст
Документація Kubernetes містить прикладні приклади проєктів, що входять до проєкту Kubernetes, — проєктів, розміщених в організаціях GitHub kubernetes і kubernetes-sigs.
Посилання на активний вміст у проєкті Kubernetes завжди дозволені.
Для роботи Kubernetes потрібен деякий сторонній вміст. Приклади — середовища виконання контейнерів (containerd, CRI-O, Docker), мережеві політики (втулки CNI), контролери Ingress і логування.
Документація може посилатися на стороннє програмне забезпечення з відкритим кодом (OSS) поза проєктом Kubernetes лише тоді, коли воно потрібне для роботи Kubernetes.
Вміст із подвійним джерелом
Коли це можливо, документація Kubernetes посилається на канонічні джерела замість розміщення вмісту з подвійним джерелом.
Вміст із подвійним джерелом потребує вдвічі більше зусиль (або й більше!) на підтримку і швидше застаріває.
Примітка:
Якщо ви супровідник проєкту Kubernetes і вам потрібна допомога з розміщенням власної документації, попросіть допомоги в #sig-docs у Kubernetes Slack.
Додаткова інформація
Якщо у вас є запитання щодо дозволеного вмісту, приєднайтеся до каналу #sig-docs у Kubernetes Slack і запитайте!
Цей сайт використовує Hugo. У Hugo організація вмісту — одне з ключових понять.
Примітка:
Порада щодо Hugo: для сеансів редагування вмісту запускайте Hugo командою hugo server --navigateToChanged.
Списки сторінок
Порядок сторінок
Бічне меню документації, браузер сторінок документації тощо впорядковуються за стандартним порядком сортування Hugo: за вагою (від 1), датою (спершу новіші) і, нарешті, за заголовком посилання.
Тож, якщо ви хочете перемістити сторінку або розділ вище, задайте вагу у front matter сторінки:
title:My Pageweight:10
Примітка:
Для ваги сторінок розумно використовувати не 1, 2, 3 ..., а інший інтервал, скажімо, 10, 20, 30... Це дасть змогу згодом вставляти сторінки там, де потрібно. Крім того, ваги в межах однієї теки (розділу) не мають збігатися з іншими вагами. Так вміст завжди буде впорядковано правильно, особливо в локалізованому вмісті.
Головне меню документації
Головне меню Документація формується з розділів у docs/, у front matter файлу вмісту розділу _index.md яких встановлено прапорець main_menu:
main_menu:true
Зверніть увагу, що заголовок посилання береться з linkTitle сторінки, тож якщо ви хочете, щоб він відрізнявся від заголовка, змініть його у файлі вмісту:
main_menu:truetitle:Page TitlelinkTitle:Title used in links
Примітка:
Це потрібно зробити для кожної мови. Якщо ви не бачите свого розділу в меню, імовірно, Hugo не визначає його як розділ. Створіть файл вмісту _index.md у теці розділу.
Бічне меню документації
Бічне меню документації формується з поточного дерева розділів, починаючи нижче docs/.
У ньому відображаються всі розділи та їхні сторінки.
Якщо ви не хочете показувати розділ або сторінку в списку, встановіть прапорець toc_hide у true у front matter:
toc_hide:true
Коли ви переходите до розділу, що має вміст, показується конкретний розділ або сторінка (наприклад, _index.md). Інакше показується перша сторінка в цьому розділі.
Браузер документації
Браузер сторінок на домашній сторінці документації формується з усіх розділів і сторінок, розміщених безпосередньо нижче docs section.
Якщо ви не хочете показувати розділ або сторінку в списку, встановіть прапорець toc_hide у true у front matter:
toc_hide:true
Головне меню
Посилання сайту в меню вгорі праворуч (а також у нижньому колонтитулі) формуються через пошук сторінок. Так забезпечується, що сторінка справді існує. Тож якщо розділу case-studies на сайті (для мови) немає, посилання на нього не буде.
Пакети сторінок
Крім окремих сторінок вмісту (файлів Markdown), Hugo підтримує пакети сторінок.
Один із прикладів — Власні shortcodes Hugo. Це leaf bundle. Усе, що міститься в цій теці, зокрема index.md, буде частиною пакета. Це також стосується посилань відносно сторінки, зображень, які можна обробляти, тощо:
Ще один поширений приклад — пакет includes. У його front matter встановлено headless: true, тобто він не отримує власного URL. Він використовується лише в інших сторінках.
Для перекладених пакетів відсутні файли, що не є вмістом, успадковуються з мов вище. Це дає змогу уникнути дублювання.
Усі файли в пакеті — це те, що Hugo називає Resources, і для кожної мови можна надати метадані, як-от параметри й заголовок, навіть якщо файл не підтримує front matter (файли YAML тощо). Див. Метадані ресурсів сторінок.
Значення, отримане з .RelPermalink ресурсу Resource, є відносним до сторінки. Див. Permalinks.
Стилі
Вихідний код SASS таблиць стилів цього сайту зберігається в assets/sass і автоматично збирається Hugo.
Ця панель побудована за допомогою Google Looker Studio та відображає інформацію, зібрану на kubernetes.io за допомогою Google Analytics 4 з серпня 2022 року.
Використання панелі
Стандартно панель показує всю зібрану аналітику за останні 30 днів. Щоб переглянути дані за інший період, скористайтеся вибором дат. Інші параметри фільтрації дають змогу переглядати дані за розташуванням користувачів, пристроєм, з якого відкривали сайт, перекладом документації тощо.
Якщо ви помітили проблему з цією панеллю або хочете запропонувати покращення, створіть тікет.
10 - Рекомендації з перекладу українською мовою
Дорогі друзі! Раді вітати вас у спільноті українських контриб'юторів проекту Kubernetes. Ця сторінка створена з метою полегшити вашу роботу при перекладі документації. Вона містить правила, якими ми керувалися під час перекладу, і базовий словник, який ми почали укладати. Перелічені у ньому терміни ви знайдете в українській версії документації Kubernetes. Будемо дуже вдячні, якщо ви допоможете нам доповнити цей словник і розширити правила перекладу.
Сподіваємось, наші рекомендації стануть вам у пригоді.
Загальний процес
Виберіть одне з найбільш витребуваних ішьюзів або будь-яке ішью і залиште в ньому коментар на кшталт "Працюю над цим". Ми надішлемо вам запрошення до організації та закріпимо цей ішьюз за вами.
Якщо ви виявили проблеми з перекладеним вмістом і не можете негайно їх виправити, створіть ішью у k/website з описом що не так, на якій сторінці (посилання) і додайте в опис ішью з нового рядка /language uk.
Скопіюйте оригінал і додайте його перед перекладом у якості коментаря. Це потрібно для спрощення відслідковування змін і процесу ревью. Приклади: для Markdown, для YAML.
У випадку, якщо у перекладі термін набуває неоднозначності і розуміння тексту ускладнюється, надайте у дужках англійський варіант, наприклад: кінцеві точки (endpoints). Якщо при перекладі термін втрачає своє значення, краще не перекладати його, наприклад: характеристики affinity.
Назви об'єктів Kubernetes залишаємо без перекладу і пишемо з великої літери: Service, Pod, Deployment, Volume, Namespace, за винятком терміна node (вузол). Назви об'єктів Kubernetes вважаємо за іменники ч.р. і відмінюємо за допомогою апострофа: Pod'ів, Deployment'ами.
Для слів, що закінчуються на приголосний, у родовому відмінку однини використовуємо закінчення -а: Pod'а, Deployment'а.
Слова, що закінчуються на голосний, не відмінюємо: доступ до Service, за допомогою Namespace. У множині використовуємо англійську форму: користуватися Services, спільні Volumes.
Частовживані і усталені за межами Kubernetes слова перекладаємо українською і пишемо з малої літери (label -> мітка). У випадку, якщо термін для означення об'єкта Kubernetes вживається у своєму загальному значенні поза контекстом Kubernetes (service як службова програма, deployment як розгортання), перекладаємо його і пишемо з малої літери, наприклад: service discovery -> виявлення сервісу, continuous deployment -> безперервне розгортання.
Складені слова вважаємо за власні назви і не перекладаємо (LabelSelector, kube-apiserver).
Для перевірки закінчень слів у родовому відмінку однини (-а/-я, -у/-ю) використовуйте онлайн словник. Якщо слова немає у словнику, визначте його відміну і далі відмінюйте за правилами. Докладніше дивіться тут.