Будь-хто може рецензувати pull request документації. Відвідайте розділ pull requests у репозиторії вебсайту Kubernetes, щоб побачити відкриті pull request.
Рецензування pull request документації — це чудовий спосіб познайомитися зі спільнотою Kubernetes. Це допомагає вам вивчити кодову базу та завоювати довіру інших учасників.
Будьте емпатичними та враховуйте, як ваш огляд може бути сприйнятий.
Передбачайте добрі наміри та ставте уточнювальні питання.
Досвідчені учасники можуть співпрацювати з новими учасниками, чиї роботи потребують значних змін.
Процес рецензування
Загалом, огляньте pull request на вміст та стиль англійською мовою. На схемі 1 показані етапи процесу огляду. Деталі для кожного кроку наведено нижче.
flowchart LR
subgraph fourth[Початок огляду]
direction TB
S[ ] -.-
M[додавання коментарів] --> N[огляд змін]
N --> O[нові учасники повинні вибрати Comment]
end
subgraph third[Вибір PR]
direction TB
T[ ] -.-
J[ознайомлення з описом та коментарями]--> K[перегляд змін у попередньому перегляді Netlify]
end
A[Огляд списку відкритих PR]--> B[Фільтр відкритих PR за міткою]
B --> third --> fourth
classDef grey fill:#dddddd,stroke:#ffffff,stroke-width:px,color:#000000, font-size:15px;
classDef white fill:#ffffff,stroke:#000,stroke-width:px,color:#000,font-weight:bold
classDef spacewhite fill:#ffffff,stroke:#fff,stroke-width:0px,color:#000
class A,B,J,K,M,N,O grey
class S,T spacewhite
class third,fourth white
Відфільтруйте відкриті PR, використовуючи одну або всі з наступних міток:
cncf-cla: yes (Рекомендовано): PR, подані учасниками, які не підписали CLA, не можуть бути об’єднані з осноною кодовою базою репо. Див. Підписання CLA для отримання додаткової інформації.
language/en (Рекомендовано): Фільтрує лише PR англійською мовою.
size/<розмір>: фільтрує PR певного розміру. Якщо ви новачок, почніть з менших PR.
Крім того, переконайтеся, що PR не позначено як роботу в процесі. PR з міткою work in progress ще не готові до огляду.
Після того, як ви вибрали PR для огляду, зрозумійте зміни, зроблені в ньому, шляхом:
Читання опису PR, щоб зрозуміти зроблені зміни, і читання будь-яких пов’язаних питань
Читання коментарів інших рецензентів
Клацанням на вкладку Files changed, щоб побачити змінені файли та рядки
Попереднього перегляду змін у попередньому перегляді Netlify, прокручуючи до розділу перевірки збірки PR у нижній частині вкладки Conversation. Ось знімок екрана (який показує сайт GitHub на компʼютері; якщо ви переглядаєте на планшеті або смартфоні, вебінтерфейс GitHub дещо відрізняється):Щоб відкрити попередній перегляд, натисніть на посилання Details у рядку deploy/netlify у списку перевірок.
Перейдіть на вкладку Files changed, щоб почати свій огляд.
Клацніть на символ + біля рядка, який хочете прокоментувати.
Додайте ваші коментарі щодо рядка та натисніть або Add single comment (якщо у вас є лише один коментар), або Start a review (якщо у вас є кілька коментарів).
Після завершення натисніть 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?
Чи правильно сторінка відображається у боковій навігації (або взагалі)?
Ми готові розміщувати дзеркальну версію будь-якої статті, опублікованої на 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 >}}, і часто краще, щоб вони його не використовували
ми дозволяємо авторам писати статті в їхньому власному стилі, за умови, що більшість читачів зрозуміють основну думку
ми надаємо перевагу SVG над растровими форматами діаграм і над Mermaid (джерело Mermaid можна включити у коментар)
нема потреби додавати підписи до діаграм як "Рисунок 1", "Рисунок 2" тощо
Інше
Слідкуйте за несуттєвими правками; якщо ви бачите зміну, яку вважаєте несуттєвою правкою, будь ласка, вкажіть цю політику (все ще можна прийняти зміну, якщо вона дійсно є покращенням).
Заохочуйте авторів, які роблять виправлення пробілів, робити це в першому коміті свого PR, а потім додавати інші зміни поверх цього. Це полегшує як злиття, так і огляд. Особливо звертайте увагу на несуттєві зміни, які відбуваються в одному коміті разом з великою кількістю виправлень пробілів (і якщо ви це бачите, заохочуйте автора виправити це).
Якщо ви виявляєте невеликі проблеми з PR, які не є суттєвими для змісту, наприклад, друкарські помилки або неправильне використання пробілів, додайте на початку своїх коментарів nit:. Це дає автору зрозуміти, що ця частина вашого зворотного зв’язку не є критичною.
Якщо ви розглядаєте pull request для схвалення, і весь відгук позначений як nit, ви можете обʼєднати PR в будь-якому випадку. У такому випадку часто корисно створити тікет щодо залишених незначних зауважень. Розгляньте, чи можете ви виконати вимоги для позначення цієї нової проблеми як Good First Issue; якщо ви можете, це буде хорошим початком для новачків.
