Рецензування для затверджувачів та рецензентів

Рецензенти та затверджувачі SIG Docs під час рецензування змін виконують кілька додаткових дій.

Щотижня певний затверджувач документації добровільно береться розглядати (triage) й рецензувати pull request. Ця особа є "PR Wrangler" (відповідальним за PR) на тиждень. Докладніше див. графік PR Wrangler. Щоб стати PR Wrangler, відвідайте щотижневу зустріч SIG Docs і зголосіться. Навіть якщо вас немає в графіку на поточний тиждень, ви все одно можете рецензувати pull request (PR), які ще ніхто активно не рецензує.

Окрім чергування, бот призначає рецензентів і затверджувачів для PR на основі власників змінених файлів.

Рецензування PR

Документація Kubernetes дотримується процесу рецензування коду Kubernetes.

Усе, що описано в Рецензування 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, які використовують рецензенти та затверджувачі:

Щоб переглянути команди, які можна використовувати в PR, див. довідник команд Prow.

Класифікація та категоризація проблем

Загалом SIG Docs дотримується процесу класифікації тікетів Kubernetes і використовує ті самі мітки.

Цей фільтр тікетів GitHub знаходить тікети, які можуть потребувати класифікації.

Класифікація тікета

1. Перевірте тікет

   • Переконайтеся, що тікет стосується документації вебсайту. Деякі тікети можна швидко закрити, відповівши на запитання або вказавши автору на ресурс. Докладніше див. розділ Запити на підтримку або звіти про помилки в коді.
   • Оцініть, чи має тікет сенс.
   • Додайте мітку triage/needs-information, якщо в тікеті недостатньо подробиць, щоб із ним можна було працювати, або шаблон заповнено неналежно.
   • Закрийте тікет, якщо він має мітки lifecycle/stale та triage/needs-information.

2. Додайте мітку пріоритету (докладні визначення міток пріоритету наведено в 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)

В обох випадках мітка має вже існувати. Якщо ви спробуєте додати мітку, якої не існує, команду буде мовчки проігноровано.

Список усіх міток можна знайти у розділі міток репозиторію сайту. Не всі мітки використовуються SIG Docs.

Мітки життєвого циклу тікета

Тікети зазвичай відкривають і закривають швидко. Однак іноді тікет після відкриття стає неактивним. А іноді тікет має залишатися відкритим довше ніж 90 днів.

Обробка особливих типів тікетів

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) слід обʼєднувати. Якщо це так, порадьте їм це зробити, дайте посилання на корисну інформацію і запропонуйте організувати допомогу, якщо вона потрібна. Корисні посилання:

• Відкриття pull request та обʼєднання комітів для учасників документації.
• GitHub Workflow, включаючи діаграми, для розробників.

Обʼєднання комітів за учасників: якщо учаснику може бути складно обʼєднати коміти або PR потрібно злити терміново, ви можете виконати обʼєднання за нього:

• Репозиторій kubernetes/website налаштовано так, щоб дозволяти обʼєднання комітів під час злиття pull request. Просто натисніть кнопку Squash commits.
• Якщо автор PR дозволяє супровідникам керувати PR, ви можете обʼєднати його коміти й оновити його форк результатом. Перш ніж обʼєднувати, порадьте йому зберегти й надіслати (push) свої останні зміни до PR. Після обʼєднання порадьте йому підтягнути (pull) обʼєднаний коміт у свій локальний клон.
• Ви можете змусити GitHub обʼєднати коміти за допомогою мітки, щоб обʼєднання виконали Tide / GitHub, або натиснувши кнопку Squash commits під час злиття PR.

Порада авторам не обʼєднувати коміти

• Якщо один коміт робить щось зламане чи нерозумне, а останній коміт скасовує цю помилку, не обʼєднуйте коміти. Хоча вкладка "Files changed" у PR на GitHub і попередній перегляд Netlify виглядатимуть нормально, злиття такого PR може спричинити конфлікти rebase або merge в інших людей. Втручайтеся на власний розсуд, щоб уберегти інших учасників від цього ризику.

Ніколи не обʼєднуйте

• Якщо ви запускаєте локалізацію або випускаєте документацію для нової версії, ви зливаєте гілку, яка не походить із форку користувача, — ніколи не обʼєднуйте коміти. Відмова від обʼєднання тут обовʼязкова, бо потрібно зберегти історію комітів для цих файлів.