Будь-хто може рецензувати 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?
Чи правильно сторінка відображається у боковій навігації (або взагалі)?
Чи відображаються зміни у попередньому перегляді Netlify? Будьте особливо уважними до списків, блоків коду, таблиць, приміток та зображень.
Інше
Слідкуйте за несуттєвими правками; якщо ви бачите зміну, яку вважаєте несуттєвою правкою, будь ласка, вкажіть цю політику (все ще можна прийняти зміну, якщо вона дійсно є покращенням).
Заохочуйте авторів, які роблять виправлення пробілів, робити це в першому коміті свого PR, а потім додавати інші зміни поверх цього. Це полегшує як злиття, так і огляд. Особливо звертайте увагу на несуттєві зміни, які відбуваються в одному коміті разом з великою кількістю виправлень пробілів (і якщо ви це бачите, заохочуйте автора виправити це).
Якщо ви виявляєте невеликі проблеми з PR, які не є суттєвими для змісту, наприклад, друкарські помилки або неправильне використання пробілів, додайте на початку своїх коментарів nit:. Це дає автору зрозуміти, що ця частина вашого зворотного зв’язку не є критичною.
Якщо ви розглядаєте pull request для схвалення, і весь відгук позначений як nit, ви можете обʼєднати PR в будь-якому випадку. У такому випадку часто корисно створити тікет щодо залишених незначних зауважень. Розгляньте, чи можете ви виконати вимоги для позначення цієї нової проблеми як Good First Issue; якщо ви можете, це буде хорошим початком для новачків.
