Опис pull request англійською: заголовок, контекст і що перевірити
Колега відкриває Ваш PR між двома мітингами. Що він має зрозуміти за перші десять секунд? Що змінилося, навіщо і куди дивитися уважніше. Якщо цього немає в описі, він спитає в коментарі. Або відкладе рев’ю до завтра.
Заголовок: дієслово першим, без крапки
Заголовок PR читають у списку, серед десятків інших. Тому він починається з дії. Документація Git радить описувати зміну наказовим способом, ніби Ви даєте команду коду: make, а не makes чи changed. Багато команд переносять це правило і на заголовки PR.
| Не каже нічого | Каже, що зміниться |
|---|---|
| Fixed bug | Fix crash when the cart is empty |
| Changes in auth | Add rate limiting to the login endpoint |
| Refactoring | Move price formatting into a shared helper |
Перевірка проста. Підставте заголовок у речення If merged, this PR will… Fix crash when the cart is empty туди лягає. Fixed bug не лягає. Якщо в репозиторії вже є звичка писати інакше, тримайтеся її: сусідні PR важать більше за будь-яку пораду.
Три блоки опису і четвертий за потреби
Опис не мусить бути довгим. Йому досить трьох коротких блоків під заголовками What, Why і How to test. Четвертий рядок додають, коли в дифі є щось нетипове.
| Блок | Що написати | Приклад |
|---|---|---|
| What | зміну одним-двома реченнями | Adds a retry to the export job |
| Why | проблему, яку зміна закриває | Large exports fail when the API times out. Closes #412 |
| How to test | кроки для рев’юера | Export 10,000 rows and check that the file arrives |
| Notes | де дивитися уважніше | The main change is in export_service.py. The rest is renaming |
Рядок Closes #412 працює не лише як посилання. GitHub розуміє будь-яку форму слів close, fix і resolve: Closes, Fixed, Resolves. Коли PR із таким словом злиють у гілку за замовчуванням, тікет закриється сам.
Блок How to test зручно будувати з критеріїв тікета. Як їх формулюють, показує стаття про acceptance criteria англійською.
Ці три заголовки не треба набирати щоразу. Покладіть їх у файл pull_request_template.md у корені репозиторію, і GitHub підставлятиме шаблон у кожен новий PR.
У групах розробників ми часто бачимо опис-щоденник: First I tried to cache the response, then I found that… Рев’юеру потрібен результат, а не шлях до нього. Історію пошуку залиште на один рядок у Notes, і лише якщо вона пояснює відкинутий варіант: Caching didn’t help because the data changes every minute.
Draft чи ready for review
Стан PR показує і сама позначка. Чернетку (draft) не можна злити, і GitHub сам не покличе на рев’ю власників коду, тобто людей, відповідальних за ці файли. Тому чернетка годиться, коли потрібен ранній погляд на підхід, а не перевірка кожного рядка. Позначка ready for review сама надішле запит власникам коду.
Як попросити рев’ю і не підганяти
Перед запитом перегляньте свій диф самі. GitHub радить саме це: власне рев’ю ловить випадкові зміни й показує колегам, що PR готовий. Потім одне повідомлення з іменем, місцем у коді й терміновістю.
Якщо рев’ю стоїть другий день, нагадайте одним рядком: Friendly ping on this one. Happy to walk you through it on a call. Великий PR дешевше розбити, ніж чекати: малий переглядають швидше, і злити його безпечніше. Коли коментарі прийшли, відповідати на них допоможе розбір англійської для code review.
Два питання, які ставлять перед першим PR
Опис PR писати в теперішньому чи минулому часі?
Заголовок пишуть наказовим способом: Add, Fix, Remove. Так радить, зокрема, документація самого Git: описувати зміну як наказ коду. В описі годиться і This PR adds, і Added. Важливо, щоб увесь опис тримав один часЧи потрібен опис, якщо зміна в один рядок?
Потрібен, хоча б одне речення про причину. Код показує, що змінилося. Навіщо, видно лише з опису або тікета. Через пів року причину шукатимуть саме в історії змін, а не в пам’яті автораЩо зробити сьогодні: відкрийте свій останній PR і перевірте заголовок реченням If merged, this PR will… Не лягає, перепишіть дієсловом.
Про ті самі зміни Вас спитають на ранковому дзвінку, і для нього є розбір стендапу англійською. Описи PR і коментарі окремо тренують на курсі, це технічна англійська для IT з коментарями до PR і тікетами.