Рецензенти та затверджувачі SIG Docs виконують кілька додаткових дій під час огляду змін.
Щотижня конкретний затверджувач документації добровільно погоджується переглядати та рецензувати pull request'и (PR). Ця особа є "PR Wrangler" на тиждень. Детальнішу інформацію можна знайти в розкладі PR Wrangler. Щоб стати PR Wrangler, відвідайте щотижневу зустріч SIG Docs і станьте волонтером. Навіть якщо ви не внесені до розкладу на поточний тиждень, ви все одно можете переглядати pull request'и, які не знаходяться в активному перегляді.
Окрім ротації, бот призначає рецензентів і затверджувачів для 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 напряму надіслав (push) свою гілку до https://github.com/kubernetes/website/ репозиторію. Тільки рецензент з доступом на push може робити коміти в PR іншого користувача.
Автор PR явно забороняє редагування з боку затверджувачів.
Prow є CI/CD системою на базі Kubernetes, яка запускає завдання для pull requestʼів (PR). Prow дозволяє використовувати команди в стилі чат-ботів для обробки дій GitHub у межах організації Kubernetes, таких як додавання та видалення міток, закриття тікетів та призначення затверджувача. Використовуйте команди Prow у вигляді коментарів GitHub у форматі /<command-name>.
Найбільш поширені команди Prow, які використовують рецензенти та затверджувачі:
| Команда Prow | Обмеження ролей | Опис |
|---|---|---|
/lgtm |
Члени організації | Сигналізує, що ви завершили огляд PR і задоволені змінами. |
/approve |
Затверджувачі | Затверджує PR для злиття. |
/assign |
Будь-хто | Призначає людину для огляду або затвердження PR |
/close |
Члени організації | Закриває проблему або PR. |
/hold |
Будь-хто | Додає мітку do-not-merge/hold, що означає, що PR не може бути автоматично злитий. |
/hold cancel |
Будь-хто | Видаляє мітку do-not-merge/hold. |
Щоб переглянути команди, які ви можете використовувати в PR, дивіться довідку по командах Prow.
Загалом, SIG Docs дотримується процесу класифікації проблем Kubernetes і використовує ті ж самі мітки.
Цей фільтр GitHub Issue знаходить тікети, які можуть потребувати класифікації.
Перевірте тікет
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)У обох випадках мітка повинна вже існувати. Якщо ви спробуєте додати мітку, якої не існує, команда буде проігнорована без будь-яких сповіщень проце.
Список усіх міток можна знайти у розділі міток репозиторію сайту. Не всі мітки використовуються SIG Docs.
Тікети зазвичай відкриваються і закриваються швидко. Однак іноді тікети залишаються неактивними після їх відкриття. Іноді тікет може залишатися відкритим більше ніж 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.
Як затверджувач (approver), коли ви переглядаєте pull requests (PRs), є кілька випадків, коли ви можете зробити наступне:
Порада авторам обʼєднати коміти: Нові учасники можуть не знати, що потрібно обʼєднати коміти в своїх pull requests (PRs). Якщо це так, порадьте їм це зробити, надайте посилання на корисну інформацію і запропонуйте допомогу, якщо вона необхідна. Корисні посилання:
Обʼєднання комітів для учасників: Якщо автору може бути важко обʼєднати коміти або існує тиск часу для злиття PR, ви можете виконати обʼєднання за них:
Порада авторам не обʼєднувати коміти
Ніколи не обʼєднуйте