Рецензування змін

• 1: Рецензування pull request
• 2: Рецензування для затверджувачів та рецензентів

1 - Рецензування pull request

Будь-хто може рецензувати pull request документації. Відвідайте розділ pull requests у репозиторії вебсайту Kubernetes, щоб побачити відкриті pull request.

Рецензування pull request документації — це чудовий спосіб познайомитися зі спільнотою Kubernetes. Це допомагає вам вивчити кодову базу та завоювати довіру інших учасників.

Перед рецензуванням доцільно:

• Ознайомитись з настановами з контенту та керівництвом зі стилю, щоб залишати обґрунтовані коментарі.
• Розуміти різні ролі та обовʼязки у спільноті документації Kubernetes.

Перш ніж почати

Перш ніж почати рецензування:

• Прочитайте Кодекс поведінки CNCF та дотримуйтеся його у будь-який час.
• Будьте ввічливими, уважними та корисними.
• Коментуйте позитивні аспекти PR, а також зміни.
• Будьте емпатичними та враховуйте, як ваш огляд може бути сприйнятий.
• Передбачайте добрі наміри та ставте уточнювальні питання.
• Досвідчені учасники можуть співпрацювати з новими учасниками, чиї роботи потребують значних змін.

Процес рецензування

Загалом, огляньте pull request на вміст та стиль англійською мовою. На схемі 1 показані етапи процесу огляду. Деталі для кожного кроку наведено нижче.

Схема 1. Етапи процесу огляду.

1. Перейдіть на https://github.com/kubernetes/website/pulls. Ви побачите список усіх відкритих pull request до вебсайту та документації Kubernetes.

2. Відфільтруйте відкриті PR, використовуючи одну або всі з наступних міток:

   • cncf-cla: yes (Рекомендовано): PR, подані учасниками, які не підписали CLA, не можуть бути об’єднані з осноною кодовою базою репо. Див. Підписання CLA для отримання додаткової інформації.
   • language/en (Рекомендовано): Фільтрує лише PR англійською мовою.
   • size/<розмір>: фільтрує PR певного розміру. Якщо ви новачок, почніть з менших PR.

   Крім того, переконайтеся, що PR не позначено як роботу в процесі. PR з міткою work in progress ще не готові до огляду.

3. Після того, як ви вибрали PR для огляду, зрозумійте зміни, зроблені в ньому, шляхом:

   • Читання опису PR, щоб зрозуміти зроблені зміни, і читання будь-яких пов’язаних питань
   • Читання коментарів інших рецензентів
   • Клацанням на вкладку Files changed, щоб побачити змінені файли та рядки
   • Попереднього перегляду змін у попередньому перегляді Netlify, прокручуючи до розділу перевірки збірки PR у нижній частині вкладки Conversation. Ось знімок екрана (який показує сайт GitHub на компʼютері; якщо ви переглядаєте на планшеті або смартфоні, вебінтерфейс GitHub дещо відрізняється):

     

     Щоб відкрити попередній перегляд, натисніть на посилання Details у рядку deploy/netlify у списку перевірок.

4. Перейдіть на вкладку Files changed, щоб почати свій огляд.

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

   2. Додайте ваші коментарі щодо рядка та натисніть або Add single comment (якщо у вас є лише один коментар), або Start a review (якщо у вас є кілька коментарів).

   3. Після завершення натисніть Review changes у верхній частині сторінки. Тут ви можете додати короткий зміст свого огляду (і залишити кілька позитивних коментарів для учасника!).Завжди використовуйте "Comment"

      • Уникайте натискання кнопки "Request changes" при завершенні огляду. Якщо ви хочете заблокувати PR від обʼєднання до внесення подальших змін, ви можете залишити коментар "/hold". Зазначте, чому ви встановлюєте hold, і за потреби уточніть умови, за яких hold можна зняти вами або іншими рецензентами.

      • Уникайте натискання кнопки "Approve" при завершенні огляду. Коментар "/approve" є рекомендованим в більшості випадків.

Контрольний список рецензування

Використовуйте наступні пункти як відправну точку при огляді.

Мова та граматика

• Чи є очевидні помилки в мові або граматиці? Чи є кращий спосіб сформулювати щось?
  • Зосередьтеся на мові та граматиці тих частин сторінки, які змінює автор. Якщо автор не має на меті оновити всю сторінку, він не зобовʼязаний виправляти всі помилки на сторінці.
  • Коли PR оновлює наявну сторінку, слід зосередитися на перегляді тих частин сторінки, які оновлюються. Цей змінений контент слід переглянути на предмет технічної та редакційної відповідності. Якщо ви виявите помилки на сторінці, які не стосуються безпосередньо того, що намагається виправити автор PR, це слід розглядати як окрему проблему (спершу перевірте, чи вже не існує тікет щодо цього).
  • Слідкуйте за pull request, які переміщують контент. Якщо автор перейменовує сторінку або обʼєднує дві сторінки, ми (Kubernetes SIG Docs) зазвичай не просимо до цього автора виправити всі граматичні або орфографічні недоліки в переміщеному контенті.
