Conventional Commits

Коротко: Угода про повідомлення комітів із фіксованим форматом: <тип>(<область>): <короткий опис>, наприклад feat(shop): ... або fix(chat): ....

Докладніше: Поширені типи: feat (нова функція), fix (виправлення помилки), refactor (реструктуризація без зміни поведінки), chore (обслуговування, наприклад оновлення залежностей), perf (продуктивність). Робить історію комітів машинозчитною (наприклад, для автоматичних журналів змін) і дає змогу людям класифікувати її одним поглядом.

Наш контекст: Для Emzett узгоджено власну угоду — кожна «пачка» змін отримує повідомлення коміту в цьому форматі німецькою мовою, плюс додатковий розділ «чому» з обґрунтуванням рішення.

Подробиці

Повна структура

Окрім однорядкового заголовка, повна специфікація знає необов’язкове тіло (докладніше пояснення, зазвичай відокремлене порожнім рядком) і необов’язкові «нижні колонтитули» (footers) для структурованої додаткової інформації — наприклад, BREAKING CHANGE: ... для змін, що зачіпають наявних користувачів кодової бази, або Closes #123 для автоматичного зв’язування коміту із завданням (issue). ! одразу після типу/області (feat(api)!: ...) також позначає несумісну зміну як скорочення докладного footer.

feat(shop)!: switch cart API to new response format
Old clients expecting the previous format break with this
update - only affects internal consumers of the API, no external ones.
BREAKING CHANGE: /api/cart now returns { items: [...] } instead of a
raw array.
Closes #142

Автоматизація завдяки машинозчитній структурі

Справжня практична користь виявляється з інструментами, які автоматично оцінюють цю структуру: semantic-release та подібні інструменти можуть виводити наступний номер версії за семантичним версіонуванням прямо з історії комітів — коміт feat підвищує мінорну версію, коміт із BREAKING CHANGE — мажорну, fix — лише патч-версію — і одразу генерувати з цього читабельний журнал змін, без потреби комусь вручну записувати, що змінилося в якій версії. Однак це надійно працює, лише якщо СПРАВДІ кожен коміт у репозиторії дотримується угоди — навіть один коміт без правильного префікса може порушити автоматичну оцінку або призвести до неправильно розрахованого номера версії.

Інші поширені типи

Окрім основних типів (feat, fix, refactor, chore, perf), на практиці закріпилися й інші угоди, хоча вони не входять до офіційної специфікації: docs (лише зміни документації), test (додавання/зміна тестів без зміни виробничого коду), style (суто косметичні зміни на кшталт форматування, без зміни поведінки) і build/ci (зміни конфігурації збірки або конвеєрів безперервної інтеграції). Область у дужках необов’язкова, але корисна, щоб одним поглядом бачити, яка частина кодової бази зачеплена, не читаючи весь diff — у великих проєктах із чітко розділеними модулями (наприклад, shop, chat, auth) це робить історію комітів набагато зручнішою для пошуку.

Межі угоди

Conventional Commits забезпечує структуру, але не якість — технічно правильно оформлений коміт (fix(shop): fixed bug) усе одно може не казати нічого по суті, якщо бракує справжньої причини чи обґрунтування. Тому багато команд доповнюють чисту структуру тип/область обов’язком коротко пояснити в тілі «чому» (а не лише «що», яке й так можна прочитати з diff) — у довгостроковій перспективі повідомлення комітів часто єдине місце, де лишаються задокументованими мотиви рішення.

Див. також: Next.js App Router, Git