Соглашения о коммитах:

---

25 мая 2024

Оглавление:

• Примеры
• Спецификация

Причины использования соглашения о коммитах:

• Автоматическая генерация чейнджлогов.
• Автоматическое определение семантического повышения версии (на основе типов совершенных коммитов).
• Информирование товарищей по команде, сообщества и других заинтересованных сторон о характере изменений.
• Запуск процессов сборки и публикации по триггерам.
• Возможность упростить людям участие в ваших проектах, позволив им изучить более структурированную историю коммитов.

Сообщения коммитов должны быть следующей структуры:

<тип>[необязательный контекст]: <описание>

[необязательное тело]

[необязательная(ые) сноска(и)]

Коммит содержит следующие структурные элементы для передачи намерений пользователям вашей библиотеки:

• fix : коммит типа fix исправляет баг в вашем коде (соответствует PATCH в Cемантическом Версионировании).
• feat : коммит типа feat добавляет новую функцию в ваш код (соответствует MINOR в Cемантическом Версионировании).
• BREAKING CHANGE : коммит, который имеет сноску BREAKING CHANGE или коммит, заканчивающийся восклицательным знаком (!) после типа или контекста, вводящий изменение(я), нарушающие обратную совместимость (соответствует MAJOR в Cемантическом Версионировании). BREAKING CHANGE может быть частью коммита любого типа.

Разрешены другие типы коммитов:

• build : сборка проекта или изменения внешних зависимостей
• chore : обновление рутинных задач и т. д.; без изменения производственного кода
• ci : настройка CI и работа со скриптами
• docs : изменения в документации
• style : форматирование, отсутствующие точки с запятой и т. д .; без изменения производственного кода
• refactor : рефакторинг производственного кода, например, переименование переменной
• perf : изменения направленные на улучшение производительности
• revert : откат на предыдущие коммиты
• test : добавление недостающих тестов, рефакторинг тестов; без изменения производственного кода

Примеры:

Сообщение коммита с описанием и сноской BREAKING CHANGE:

feat: allow provided config object to extend other configs

BREAKING CHANGE: `extends` key in config file is now used for extending other config files

Сообщение коммита с ! для привлечения внимания к BREAKING CHANGE:

feat!: send an email to the customer when a product is shipped

Сообщение коммита с контекстом и ! для привлечения внимания к BREAKING CHANGE:

feat(api)!: send an email to the customer when a product is shipped

Сообщение коммита вместе с ! и сноской BREAKING CHANGE:

chore!: drop support for Node 6

BREAKING CHANGE: use JavaScript features not available in Node 6.

Сообщение коммита без тела:

docs: correct spelling of CHANGELOG

Сообщение коммита с контекстом:

feat(lang): add polish language

Сообщение коммита с телом из нескольких абзацев и несколькими сносками:

fix: prevent racing of requests

Introduce a request id and a reference to latest request. Dismiss
incoming responses other than from latest request.

Remove timeouts which were used to mitigate the racing issue but are
obsolete now.

Reviewed-by: Z
Refs: #123

Спецификация:

Слова «MUST», «MUST NOT», «REQUIRED», «SHALL», «MAY» и «OPTIONAL» в данном документе должны интерпретироваться как в RFC 2119.

1. Коммиты должны (MUST) начинается с типа, который является существительным: feat, fix и т.д. За ним следует необязательный (OPTIONAL) контекст, необязательный (OPTIONAL) восклицательный знак (!) и обязательные (REQUIRED) двоеточие (:) и пробел ( ).
2. Тип feat должен (MUST) использоваться, когда коммит добавляет новый функционал в ваше приложение или вашу библиотеку.
3. Тип fix должен (MUST) использоваться, когда коммит исправляет баг в вашем приложении или вашей библиотеке.
4. Контекст может (MAY) следовать после типа. Контекст должен (MUST) быть существительным, заключённым в круглые скобки, описывающий часть кодовой базы, которую затронул коммит. Например, fix(parser).
5. Описание должно (MUST) следовать сразу за двоеточием (:) и пробелом ( ) после типа или контекста. Описание представляет собой краткое изложение изменений кода. Например, fix: array parsing issue when multiple spaces were contained in string.
6. Тело коммита может (MAY) следовать после короткого описания, добавляя дополнительную контекстную информацию об изменениях в коде. Тело должно (MUST) отделяться от описания одной пустой строкой.
7. Тело коммита имеет произвольную форму и может (MAY) состоять из любого количества абзацев, разделённых новой строкой.
8. В одной или нескольких сносках может (MAY) быть одна пустая строка после тела. Каждая сноска должна (MUST) состоять из токена слова, за которым следует разделитель :<пробел> или <пробел>#, за которым следует строковое значение (основано на git trailer format).
9. Токен сноски должен (MUST) использовать - вместо пробельных символов. Например, Acked-by (это помогает отличить раздел сноски от его тела, состоящего из нескольких абзацев). Исключение составляет BREAKING CHANGE, которое может (MAY) также использоваться как токен.
10. Сноска может (MAY) содержать пробелы и символы новой строки, а считывание должно (MUST) завершаться при обнаружении следующей допустимой пары токен-разделитель сноски.
11. Критические изменения должны (MUST) быть указаны в типе, контексте или сноске коммита.
12. Если BREAKING CHANGE включено в сноску, то оно должно (MUST) состоять из прописного текста BREAKING CHANGE, за которым следует двоеточие (:), пробел ( ) и описание. Например, BREAKING CHANGE: environment variables now take precedence over config files.
13. Если критические изменения находятся в типе или контексте, то они должны (MUST) быть обозначены восклицательным знаком (!), непосредственно перед двоеточием (:). Если используется восклицательный знак (!), то BREAKING CHANGE может (MAY) быть опущен в сноске, а описание коммита должно (SHALL) использоваться для описания критического изменения.
14. В ваших сообщениях коммитов могут (MAY) использоваться типы, отличные от feat и fix. Например, docs: updated ref docs.
15. Единицы информации, которые составляют «Соглашение о коммитах», не должны (MUST NOT) обрабатываться разработчиками как чувствительные к регистру, за исключением BREAKING CHANGE, которое должно (MUST) быть прописными.
16. BREAKING-CHANGE должен (MUST) быть синонимом BREAKING CHANGE при использовании в качестве токена в сноске.