Як мейнтейнер, ми досить регулярно переглядаємо pull request.
У цьому документі зібрано рекомендації щодо перегляду pull request, прийняті в Exercism.
Перегляд pull request до вправ
Переглядати pull request до Concept Exercise чи Practice Exercise буває складно, адже з цими типами вправ повʼязано багато правил.
Саме тому первинний перегляд силами одного мейнтейнера часто займає дві-три години й дає десятки коментарів.
А для Concept Exercise є ще й файли зі схожими цілями та вмістом (наприклад, вступ до вправи та вступ до концепції), і тут важливо спершу довести до пуття щось одне, перш ніж надто широко розгалужуватися.
Щоб спростити цей процес, ми підготували такі рекомендації.
Рекомендація: нехай первинний перегляд веде один досвідчений мейнтейнер
Причини, чому первинний перегляд має вести саме один досвідчений мейнтейнер, такі:
- Ніхто не виконує ту саму роботу з перегляду двічі
- Контрибʼютор і мейнтейнер працюють над pull request у парі, і контрибʼютор, сподіваємося, відчуває, що не робить це сам
- Не буде суперечливих коментарів щодо перегляду від інших мейнтейнерів
Рекомендація: зливати зі status зі значенням wip
Коли і контрибʼютор, і мейнтейнер задоволені вправою, її варто злити зі status зі значенням wip (wip означає «робота в процесі»).
Вправи з таким статусом не будуть доступні учням, але їх зможуть переглядати наші найкращі наставники (коли ми колись це реалізуємо).
Ці користувачі з високою репутацією зможуть протестувати вправу й створити issue або pull request, щоб виправити чи покращити її.
Основні переваги такого підходу:
- Це знімає з початкової пари «контрибʼютор і мейнтейнер» тягар необхідності зробити все ідеально
- Це не призводить до величезних циклів pull request з безліччю голосів (а керувати ними справді важко)
Перегляд pull request до Practice Exercise
Рекомендація: подумати, чи справді ця зміна належить до problems-specifications
Частина вмісту Practice Exercise (наприклад, її вступ) походить зі спільних метаданих, визначених у репозиторії problems-specifications.
Переглядаючи pull request, який змінює такий вміст, подумаймо, чи не буде ця зміна корисною й для інших треків.
Якщо так, варто запропонувати контрибʼютору відкрити pull request до відповідного файлу в репозиторії problems-specifications
Загальні рекомендації щодо перегляду
Рекомендація: один головний рецензент на кожен pull request
У кожного pull request має бути один головний рецензент (той мейнтейнер, який його взяв).
Інші мейнтейнери та/або учасники спільноти діють у другорядній ролі.
Є два основні способи, у які людина в другорядній ролі може долучитися до перегляду:
- Вичитати правопис і граматику, але лише після того, як первинний перегляд від головного рецензента вже відбувся.
Контрибʼюторів може засмутити, якщо спершу вони отримають зауваження до правопису й граматики, виправлять їх, а потім прийде мейнтейнер і попросить внести ґрунтовніші зміни.
Інакше кажучи, вичитування робимо після того, як ґрунтовні зміни вже враховано (або, можливо, в окремому pull request).
- Звертати увагу на речі так, щоб головний рецензент не сприймав їх як завдання до виконання.
Якщо ми коментуємо те, про що головному рецензенту варто подумати або що він міг пропустити, то краще подати коментар як думку або сформулювати його як запитання.
Так контрибʼютору буде зрозуміло, що ми не просимо його щось змінювати, і йому буде менше плутанини.
Це також зменшить імовірність того, що головний рецензент відчує, ніби хтось підриває його авторитет.
Рекомендація: не коментувати те, що не стосується справи
Переглядаючи pull request, коментуймо лише те, що безпосередньо з ним повʼязано.
Усе інше варто винести в окремий issue або створити для нього окремий (наступний) pull request.
Рекомендація: посилатися на документацію
Коли це можливо, варто завжди посилатися на документацію, яка пояснює, чому ми щось коментуємо.
Це дуже допомагає зменшити ймовірність того, що обговорення перетвориться на суперечку.
Рекомендація: просити допомоги в інших команд
Якщо потрібна допомога з переглядом pull request, можна звернутися до двох конкретних команд:
-
@exercism/reviewers: для будь-яких загальних переглядів
-
@exercism/github-actions: для будь-яких запитань щодо GitHub actions
