Стандартизация коммитов с Conventional Commits и автоматизация CHANGELOG

Почему без Conventional Commits история изменений нечитаема

Пока договорённости о формате нет, каждый коммит пишется как получится: «фикс», «поправил», «ещё правки», «доработка по задаче». Формально история изменений есть, фактически по ней нельзя понять, что и зачем поменяли. Через месяц такое не восстановит даже автор строки — останутся только дата и фамилия.

Дальше ломается всё, что опирается на эту историю. Перечень изменений к выпуску собирают вручную, вычитывая десятки сообщений, и он всё равно расходится с реальностью: часть правок в него не попадает, а отдельные строки описывают работы, которые в релиз не вошли. Разбор релиза превращается в археологию по датам и веткам.

Цена особенно заметна при разборе сбоя. Нужно найти изменение, внёсшее дефект, но поиск по описанию не работает: в сообщениях нет ни затронутой подсистемы, ни характера правки. Приходится перебирать диапазон коммитов, вручную смотреть диффы и опрашивать людей — это часы вместо минут, и всё это на фоне горящего выпуска.

Conventional Commits задаёт сообщению структуру: тип изменения, область, краткое описание и явный признак несовместимой правки. Такая история читается человеком и разбирается инструментами: из неё автоматически собирается CHANGELOG, а по типу коммита видно, нужна ли выпуску миграция. Читаемость истории перестаёт зависеть от дисциплины отдельных разработчиков.

Стандарт сообщений — не про красоту логов, а про то, чтобы выпуск и разбор сбоя опирались на факты, а не на память участников. Ниже разбираем, как это выстраивается на практике.

Что даёт единый формат сообщений о правках

Сообщение о правке перестаёт быть свободным текстом и становится данными: тип изменения, затронутая область, суть, номер задачи. Стандарт Conventional Commits задаёт эту разметку, и инструмент разбора сам собирает журнал изменений — версию, список исправлений, отдельно помеченные ломающие изменения. Автосборка убирает ручной этап перед выпуском, который обычно съедал день-два, а вместе с ним — забытые пункты и расхождения между описанием релиза и его содержимым.

Единый формат сообщений сокращает долю ручных операций в подготовке версии до нескольких подтверждений: инженер просматривает собранный черновик и запускает выпуск. Проверка формата на стороне сервера отсекает нечитаемые сообщения до попадания в основную ветку, поэтому журнал не приходится разбирать и дописывать задним числом, когда контекст уже потерян.

Меняется и класс отказов, которые доходят до пользователя. Когда тип правки виден из истории, ломающее изменение помечается явно и не уезжает в рядовой выпуск по невнимательности. Откат становится точным: по журналу видно, какая версия принесла регресс, и её снимают, не перебирая весь диапазон изменений между сборками.

Контроль качества правок опирается на ту же разметку: проверяющий видит назначение изменения до чтения кода, связанные задачи собираются по номеру автоматически, а доля правок, требующих уточнений на проверке, падает за счёт понятного описания. Возврат к старой ветке перестаёт быть раскопками — история читается линейно и по смыслу каждого изменения.

Conventional Commits или свободный формат: что выбрать

Выбор здесь не между «стандартом» и хаосом, а между уровнями принуждения. Свободный формат держится на устной договорённости, конвенциональный — на правиле, которое проверяет машина: линтер сообщений на хуке перед коммитом и та же проверка в конвейере сборки. Чем раньше срабатывает отказ, тем дешевле исправление — отклонённое сообщение стоит минуту, а разбор истории на релизе — часы.

Критерий применимости — не размер команды, а то, кто и как часто собирает CHANGELOG и нумерует версии. Пока это делает один человек вручную, хватает договорённости. Как только релизы становятся регулярными, а репозиториев больше одного, правило нужно закреплять технически.

Варианты не исключают друг друга: к автоматическому выпуску обычно идут поэтапно — сначала проверка типов, затем генерация журнала и нумерация. Ограничения каждого шага видны заранее, и это как раз определяет, где разумно остановиться, а где правило уже мешает работать.

Этапы внедрения стандарта и автосборки журнала

Стандарт не внедряется одним коммитом: если сразу включить жёсткие проверки, команда начнёт обходить их через --no-verify, и правило превращается в формальность на второй неделе. Поэтому идём волной — от разбора накопленной истории к автоматике, которая сама держит формат.