• Чи є складні або архаїчні слова, які можна замінити простішими?
• Чи є слова, терміни або фрази, які можна замінити на недискримінаційні альтернативи?
• Чи відповідає вибір слів та їхнє написання з великої літери настановам зі стилю?
• Чи є довгі речення, які можна зробити коротшими або менш складними?
• Чи є довгі абзаци, які краще б виглядали у вигляді списку або таблиці?

Вміст

• Чи існує схожий контент в іншому місці на сайті Kubernetes?
• Чи посилається контент надмірно на зовнішні сайти, окремих постачальників або документацію, що не є відкритим вихідним кодом?

Вебсайт

• Чи змінив цей PR заголовок сторінки, slug/alias або anchor link? Якщо так, чи є зламані посилання в результаті цього PR? Чи є інший варіант, наприклад, зміна заголовка сторінки без зміни slug?

• Чи додає PR нову сторінку? Якщо так:

  • Чи використовує сторінка правильний тип контенту сторінки та відповідні Hugo shortcodes?
  • Чи правильно сторінка відображається у боковій навігації (або взагалі)?
  • Чи повинна сторінка з’явитися у списку Docs Home?

• Чи відображаються зміни у попередньому перегляді Netlify? Будьте особливо уважними до списків, блоків коду, таблиць, приміток та зображень.

Блог

• Ранні відгуки щодо дописів блогу вітаються у вигляді Google Doc або HackMD. Будь ласка, запитуйте відгуки заздалегідь у Slack-каналі #sig-docs-blog.

• Перед переглядом PR для блогу ознайомтесь з розділом Надсилання блог-постів і прикладів використання.

• Ми готові розміщувати дзеркальну версію будь-якої статті, опублікованої на https://kubernetes.dev/blog/ (блог спільноти) за умови, що:

  • дзеркальна стаття має ту ж дату публікації, що й оригінал (час публікації також повинен збігатися, але в особливих випадках можна вказати час із затримкою до 12 годин)
  • PR для статей, у яких оригінальна стаття була змерджена на https://kubernetes.dev/, повинні дотримуватись правил:
    • між публікацією оригіналу та дзеркальної статті не було (і не буде) інших публікацій в основному блозі. Це робиться для того, щоб не додавати статті до стрічок, таких як RSS, окрім як у самому кінці.
  • оригінальна стаття не порушує жодних суворо рекомендованих керівних принципів чи норм спільноти.
  • Необхідно вказати канонічний URL для дзеркальної статті, на URL оригінальної статті (можна використовувати попередній перегляд для визначення URL і заповнити його заздалегідь перед публікацією). Використовуйте поле canonicalUrl у front matter для цього.

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

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

• Ми позначаємо статті блогу як підтримувані (evergreen: true у front matter), тільки якщо проєкт Kubernetes готовий зобовʼязатися підтримувати їх необмежений час. Деякі статті блогу безумовно заслуговують на це, і ми завжди позначаємо наші анонси релізів як "evergreen". Порадьтеся з іншими учасниками, якщо ви не впевнені, як перевірити цей аспект.

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

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

  • допустимо використовувати “ми“ в статті блогу, якщо є кілька авторів або вступ чітко вказує, що автор пише від імені певної групи.
  • ми уникаємо використання шорткодів Kubernetes для привернення уваги (наприклад, {{< caution >}})
  • висловлювання про майбутнє допустимі, хоча ми використовуємо їх обережно в офіційних анонсах від імені Kubernetes
  • приклади коду не повинні використовувати шорткод {{< code_sample >}}, і часто краще, щоб вони його не використовували
  • ми дозволяємо авторам писати статті в їхньому власному стилі, за умови, що більшість читачів зрозуміють основну думку

• Посібник зі створення діаграм орієнтований на документацію Kubernetes, а не на статті блогу. Однак:

  • ми надаємо перевагу SVG над растровими форматами діаграм і над Mermaid (джерело Mermaid можна включити у коментар)
  • нема потреби додавати підписи до діаграм як "Рисунок 1", "Рисунок 2" тощо

Інше

• Слідкуйте за несуттєвими правками; якщо ви бачите зміну, яку вважаєте несуттєвою правкою, будь ласка, вкажіть цю політику (все ще можна прийняти зміну, якщо вона дійсно є покращенням).
• Заохочуйте авторів, які роблять виправлення пробілів, робити це в першому коміті свого PR, а потім додавати інші зміни поверх цього. Це полегшує як злиття, так і огляд. Особливо звертайте увагу на несуттєві зміни, які відбуваються в одному коміті разом з великою кількістю виправлень пробілів (і якщо ви це бачите, заохочуйте автора виправити це).

Якщо ви виявляєте невеликі проблеми з PR, які не є суттєвими для змісту, наприклад, друкарські помилки або неправильне використання пробілів, додайте на початку своїх коментарів nit:. Це дає автору зрозуміти, що ця частина вашого зворотного зв’язку не є критичною.

Якщо ви розглядаєте pull request для схвалення, і весь відгук позначений як nit, ви можете обʼєднати PR в будь-якому випадку. У такому випадку часто корисно створити тікет щодо залишених незначних зауважень. Розгляньте, чи можете ви виконати вимоги для позначення цієї нової проблеми як Good First Issue; якщо ви можете, це буде хорошим початком для новачків.

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

Рецензенти та затверджувачі 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 для інших осіб. Втручайтеся, щоб уникнути цього ризику для інших учасників.

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

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