Как называть PR правильно: гайд по понятным и полезным заголовкам

Зачем вообще думать о названии PR

Заголовок PR — это первое, что видит ревьюер и поисковик в истории изменений. От него зависит скорость ревью, качество релиз‑нотов и то, насколько быстро вы сами поймете, что происходило полгода назад.

Хороший заголовок даёт три вещи:

• Контекст: где меняем
• Действие: что делаем
• Ценность/итог: зачем (какой эффект)

Рабочий шаблон заголовка

Рекомендую придерживаться варианта, совместимого с Conventional Commits, но без фанатизма:

<type>(<scope>): <imperative - что делаем> — <итог/ценность>

Где:

• type: feat, fix, refactor, perf, docs, test, build, ci, chore, revert
• scope: область/модуль/пакет, например payments, auth, search/api, ui/buttons
• Императив: «add», «fix», «remove», «rename», «refactor», «optimize», «revert»

Примеры:

• feat(payments): add idempotency key to capture endpoint — avoid double charge
• fix(auth): skip disabled users in token rotation — reduce 500s
• refactor(cart): extract price calculator service
• perf(search): cache empty queries for 5m — p95 -25%
• docs: update README for local setup

Допустимо опустить «— итог», если он очевиден, но лучше оставлять хотя бы короткий эффект.

Плохо vs хорошо

• Плохо: fix, changes, WIP, misc updates

• Хорошо: fix(webhook): abort payment on timeout callback — prevent duplicates

• Плохо: FOO-123

• Хорошо: feat(orders): add invoice email job (FOO-123)

• Плохо: final, tmp, new logic, bugfix, эмодзи вместо смысла

• Хорошо: refactor(api): rename user_id -> account_id in v2 endpoints

Правила, которые экономят десятки минут ревью

• Длина: старайтесь уместиться в 50–72 символа. Без точки в конце.
• Язык: по умолчанию — английский для кросс‑командной коммуникации.
• Время/наклонение: используйте повелительное наклонение (add, fix, remove), а не прошедшее время.
• Без WIP в названии: для этого есть Draft PR.
• Ссылки на задачи: добавляйте в конец Fixes #123 или (PROJ-456).
• Один смысл — один PR: если в названии хочется перечислить «и то, и это», вероятно, PR нужно разделить.

Шаблоны для разных типов PR

• feat: feat(<scope>): add <что> — <ценность>
• fix: fix(<scope>): fix <что> — <симптом/метрика>
• refactor: refactor(<scope>): extract/inline/rename <что>
• perf: perf(<scope>): optimize <что> — p95 -X%/alloc -Y%
• docs: docs: update <что>
• chore/build/ci: chore(ci): bump Go to 1.22.2
• test: test(<scope>): add/expand <что>
• revert: revert: <предыдущий заголовок> (reverts <sha/PR#>)

Как выбирать scope

• Используйте понятные срезы системы: auth, payments, search, ui/table, infra/ci.
• В монорепо добавляйте workspace/папку: app/web/auth, services/billing.
• Избегайте абстракций типа core, misc — они не помогают найти место изменений.

Чек‑лист перед отправкой PR

• Заголовок отвечает на «где/что/зачем». Да/Нет?
• Тип выбран корректно (feat/fix/refactor/...)?
• Scope помогает понять область кода?
• Императив и без точки в конце?
• Есть ссылка на issue/задачу, если применимо?
• Эффект/метрика указаны (если релевантно)?

Анти‑паттерны заголовков

1. update/changes — не несёт смысла.
2. Только номер задачи: ABC-123 — заставляет переходить по ссылке.
3. Прошедшее время: added, fixed — хуже читается в истории.
4. Заглавные буквы целиком: СЛОЖНО ЧИТАТЬ.
5. Несколько областей через слэш/запятую — признак слишком широкого PR.
6. Шутки/эмодзи вместо смысла.
7. «WIP» — используйте Draft.
8. Слишком длинно с деталями имплементации — перенесите в описание PR.
9. Внутренние термины команды без контекста — непонятно новичкам.
10. «hotfix» как тип для чего угодно.

Автоматизация правил

Чтобы команда реально следовала конвенции, добавьте проверку заголовка в CI (Danger/Action/бот), например регуляркой:

^(feat|fix|refactor|perf|docs|test|build|ci|chore|revert)(\([a-z0-9/_-]+\))?:\s[^\s].{5,}$

И настройте шаблон PR (PULL_REQUEST_TEMPLATE.md), где явно попросите кратко указать эффект/метрику.

Дополнительно, для визуальной маркировки типов изменений можно использовать инструмент Devmoji от Folke: он автоматически добавляет понятные эмодзи к сообщениям коммитов (feat ✨, fix 🐛, docs 📝 и т.д.) по Conventional Commits. Подключите его через git hook или в CI — история станет заметно читабельнее.

Быстрая настройка Husky-хука для Devmoji:

npm i -D devmoji husky
npx husky install
npx husky add .husky/prepare-commit-msg "npx devmoji -e --lint"

Итог

Хороший заголовок PR — это 10 секунд вашей дисциплины, которые экономят десятки минут команде и делают историю проекта самодокументируемой. Держите простой шаблон под рукой и автоматизируйте проверку — и через неделю история коммитов и релиз‑нотов станет понятнее в разы.