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

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

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

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

Огляд PR

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

Все, що описано в Огляд pull request'ів, застосовується, але рецензенти та затверджувачі повинні також робити наступне:

• Використовуйте команду Prow /assign, щоб за потреби призначити конкретного рецензента для PR. Це особливо важливо, коли мова йде про запит технічного огляду від тих хто робить внесок в покращення коду.

  Примітка:

  Подивіться поле reviewers у верхній частині Markdown файлу, щоб побачити, хто може надати технічний огляд.

• Переконайтеся, що PR дотримується настанов з контенту та стилью; надайте автору посилання на відповідну частину керівництва, якщо ні.

• Використовуйте опцію Request Changes в GitHub, коли це доречно, щоб запропонувати зміни автору PR.

• Змінюйте свій статус огляду в GitHub за допомогою команд Prow /approve або /lgtm, якщо ваші пропозиції були впроваджені.

Комміти в PR іншої особи

Залишати коментарі до PR корисно, але можуть бути випадки, коли вам потрібно внести зміни в PR іншої особи.

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

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

Ви не можете робити коміти в PR іншої особи, якщо виконується будь-яка з наступних умов:

• Якщо автор PR напряму надіслав (push) свою гілку до https://github.com/kubernetes/website/ репозиторію. Тільки рецензент з доступом на push може робити коміти в PR іншого користувача.

  Примітка:

  Заохочуйте авторів надсилати свою гілку у свій форк перед відкриттям PR наступного разу.

• Автор PR явно забороняє редагування з боку затверджувачів.

Команди Prow для рецензування

Prow є CI/CD системою на базі Kubernetes, яка запускає завдання для pull requestʼів (PR). Prow дозволяє використовувати команди в стилі чат-ботів для обробки дій GitHub у межах організації Kubernetes, таких як додавання та видалення міток, закриття тікетів та призначення затверджувача. Використовуйте команди Prow у вигляді коментарів GitHub у форматі /<command-name>.

Найбільш поширені команди Prow, які використовують рецензенти та затверджувачі:

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

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

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

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

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

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 Blog будуть ставати застарілими з часом. Тому ми підтримуємо дописи блогу лише до одного року. Якщо питання стосується допису, якому понад рік, закрийте тікет без виправлення.

Запити на підтримку або звіти про помилки в коді

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

Обʼєднання комітів

Як затверджувач (approver), коли ви переглядаєте pull requests (PRs), є кілька випадків, коли ви можете зробити наступне:

• Порадити автору обʼєднати коміти.
• Обʼєднати коміти для автора.
• Порадити автору не обʼєднувати коміти ще.
• Запобігти обʼєднанню.

Порада авторам обʼєднати коміти: Нові учасники можуть не знати, що потрібно обʼєднати коміти в своїх pull requests (PRs). Якщо це так, порадьте їм це зробити, надайте посилання на корисну інформацію і запропонуйте допомогу, якщо вона необхідна. Корисні посилання:

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

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

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

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

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

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

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