Главное
Спецификация «Соглашение о коммитах» — простое соглашение о том, как нужно писать сообщения коммитов. Оно описывает простой набор правил для создания понятной истории коммитов, а также позволяет проще разрабатывать инструменты автоматизации, основанные на истории коммитов. Данное соглашение совместимо с Семантическим Версионированием, описывая новые функции, исправления и изменения, нарушающие обратную совместимость в сообщениях коммитов.
Сообщения коммитов должны быть следующей структуры:
<тип>[необязательный контекст]: <описание>
[необязательное тело]
[необязательная(ые) сноска(и)]
Коммит содержит следующие структурные элементы для передачи намерений пользователям вашей библиотеки:
- fix: коммит типа
fixисправляет баг в вашем коде (соответствуетPATCHв Cемантическом Версионировании). - feat: коммит типа
featдобавляет новую функцию в ваш код (соответствуетMINORв Cемантическом Версионировании). - BREAKING CHANGE: коммит, который имеет сноску
BREAKING CHANGEили коммит, заканчивающийся восклицательным знаком (!) после типа или контекста, вводящий изменение(я), нарушающие обратную совместимость (соответствуетMAJORв Cемантическом Версионировании).BREAKING CHANGEможет быть частью коммита любого типа. - Другие типы коммитов разрешены. Например, @commitlint/config-conventional (основан на соглашении Angular) рекомендует
build,chore,ci,docs,style,refactor,perf,testи другие. - Другие сноски коммитов могут быть аналогичны соглашению git trailer format.
Дополнительные типы не требуются «Соглашению о коммитах» и не имеют неявного эффекта в семантическом версионировании (если только они не включают BREAKING CHANGE). Контекст может быть добавлен к типу коммита, чтобы предоставить дополнительную контекстную информацию; она содержится в скобках. Например, feat(parser): add ability to parse arrays.
Примеры
Сообщение коммита с описанием и сноской 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.
- Коммиты должны (MUST) начинается с типа, который является существительным:
feat,fixи т.д. За ним следует необязательный (OPTIONAL) контекст, необязательный (OPTIONAL) восклицательный знак (!) и обязательные (REQUIRED) двоеточие (:) и пробел ( ). - Тип
featдолжен (MUST) использоваться, когда коммит добавляет новый функционал в ваше приложение или вашу библиотеку. - Тип
fixдолжен (MUST) использоваться, когда коммит исправляет баг в вашем приложении или вашей библиотеке. - Контекст может (MAY) следовать после типа. Контекст должен (MUST) быть существительным, заключённым в круглые скобки, описывающий часть кодовой базы, которую затронул коммит. Например,
fix(parser). - Описание должно (MUST) следовать сразу за двоеточием (
:) и пробелом ( ) после типа или контекста. Описание представляет собой краткое изложение изменений кода. Например,fix: array parsing issue when multiple spaces were contained in string. - Тело коммита может (MAY) следовать после короткого описания, добавляя дополнительную контекстную информацию об изменениях в коде. Тело должно (MUST) отделяться от описания одной пустой строкой.
- Тело коммита имеет произвольную форму и может (MAY) состоять из любого количества абзацев, разделённых новой строкой.
- В одной или нескольких сносках может (MAY) быть одна пустая строка после тела. Каждая сноска должна (MUST) состоять из токена слова, за которым следует разделитель
:<пробел>или<пробел>#, за которым следует строковое значение (основано на git trailer format). - Токен сноски должен (MUST) использовать
-вместо пробельных символов. Например,Acked-by(это помогает отличить раздел сноски от его тела, состоящего из нескольких абзацев). Исключение составляетBREAKING CHANGE, которое может (MAY) также использоваться как токен. - Сноска может (MAY) содержать пробелы и символы новой строки, а считывание должно (MUST) завершаться при обнаружении следующей допустимой пары токен-разделитель сноски.
- Критические изменения должны (MUST) быть указаны в типе, контексте или сноске коммита.
- Если
BREAKING CHANGEвключено в сноску, то оно должно (MUST) состоять из прописного текстаBREAKING CHANGE, за которым следует двоеточие (:), пробел ( ) и описание. Например,BREAKING CHANGE: environment variables now take precedence over config files. - Если критические изменения находятся в типе или контексте, то они должны (MUST) быть обозначены восклицательным знаком (
!), непосредственно перед двоеточием (:). Если используется восклицательный знак (!), тоBREAKING CHANGEможет (MAY) быть опущен в сноске, а описание коммита должно (SHALL) использоваться для описания критического изменения. - В ваших сообщениях коммитов могут (MAY) использоваться типы, отличные от
featиfix. Например,docs: updated ref docs. - Единицы информации, которые составляют «Соглашение о коммитах», не должны (MUST NOT) обрабатываться разработчиками как чувствительные к регистру, за исключением
BREAKING CHANGE, которое должно (MUST) быть прописными. BREAKING-CHANGEдолжен (MUST) быть синонимомBREAKING CHANGEпри использовании в качестве токена в сноске.
Зачем использовать «Соглашение о коммитах»
- Автоматическое создание списков изменения.
- Автоматическое определение семантического повышения версии (на основе типов совершённых коммитов).
- Информирование товарищей по команде, общественности и других заинтересованных сторон о характере изменений.
- Запуск процессов сборки и публикации.
- Упрощать людям участие в ваших проектах, позволив им изучить более структурированную историю коммитов.