Сообщить об ошибкеКороткий ответ
Описание PR должно коротко отвечать на вопросы «что изменилось и зачем», «как это проверить» и «на что обратить внимание», а не просто дублировать название задачи.
Как это работает подробнее
Хорошее описание экономит время ревьюера: он сразу понимает контекст изменения, не читая всю историю переписки в таск-трекере. Обычно в описание включают ссылку на задачу, краткое резюме изменений, список затронутых мест и шаги проверки (как запустить, что проверить вручную, если это не покрыто тестами). Описание фактически заменяет собой короткую устную презентацию изменения, которую иначе пришлось бы делать лично.
Пример кода
example.txt
Плохое описание PR:
"ABC-123"
Хорошее описание PR:
"Исправляет ABC-123: при пустой корзине эндпоинт /checkout падал с 500,
т.к. total() не обрабатывал None. Добавлена проверка и unit-тест.
Как проверить: вызвать POST /checkout с items=[] — должен вернуться 400
с понятным сообщением вместо 500."Что использовать на практике
- Практика. Если PR большой или затрагивает несколько независимых вещей, стоит явно перечислить их по пунктам — это помогает ревьюеру распределить внимание и не пропустить менее очевидные части диффа. Скриншоты или примеры запросов/ответов полезны для изменений в API или UI, а ссылка на задачу в трекере — для тех, кому нужен более широкий бизнес-контекст.
Подводные камни
- Риски. Частая ошибка — оставить описание пустым или ограничиться названием задачи вида «Fix bug ABC-123», не объяснив, в чём была причина бага и как её исправили. Это заставляет ревьюера самостоятельно реконструировать контекст по коду, что увеличивает время ревью и риск пропустить проблему. Другая ошибка — описать только «что сделано», но не «как это проверить», из-за чего ревьюер вынужден сам придумывать сценарий тестирования.