Описание PR: what, why, how, чеклист
Тема дорожной карты · Английский для IT
🔊 Словарь терминов с произношением →
Описание pull request — это документ, который ревьюер читает до кода, и от него зависит, займёт ревью пять минут или час. Устоявшаяся структура состоит из трёх вопросов. What — что меняется, в двух-трёх предложениях, без пересказа диффа: Adds CSV export for the user list. Introduces an ExportService and a new endpoint GET /api/users/export. Why — зачем, со ссылкой на тикет или обсуждение: Support asked for a way to hand user lists to finance without DB access (JIRA-812). How — как проверить и на что обратить внимание: Tested locally with 50k rows; export streams, memory stays flat. Please look closely at the CSV escaping in csv.ts. Дополнительно: Screenshots для UI, Breaking changes если есть, Migration notes для схемы БД, Rollout plan для рискованных изменений, Out of scope для того, что намеренно не сделано. Чеклист в конце PR — маркеры вида - [x] Tests added, - [x] Docs updated, - [ ] Feature flag created — показывает ревьюеру, что автор проверил сам. Заголовок PR подчиняется тем же правилам, что и заголовок коммита: повелительное наклонение, до 72 символов, префикс типа при Conventional Commits.
Как произносится
Pull request /ˌpʊl rɪˈkwɛst/, сокращённо PR /ˌpiː ˈɑːr/ («пи-ар»), merge request /ˈmɜːrdʒ rɪˈkwɛst/, description /dɪˈskrɪpʃən/, draft /drɑːft/ или /dræft/ (черновик PR), checklist /ˈtʃɛklɪst/, screenshot /ˈskriːnʃɒt/, scope /skoʊp/, out of scope («за рамками»), follow-up /ˈfɒloʊ ʌp/ (последующая задача), reviewer /rɪˈvjuːər/, assignee /əˌsaɪˈniː/ («эсайнИ», ударение на последний слог; тот, кому назначено), label /ˈleɪbl/ (метка), milestone /ˈmaɪlstoʊn/.
Как употребляется
Фразы из описаний и обсуждений PR:
- This PR adds… / This PR fixes… / This PR refactors… — стандартное начало раздела What.
- Closes #123. — закрывает тикет автоматически при merge.
- Marked as draft, not ready for review yet. — Черновик, ещё не готов к ревью.
- Ready for review. / PTAL. — Готов к ревью.
- Out of scope: pagination, tracked in #130. — За рамками: пагинация, отдельный тикет.
- Follow-up PR will handle the UI. — Интерфейс будет в следующем PR.
- Tested on staging, no regressions. — Проверено на стейдже, регрессий нет.
- Happy to split this into smaller PRs if preferred. — Могу разбить на несколько PR, если так удобнее.
- Depends on #128 being merged first. — Зависит от слияния #128.
Ловушки
Первая ловушка — пустое описание или одна строка fix bug: ревьюер вынужден восстанавливать контекст из диффа, и ревью затягивается. Вторая — пересказ диффа вместо смысла: Changed line 45, added function foo видно и так; нужно «зачем». Третья — описание в прошедшем времени от первого лица (I added, I fixed): в англоязычных проектах принято безличное настоящее This PR adds или повелительное Add. Четвёртая — русские скриншоты интерфейса без пояснения в международном проекте: ревьюер не прочитает подписи. Пятая — огромный PR без структуры: если изменений больше 400 строк, укажите порядок чтения (Start with service.ts, the rest is plumbing) или разбейте. Шестая — чеклист для галочки: отмеченный Tests added при отсутствии тестов подрывает доверие сильнее, чем отсутствие чеклиста.