Junior: питання на співбесіді з теми «Pull request і code review»

Pull request (у GitLab - merge request) - це пропозиція влити зміни з однієї гілки в іншу. Навколо неї відбувається все обговорення: рев'ю коду, коментарі до рядків, результати CI, затвердження. Сам Git про pull request нічого не знає - це функція платформи (GitHub, GitLab, Bitbucket).

Навіщо потрібен опис: рев'юер бачить диф, але не бачить, навіщо зміна зроблена, які варіанти відкинуто і як її перевірити. Добрий опис економить кілька раундів запитань.

Шаблон опису:

## Що і навіщо
Додає експорт вакансій у CSV для адмінки. Менеджери зараз копіюють
таблицю вручну.

Closes #412

## Як зроблено
- `VacancyExport` формує файл потоково, щоб не тримати 50k рядків у пам'яті
- експорт іде в черзі, посилання приходить листом

## Як перевірити
1. Адмінка → Вакансії → «Експорт»
2. Дочекатися листа, відкрити файл

## На що звернути увагу
Не впевнений щодо формату дат - зараз ISO 8601.

Що робить опис добрим:

• проблема, а не перелік файлів - «що змінилося» видно в дифі, а «чому» - ні;
• посилання на задачу (Closes #412) - контекст і автоматичне закриття задачі;
• інструкція з перевірки - рев'юер може відтворити поведінку;
• скріншоти чи відео для змін інтерфейсу;
• ризики й відкриті питання - куди дивитися уважніше;
• заголовок як у доброго коміту - коротко про суть: «Експорт вакансій у CSV», а не «fix» чи «updates».

Шаблон для всієї команди - файл .github/pull_request_template.md: GitHub підставляє його в кожен новий pull request, і структура опису стає однаковою.

Докладніше в документації: GitHub: pull requests

Великий pull request рев'ю не проходить - він проходить «апрув». На 50 рядках рев'юер знаходить проблеми, на 2000 - гортає й пише «LGTM». Якість рев'ю падає разом з розміром.

Чому маленькі PR кращі:

• швидше рев'ю: 15 хвилин легко знайти між задачами, дві години - ні. Великі PR лежать днями;
• якісніше рев'ю: у фокусі одна ідея, помилки помітніші;
• менше конфліктів: гілка живе годину чи день, а не тиждень;
• простіший відкат: якщо щось зламалося, відкочується одна невелика зміна;
• зрозуміла історія: кожен PR - окремий логічний крок.

Орієнтир: до кількох сотень рядків змістовних змін. Згенеровані файли, lock-файли й міграції з даними рахуються окремо.

Як розбивати велику задачу:

• підготовчий рефакторинг окремо: перейменування, винесення класу, зміна сигнатури - без зміни поведінки, тому рев'ю швидке;
• шарами: спершу міграція й модель, далі сервіс з тестами, потім контролер і інтерфейс;
• за прапорцем функції (feature flag): незавершена функціональність потрапляє в main вимкненою, і можна вливати частинами;
• механічні зміни окремо від логіки: масове форматування чи перейменування в одному PR, нова поведінка - в іншому. Інакше справжня зміна губиться серед сотень рядків шуму.

Чого уникати:

• змішувати кілька непов'язаних змін «раз уже я тут» - кожна ускладнює рев'ю й відкат;
• розбивати так, що окремий PR не має сенсу й не проходить тести - кожен крок має лишати main робочим.

Якщо PR все ж великий - напишіть в описі, з чого почати читання, і проведіть рев'юера за ключовими файлами.

Докладніше в документації: GitHub: як допомогти рев'юерам

Draft (чернетка) - стан pull request, який означає «ще не готово до рев'ю». Чернетку видно команді, на неї працює CI, її можна коментувати, але:

• влити її не можна, доки автор не позначить її готовою (Ready for review);
• власників коду (CODEOWNERS) не запитують на рев'ю автоматично - запит надходить, коли PR стає готовим.

gh pr create --draft --title "Експорт вакансій у CSV"
gh pr ready 412        # позначити готовим до рев'ю

Коли відкривати draft:

• ранній відгук щодо підходу: «я збираюся зробити так - чи це правильний напрямок?» до того, як написано тисячу рядків;
• прогнати CI на реальному середовищі, поки робота триває;
• показати прогрес і позначити, що задача в роботі, - інші бачать гілку й не дублюють роботу;
• обговорити дизайн на конкретному коді, а не абстрактно.

Етикет:

• в описі чернетки варто написати, що саме хочете отримати: «подивіться лише на структуру сервісу, тести ще не готові»;
• не просити повного рев'ю чернетки - рев'юер витратить час на код, який ще зміниться;
• перед переведенням у Ready - самостійно переглянути диф, прибрати налагоджувальний код, оновити опис, переконатися, що CI зелений.

Альтернатива у старих процесах - префікс WIP: у заголовку. Draft кращий: це стан, який платформа розуміє й поважає (блокує злиття, не тривожить рев'юерів), а не домовленість, яку легко пропустити.

Докладніше в документації: GitHub: draft pull requests

GitHub розпізнає ключові слова в описі pull request (і в повідомленнях комітів) і пов'язує PR із задачею:

Closes #412
Fixes #418, resolves #420
Fixes acme/api#77

Ключові слова: close, closes, closed, fix, fixes, fixed, resolve, resolves, resolved. Регістр не важливий, двокрапка після слова допускається.

Що відбувається:

• задача показує, що над нею працюють, і містить посилання на PR;
• після злиття PR задача закривається автоматично;
• можна вказати задачу з іншого репозиторію: owner/repo#номер.

Важливий нюанс: ключові слова працюють, лише якщо PR спрямовано в гілку за замовчуванням (зазвичай main). PR у develop чи релізну гілку з Closes #412 не створить зв'язку й не закриє задачу. Для таких випадків зв'язок створюють вручну на бічній панелі PR (розділ Development).

Згадка без закриття: просто #412 чи «див. #412» створює перехресне посилання, але задачу не закриває. Це доречно, коли PR лише частина роботи:

Частина #412: міграція й модель. Інтерфейс - окремим PR.

Практичні поради:

• одна задача - одна причина PR: якщо PR закриває п'ять задач, це, мабуть, кілька різних змін;
• для задач з трекера поза GitHub (Jira, Linear) - номер задачі в назві гілки чи заголовку (ABC-123), а інтеграція трекера підхопить зв'язок;
• автопосилання (Settings → Autolink references) перетворюють ABC-123 у тексті на посилання на зовнішній трекер.

Докладніше в документації: GitHub: зв'язок pull request із задачею

Рев'ю на GitHub - це набір коментарів, які відправляються разом з підсумковим рішенням. Поки рев'ю не відправлене, коментарі видно лише вам.

Три варіанти завершення рев'ю:

Якщо в репозиторії налаштовано обов'язкове схвалення, Request changes блокує злиття, доки рецензент не змінить рішення чи рев'ю не відхилять (dismiss).

Коментарі до рядків прив'язуються до конкретного місця дифу - можна виділити кілька рядків і прокоментувати весь фрагмент.

Suggestion - запропонувати готову правку:

```suggestion
$vacancies = Vacancy::query()->with('company')->latest()->paginate(20);
```

Автор бачить диф пропозиції й натискає Commit suggestion - правка стає комітом у гілці PR. Кілька пропозицій можна застосувати одним комітом через Add suggestion to batch.

Коли suggestion доречний: друкарська помилка, перейменування, очевидний однорядковий фікс. Для складніших змін краще пояснити ідею словами - автор знає контекст краще.

Корисні звички:

• збирати коментарі в одне рев'ю (Start a review), а не відправляти по одному - автор отримує одне сповіщення, а не двадцять;
• позначати Viewed переглянуті файли - при оновленні PR GitHub покаже, які з них змінилися;
• Resolve conversation - коли питання закрите; зазвичай це робить той, хто його відкрив, або автор після виправлення;
• повторний запит рев'ю (Re-request review) після виправлень - рецензент отримає сповіщення.

Докладніше в документації: GitHub: рев'ю pull request