Участь у SIG Docs

• 1: Ролі та обовʼязки
• 2: Відповідальні за PR
• 3: Відповідальні за тікети

1 - Ролі та обовʼязки

Будь-хто може зробити внесок у Kubernetes. Зі зростанням ваших внесків до SIG Docs, ви можете подати заявку на різні рівні членства в спільноті. Ці ролі дозволяють брати на себе більше відповідальності в спільноті. Кожна роль вимагає більше часу та відданості. Ролі є такими:

• Будь-хто: регулярні учасники документації Kubernetes
• Члени: можуть призначати та розподіляти тікети, а також надавати відгук на pull requestʼи, який не є обовʼязковим до виконання
• Рецензенти: можуть керувати рецензією документаційних pull request'ів і гарантувати якість змін
• Затверджувачі: можуть керувати рецензією документації та зливати зміни

Будь-хто

Будь-хто з обліковим записом GitHub може зробити свій внесок у Kubernetes. SIG Docs вітає всіх нових учасників!

Будь-хто може:

• Створити тікет в будь-якому репозиторії Kubernetes, включаючи kubernetes/website
• Надати відгук на pull request, який не є обовʼязковим для виконання
• Зробити внесок у локалізацію
• Запропонувати покращення у Slack або в списку розсилки SIG docs.

Після підписання CLA, будь-хто також може:

• Створити pull request для покращення наявного контенту, додавання нового контенту або написання блогу чи прикладу використання
• Створювати діаграми, графічні ресурси та вбудовані відеозаписи та відео

Для отримання додаткової інформації дивіться додавання нового контенту.

Члени

Член — це хтось, хто подав кілька pull request'ів до kubernetes/website. Члени є частиною організації Kubernetes на GitHub.

Члени можуть:

• Робити все, що зазначено в розділі Будь-хто

• Використовувати коментар /lgtm, щоб додати мітку LGTM (виглядає добре для мене) до pull request'у

  Примітка:

  Використання /lgtm запускає автоматизацію. Якщо ви хочете надати не обовʼязкове схвалення, коментар "LGTM" також працює!

• Використовувати коментар /hold, щоб заблокувати злиття для pull request'у

• Використовувати коментар /assign, щоб призначити рецензента для pull requestʼу

• Робити рецензування pull request'ів, які не є обовʼязковими

• Використовувати автоматизацію для розподілу та категоризації тікетів

• Документувати нові функції

Набуття членства

Після подання щонайменше 5 значних pull request'ів та виконання інших вимог:

1. Знайдіть двох рецензентів або затверджувачів, які стануть вашими поручителями.

   Попросіть поручительства в каналі #sig-docs на Slack або в списку розсилки SIG Docs.

   Примітка:

   Не надсилайте прямий електронний лист або пряме повідомлення у Slack окремому члену SIG Docs. Ви повинні запитати про поручительство перед поданням вашої заявки на членство.

2. Відкрийте тікет на GitHub у репозиторії kubernetes/org. Використовуйте шаблон тікета Organization Membership Request.

3. Повідомте своїх поручителів про тікет на GitHub. Ви можете:

   • Згадати їх через GitHub-імʼя у тікеті (@<GitHub-username>)

   • Надіслати їм посилання на тікет за допомогою Slack або електронної пошти.

     Поручителі схвалюють ваш запит позначкою +1. Після схвалення запиту вашими поручителями, адміністратор GitHub Kubernetes додає вас як члена. Вітаємо!

     Якщо ваш запит на членство не приймається, ви отримаєте відгук. Після врахування відгуків подайте заявку знову.

4. Прийміть запрошення до організації 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.

Щоб подати заявку:

1. Відкрийте pull request, що додає ваше імʼя користувача GitHub до розділу файлу OWNERS_ALIASES в репозиторії kubernetes/website.

   Примітка:

   Якщо ви не впевнені, де себе додати, додайте себе до sig-docs-en-reviews.

2. Призначте PR одному або кільком затверджувачам SIG Docs (імена користувачів вказані в sig-docs-{language}-owners).

Якщо заявку схвалено, лідер SIG Docs додає вас до відповідної команди GitHub. Після додавання K8s-ci-robot призначає та пропонує вас як рецензента на нові pull requestʼи.

Затверджувачі

Затверджувачі оглядають і затверджують pull requestʼи для злиття. Затверджувачі є членами команд GitHub @kubernetes/sig-docs-{language}-owners.

Затверджувачі можуть робити наступне:

• Все, що зазначено в розділах Будь-хто, Члени та Рецензенти
• Публікувати контент учасників, затверджуючи та зливаючи 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.

Щоб подати заявку:

1. Відкрийте pull request, що додає вас до розділу файлу OWNERS_ALIASES у репозиторії kubernetes/website.

   Примітка:

   Якщо ви не впевнені, де себе додати, додайте себе до `sig-docs-en-owners`.
   

2. Призначте PR одному або кільком поточним затверджувачам SIG Docs.

