SIG Docs є однією з робочих груп в проєкті Kubernetes, яка зосереджена на написанні, оновленні та підтримці документації для Kubernetes в цілому. Дивіться SIG Docs в репозиторії спільноти GitHub для отримання додаткової інформації про SIG.
SIG Docs вітає контент та рецензування від усіх учасників. Будь-хто може відкрити pull request (PR), і будь-хто може подавати питання щодо контенту або коментувати pull request'и, що знаходяться в процесі.
Ви також можете стати членом, рецензентом або затверджувачем. Ці ролі вимагають більшого доступу і несуть певні обов’язки щодо затвердження та прийняття змін. Дивіться community-membership для отримання додаткової інформації про те, як працює членство в спільноті Kubernetes.
Решта цього документа описує деякі унікальні способи функціонування цих ролей у 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 Wrangler або голова SIG Docs.
Що далі
Для отримання додаткової інформації про внесок до документації Kubernetes дивіться:
Будь-хто може зробити внесок у Kubernetes. Зі зростанням ваших внесків до SIG Docs, ви можете подати заявку на різні рівні членства в спільноті. Ці ролі дозволяють брати на себе більше відповідальності в спільноті. Кожна роль вимагає більше часу та відданості. Ролі є такими:
Будь-хто: регулярні учасники документації Kubernetes
Члени: можуть призначати та розподіляти тікети, а також надавати відгук на pull requestʼи, який не є обовʼязковим до виконання
Рецензенти: можуть керувати рецензією документаційних pull request'ів і гарантувати якість змін
Затверджувачі: можуть керувати рецензією документації та зливати зміни
Будь-хто
Будь-хто з обліковим записом GitHub може зробити свій внесок у Kubernetes. SIG Docs вітає всіх нових учасників!
Не надсилайте прямий електронний лист або пряме повідомлення у Slack окремому члену SIG Docs. Ви повинні запитати про поручительство перед поданням вашої заявки на членство.
Відкрийте тікет на GitHub у репозиторії kubernetes/org. Використовуйте шаблон тікета Organization Membership Request.
Повідомте своїх поручителів про тікет на GitHub. Ви можете:
Згадати їх через GitHub-імʼя у тікеті (@<GitHub-username>)
Надіслати їм посилання на тікет за допомогою Slack або електронної пошти.
Поручителі схвалюють ваш запит позначкою +1. Після схвалення запиту вашими поручителями, адміністратор GitHub Kubernetes додає вас як члена. Вітаємо!
Якщо ваш запит на членство не приймається, ви отримаєте відгук. Після врахування відгуків подайте заявку знову.
Прийміть запрошення до організації Kubernetes на GitHub у своєму обліковому записі електронної пошти.
Примітка:
GitHub надсилає запрошення на основну електронну адресу у вашому обліковому записі.
Рецензенти
Рецензенти відповідають за рецензування відкритих pull request'ів. На відміну від відгуків членів, автор PR повинен враховувати відгуки рецензентів. Рецензенти є членами команди GitHub @kubernetes/sig-docs-{language}-reviews.
Рецензенти можуть:
Робити все, що зазначено в розділах Будь-хто та Члени
Оглядати pull requestʼи та надавати обовʼязковий відгук
Примітка:
Щоб надати не обовʼязковий відгук, додайте до ваших коментарів фразу типу "Optionally: ".
Редагувати рядки, що стосуються користувачів, у коді
Покращувати коментарі до коду
Ви можете бути рецензентом SIG Docs або рецензентом для документів у певній предметній області.
Призначення рецензентів до pull requestʼів
Автоматизація призначає рецензентів до всіх pull requestʼів. Ви можете запросити огляд від конкретної особи, додавши коментар: /assign [@_github_handle].
Якщо призначений рецензент не прокоментував PR, інший рецензент може втрутитися. Ви також можете призначати технічних рецензентів за потреби.
Використання /lgtm
LGTM означає "Виглядає добре для мене" і вказує, що pull request є технічно точним і готовим до злиття. Усі PR потребують коментаря /lgtm від рецензента та коментаря /approve від затверджувача для злиття.
Коментар /lgtm від рецензента є обовʼязковим і запускає автоматизацію, яка додає мітку lgtm.
Як стати рецензентом
Коли ви відповідаєте вимогам, ви можете стати рецензентом SIG Docs. Рецензенти в інших SIG повинні подавати окрему заявку на статус рецензента в SIG Docs.
Щоб подати заявку:
Відкрийте pull request, що додає ваше імʼя користувача GitHub до розділу файлу OWNERS_ALIASES в репозиторії kubernetes/website.
Примітка:
Якщо ви не впевнені, де себе додати, додайте себе до sig-docs-en-reviews.
Призначте PR одному або кільком затверджувачам SIG Docs (імена користувачів вказані в sig-docs-{language}-owners).
Якщо заявку схвалено, лідер SIG Docs додає вас до відповідної команди GitHub. Після додавання K8s-ci-robot призначає та пропонує вас як рецензента на нові pull requestʼи.
Публікувати контент учасників, затверджуючи та зливаючи pull requestʼи за допомогою коментаря /approve
Пропонувати покращення до посібника зі стилю
Пропонувати покращення до тестів документації
Пропонувати покращення до вебсайту Kubernetes або інших інструментів
Якщо PR вже має /lgtm, або якщо затверджувач також додає коментар /lgtm, PR автоматично зливається. Затверджувач SIG Docs повинен залишити коментар /lgtm лише на змінах, які не потребують додаткового технічного огляду.
Затвердження pull requestʼів
Затверджувачі та лідери SIG Docs є єдиними, хто може зливати pull requestʼи в репозиторій вебсайту. Це супроводжується певними обовʼязками.
Затверджувачі можуть використовувати команду /approve, яка зливає PR в репозиторій.
Попередження:
Недбале злиття може зламати сайт, тому переконайтеся, що, коли ви щось зливаєте, ви впевнені в цьому.
Якщо у вас є питання, або ви не впевнені в чомусь, не соромтеся запросити додатковий огляд.
Переконайтеся, що тести Netlify пройшли перед тим, як ви використаєте команду /approve для PR.
Відвідайте попередній перегляд сторінки Netlify для PR, щоб переконатися, що все виглядає добре перед затвердженням.
Беріть участь у графіку чергування PR Wrangler для щотижневих ротацій. SIG Docs очікує, що всі затверджувачі братимуть участь у цій ротації. Дивіться PR чергування для отримання додаткової інформації.
Як стати затверджувачем
Коли ви відповідаєте вимогам, ви можете стати затверджувачем SIG Docs. Затверджувачі в інших SIG повинні подавати окрему заявку на статус затверджувача в SIG Docs.
Щоб подати заявку:
Відкрийте pull request, що додає вас до розділу файлу OWNERS_ALIASES у репозиторії kubernetes/website.
Примітка:
Якщо ви не впевнені, де себе додати, додайте себе до `sig-docs-en-owners`.
Призначте PR одному або кільком поточним затверджувачам SIG Docs.
Якщо заявку схвалено, лідер SIG Docs додає вас до відповідної команди GitHub. Після додавання, @k8s-ci-robot призначає та пропонує вас як рецензента на нові pull request'и.
Що далі
Прочитайте про PR чергування, роль, яку всі затверджувачі виконують по черзі.
Використовуйте цей скрипт, щоб нагадати учасникам, які не підписали CLA, зробити це.
Надання відгуків про зміни та запит технічних оглядів від членів інших SIG.
Надання своїх пропозицій щодо запропонованих змін у PR.
Якщо вам потрібно перевірити зміст, залиште коментар у PR і запросіть більше деталей.
Призначте відповідну мітку(и) sig/.
Якщо необхідно, призначте рецензентів з блоку reviewers: у метаданих файлу.
Ви також можете позначити SIG для огляду, коментуючи @kubernetes/<sig>-pr-reviews у PR.
Використовуйте коментар /approve для затвердження PR для злиття. Зливайте PR, коли він готовий.
PRʼи повинні мати коментар /lgtm від іншого члена перед злиттям.
Розгляньте можливість прийняття технічно правильного змісту, який не відповідає настановам зі стилю. Під час затвердження змін відкрийте новий тікет для розвʼязання питання стилю. Зазвичай такі питання стилю можна описати як гарні перші завдання.
Використання виправлень стилю як гарних перших завдань — це хороший спосіб забезпечити наявність легших завдань для допомоги в адаптації нових учасників.
Обовʼязки відповідального за PR не застосовуються до PRʼів локалізації (неангломовних PRʼів). Команди локалізації мають свої власні процеси та команди для огляду своїх PRʼів. Однак часто корисно переконатися, що PRʼи локалізації правильно позначені, переглянути невеликі PRʼи, що не залежать від мови (наприклад, оновлення посилань), або позначити рецензентів чи учасників у довготривалих PRʼах (тих, що відкриті понад 6 місяців і не оновлювалися більше як місяць).
Корисні запити GitHub для відповідальних
Наступні запити корисні під час роботи з PRʼами. Після обробки цих запитів зазвичай залишається невеликий список PRʼів для огляду. Ці запити виключають PRʼи локалізації. Усі запити стосуються основної гілки, крім останнього.
Без CLA, не допускається до злиття: Нагадуйте учаснику підписати CLA. Якщо і бот, і людина нагадали їм, закрийте PR і нагадайте їм, що вони можуть відкрити його після підписання CLA. Не оглядайте PRʼи, автори яких не підписали CLA!
Потребує LGTM: Перелік PRʼів, які потребують LGTM від члена. Якщо PR потребує технічного огляду, залучайте одного з рецензентів, запропонованих ботом. Якщо зміст потребує доопрацювання, додайте пропозиції та відгуки безпосередньо.
Швидкі виграші: Перелік PRʼів до основної гілки без явних блокувань. (змініть "XS" у розмірі мітки, коли будете працювати з PRʼами [XS, S, M, L, XL, XXL]).
Не для основної гілки: Якщо PR для гілки dev-, це для майбутнього випуску. Призначте менеджера випуску документації використовуючи: /assign @<github-ім'я_менеджера>. Якщо 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 позначає тікети як застарілі через 90 днів неактивності. Через 30 днів він позначає питання як "протухлі" та закриває їх. Відповідальні за PR повинні закривати їх через 14-30 днів неактивності.
Програма тіньового відповідального за PR
У кінці 2021 року SIG Docs представив PR Wrangler Shadow Program. Програма була введена для допомоги новим учасникам зрозуміти процес управління PR.
Як стати тіньовим відповідальним за PR
Якщо ви зацікавлені у тому, щоби стати тіньовим відповідальним за PR, будь ласка, відвідайте сторінку Wiki PR Wrangler'ів, щоб побачити графік управління PR на цей рік та зареєструватися.
Повинен бути активним членом організації Kubernetes.
Мінімум 15 значущих внесків у Kubernetes (з яких певна кількість має бути спрямована на kubernetes/website).
Виконання ролі неофіційно вже деякий час.
Корисні команди Prow для відповідальних за тікети
Нижче наведені деякі команди, що часто використовуються Відповідальними за тікетами:
# відкрити тікет знов/reopen
# перенести тікет, що не підходять для k/website до іншого репозиторію/transfer[-issue]# змінити стан "протухлих" тікетів/remove-lifecycle rotten
# змінити стан застарілих тікетів/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 на питання.