1. Аудит истории и привычек. Разбираем лог за несколько месяцев: доля сообщений, из которых журнал собрать нельзя, какие префиксы реально используются, где в одном коммите смешаны разнородные изменения. На выходе — карта типов и понимание объёма разовой нормализации.
2. Согласование словаря. Фиксируем закрытый набор типов (feat, fix, chore, docs, refactor, perf, test, build) и границы применения каждого. Список уходит в версионируемый файл рядом с кодом, а не в вики.
3. Настройка локальных проверок. Перехватчик на стороне разработчика сверяет сообщение до отправки и сразу показывает, чего не хватает — тип, область, описание. Ошибка видна за секунды, а не на сборочном сервере.
4. Контроль на стороне репозитория. То же правило повторяется в сборке основной ветки, чтобы формат нельзя было обойти локальными настройками. Ломающие изменения помечаются отдельным маркером и отдельной секцией журнала.
5. Генерация журнала. Генератор разбирает сообщения, группирует записи по типам и собирает выпуск. Шаблон фиксирует порядок секций, ссылки на задачи и авторов — версия собирается без ручного редактирования.
6. Встраивание в релизный цикл. Выпуск, тег и файл журнала появляются как артефакт сборочного процесса, а не как задача для релиз-инженера.
7. Передача команде. Памятка на один экран, шаблон сообщения, разбор частых ошибок и контрольная точка через месяц: смотрим долю прошедших проверку сообщений и правим правила, которые оказались лишними.

Правила проверки, шаблоны и регламенты выпуска версий

Регламент проверки держится не на устных договорённостях, а на артефактах, к которым команда возвращается в спорной ситуации. Ниже — что остаётся у заказчика в репозитории после завершения работ.

• Документация по процессу: жизненный цикл сообщения от локальной ветки до тега, примеры корректных и отклонённых коммитов, разбор частых ошибок.
• Шаблоны сообщений: заготовка для ввода коммита и подсказка в терминале, которая предлагает тип, область изменений и краткое описание.
• Конфигурация проверок: правила линтера и хук на этапе подготовки коммита — неподходящий формат не попадает в историю ветки.
• Регламент выпуска версий: порядок действий перед релизом, схема нумерации, правила сборки CHANGELOG и точки, где нужна ручная правка.
• Политики доступа: роли в репозитории, кто вливает изменения в основную ветку и кто вправе ставить теги.
• Инструкции для команды: памятки под частые ситуации — правка отправленного коммита, откат релиза, изменение шаблона.
• Схемы связей: как проверки, автоматика и релизные шаги соотносятся между собой, чтобы новый инженер разобрался без сопровождения.

Каждый документ лежит рядом с кодом и обновляется вместе с ним — правила не расходятся с реальным состоянием репозитория.

Кейс: единый формат и автосборка журнала изменений

До: журнал изменений собирался вручную

Команда из восьми человек вела журнал изменений руками: перед выпуском техлид проходил по истории коммитов, восстанавливал смысл правок по сообщениям вида «правки», «поправил» и «ещё немного» и раскладывал их по разделам. На подготовку описания выпуска уходило до двух рабочих дней, и чем больше было изменений, тем выше шанс, что часть из них потеряется или попадёт не в тот раздел.

Что изменили

Ввели Conventional Commits как обязательный формат сообщения: тип, область и краткое описание изменения. Сообщение проверяется локальным хуком до создания коммита и повторно на стороне сервера при приёме ветки, поэтому нарушение формата просто не проходит дальше — исправлять приходится автору правки, а не рецензенту выпуска. Из типов и областей журнал собирается автоматически: разделы «Новое», «Исправления» и «Внутренние изменения» формируются сборкой, номер версии поднимается по правилам смыслового версионирования без ручного решения.

После: метрики

Подготовка выпуска сократилась с двух дней до 40 минут — остаётся вычитка формулировок, а не восстановление истории. Доля правок, возвращавшихся на доработку из-за неописанных или неверно описанных изменений, упала с каждой четвёртой до менее одной из двадцати. Отказы по причине «выпустили не то, что заявлено» прекратились: описание и содержимое выпуска теперь генерируются из одного источника, и расхождение между ними технически невозможно.