Якщо заявку схвалено, лідер SIG Docs додає вас до відповідної команди GitHub. Після додавання, @k8s-ci-robot призначає та пропонує вас як рецензента на нові pull request'и.

Що далі

• Прочитайте про PR чергування, роль, яку всі затверджувачі виконують по черзі.

2 - Відповідальні за PR

SIG Docs затверджувачі беруть участь у тижневих чергуваннях стосовно управління pull request'ами для репозиторію.

Цей розділ охоплює обовʼязки відповідальних за PR. Для отримання додаткової інформації щодо якісного рецензування, дивіться Рецензування змін.

Обовʼязки

Кожного дня під час тижневого чергування відповідальний за PR:

• Робить огляд відкритих pull request'ів на відповідність стилю та змісту.
  • Почніть з найменших PRʼів (size/XS), і закінчіть найбільшими (size/XXL). Огляньте стільки PRʼів, скільки зможете.
• Переконайтеся, що учасники PR підписали CLA.
  • Використовуйте цей скрипт, щоб нагадати учасникам, які не підписали CLA, зробити це.
• Надання відгуків про зміни та запит технічних оглядів від членів інших SIG.
  • Надання своїх пропозицій щодо запропонованих змін у PR.
  • Якщо вам потрібно перевірити зміст, залиште коментар у PR і запросіть більше деталей.
  • Призначте відповідну мітку(и) sig/.
  • Якщо необхідно, призначте рецензентів з блоку reviewers: у метаданих файлу.
  • Ви також можете позначити SIG для огляду, коментуючи @kubernetes/<sig>-pr-reviews у PR.
• Використовуйте коментар /approve для затвердження PR для злиття. Зливайте PR, коли він готовий.
  • PRʼи повинні мати коментар /lgtm від іншого члена перед злиттям.
  • Розгляньте можливість прийняття технічно правильного змісту, який не відповідає настановам зі стилю. Під час затвердження змін відкрийте новий тікет для розвʼязання питання стилю. Зазвичай такі питання стилю можна описати як гарні перші завдання.
  • Використання виправлень стилю як гарних перших завдань — це хороший спосіб забезпечити наявність легших завдань для допомоги в адаптації нових учасників.
• Також перевіряйте pull requestʼи до коду генератора довідкової документації та оглядайте їх (або залучайте допомогу).
• Підтримуйте відповідального за тікети у розгляді та теґуванні нових тікетів щодня. Дивіться Розгляд та категоризація тікетів для керівництва з використання метаданих SIG Docs.

Корисні запити GitHub для відповідальних

Наступні запити корисні під час роботи з PRʼами. Після обробки цих запитів зазвичай залишається невеликий список PRʼів для огляду. Ці запити виключають PRʼи локалізації. Усі запити стосуються основної гілки, крім останнього.

• Без CLA, не допускається до злиття: Нагадуйте учаснику підписати CLA. Якщо і бот, і людина нагадали їм, закрийте PR і нагадайте їм, що вони можуть відкрити його після підписання CLA. Не оглядайте PRʼи, автори яких не підписали CLA!
• Потребує LGTM: Перелік PRʼів, які потребують LGTM від члена. Якщо PR потребує технічного огляду, залучайте одного з рецензентів, запропонованих ботом. Якщо зміст потребує доопрацювання, додайте пропозиції та відгуки безпосередньо.
• Має LGTM, потребує затвердження документації: Перелік PRʼів, які потребують коментаря /approve для злиття.
• Швидкі виграші: Перелік 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.

Програма тіньового відповідального за PR

У кінці 2021 року SIG Docs представив PR Wrangler Shadow Program. Програма була введена для допомоги новим учасникам зрозуміти процес управління PR.

Як стати тіньовим відповідальним за PR

• Якщо ви зацікавлені у тому, щоби стати тіньовим відповідальним за PR, будь ласка, відвідайте сторінку Wiki PR Wrangler'ів, щоб побачити графік управління PR на цей рік та зареєструватися.

• Інші можуть звернутися до Slack-каналу #sig-docs для запиту на участь у підтримці відповідальних за PR на конкретний тиждень. Не соромтеся звертатися до Бреда Топола (@bradtopol) або одного зі співголів/лідерів SIG Docs.

• Після реєстрації на підтримку відповідального за PR, представте себе відповідальному за PR у Kubernetes Slack.

3 - Відповідальні за тікети

На додаток до PR чергування, офіційні затверджувачі, рецензенти та члени SIG Docs беруть участь у тижневих чергуваннях у розгляді та категоризації тікетів в репозиторії.

Обовʼязки

Кожного дня під час тижневого чергування Відповідальний за тікети буде відповідати за:

• Щоденний розгляд та тегування нових тікетів. Дивіться Розглядв та категоризація тікетів для керівництва з використання метаданих SIG Docs.
• Слідкування за застарілими та "протухлими" тікетами в репозиторії kubernetes/website.
• Підтримку дошки тікетів.

Вимоги

• Повинен бути активним членом організації 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 на питання.