Соглашение о коммитах. Спецификация

https://www.conventionalcommits.org/ru/v1.0.0/#спецификация

Что это?

Соглашение о коммитах призвано стандартизировать описание коммитов. По сути это стандарт который создан для структурирования данных коммитов.

Зачем использовать «Conventional Commits»

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

Как использовать

Для использования стандарта можно поставить плагин Conventional Commit он предложит форму для заполнения, после чего отформатирует введенные данные в виде коммита, это поможет избежать ошибок в начале работы. Так же можно использовать этот стандарт просто придерживаясь определенного форматирования описания коммита.

Шпаргалка

feat используется для описания добавления новой функциональности в проект.

fix описывает исправление ошибок в коде.

docs используется для изменений, связанных с документацией проекта.

style описывает изменения, не затрагивающие функциональность кода, а связанные с его стилем или форматированием.

refactor используется для описания изменений, которые не затрагивают функциональность кода, но улучшают его качество или структуру.

test описывает изменения, связанные с тестированием кода.

chore используется для изменений, которые не связаны с добавлением новой функциональности, исправлением ошибок, тестированием или документацией. Это могут быть, например, обновление зависимостей, изменения в настройках проекта и т.д.

Эти типы коммитов в сочетании с описанием изменений и scope (необязательный параметр, указывающий область изменений) позволяют лучше организовать работу над проектом и облегчают его сопровождение.

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

Слова «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 при использовании в качестве токена в сноске.