Отдельный эффект — предсказуемая навигация для тех, кто обновляется с предыдущей версии: по журналу видно, какие изменения затрагивают их конфигурацию, а какие внутренние.

Что делать, если история накоплена в свободном формате

Правила Conventional Commits можно включить поверх любой существующей истории — переписывать прошлое почти никогда не требуется. Массовый rebase сотен коммитов меняет хеши, обесценивает ссылки в задачах и подписи тегов, а команда на недели теряет возможность сверять ветки с выпусками. Достаточно провести границу по дате: всё после неё идёт по формату, всё до — остаётся как есть.

Граница фиксируется проверкой на приёме: сервер отклоняет коммит, в заголовке которого нет корректного типа и области, и возвращает автору понятное сообщение об ошибке. Генератор CHANGELOG при этом стартует не с корня репозитория, а с явно отмеченной точки отсчёта — обычно это тег первого выпуска после миграции.

Накопленная история никуда не девается: прошлые выпуски переносятся в отдельный статичный файл, который дальше не обновляется, а новые записи собираются автоматически. Для старых проектов это дешевле, чем восстанавливать тип и область для каждого коммита задним числом, — цена такой работы почти всегда выше пользы.

Полное переписывание оправдано в двух случаях: репозиторий открывается наружу и в сообщениях осталось служебное, либо код переезжает в новый репозиторий. Тогда историю сворачивают до одного стартового коммита, а нумерацию выпусков продолжают по тегам.

Сомнения и ограничения: ветки, слияния, массовые правки

Стандарт задаёт формат сообщения, но не описывает процесс — возражения касаются мест, где правила сталкиваются с реальной работой в ветках.

Слияния. Заголовок коммита слияния формирует система контроля версий, а не человек, поэтому под шаблон он не подходит. Такие коммиты исключают из проверки и из выборки для журнала изменений — иначе журнал заполняется служебным шумом. Если ветка вливается одним сжатым коммитом, текст берётся из заголовка запроса на слияние: проверку ставят на стороне сервера, а не только в локальном хуке.

Массовые правки. Форматирование, переименование модуля или автоматический рефакторинг дают сотни однотипных коммитов. Их сводят в один тип изменения, чтобы журнал не раздувался, а переписывание истории делают до публикации ветки — иначе ссылки на коммиты в обсуждениях перестают открываться.

Спорные случаи и границы. Обратно несовместимое изменение иногда логичнее оформить внутри исправления, а откат — отдельным типом: стандарт допускает это через блок описания в теле сообщения, но требует явной пометки — иначе автоматический разбор версии ошибётся. И честное ограничение: правила описывают только сообщения коммитов, а соглашение о ветках, порядок ревью и частоту релизов они не заменяют.

Можно ли отступить от правила для массовой правки?

Да, но отступление должно быть одинаковым для всей партии: единый тип, одно описание. Тогда журнал остаётся связным, а история — пригодной для поиска причины изменения.

Обсудим внедрение стандарта правок в вашей команде

Когда стандарт описания правок обсуждают «на словах», разговор упирается в личные привычки: для одного это служебные сообщения, для другого — история проекта, по которой потом восстанавливают причины изменений. Чтобы оценка и план опирались на ваш процесс, а не на общий шаблон, к разговору стоит подготовить несколько фактов о том, как правки живут сейчас.

• как формулируют описание правок и кто проверяет его на ревью;
• сколько веток ведётся параллельно и как происходит слияние в основную;
• как выпускаются версии — вручную, по расписанию или по готовности набора правок;
• что сейчас попадает в журнал изменений и кто его собирает перед выпуском;
• какие проверки уже стоят на стороне сервера перед приёмом правки;
• есть ли правки, меняющие поведение системы несовместимо, и как их помечают.

На выходе команда получает соглашение о формате, правило автоматической проверки описания перед приёмом правки и сборку журнала изменений прямо из истории. Нумерация версий и раздел про несовместимые изменения начинают формироваться машиной, а не памятью дежурного — ручной этап перед выпуском сокращается до просмотра готового текста.

Разбираем и обратный переход: часть правок в старой истории не размечена, поэтому для них задаём правила приведения и переходный период, когда проверка предупреждает, но не блокирует. Опишите задачу и пришлите то, что уже есть, — вернёмся с оценкой и планом: где стандарт внедряется без трения, а где нужен отдельный этап миграции.