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

Простое соглашение о том, как нужно писать сообщения коммитов

Главное Спецификация GitHub

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

Главное

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

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

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

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

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

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

  1. fix: коммит типа fix исправляет баг в вашем коде (соответствует PATCH в Cемантическом Версионировании).
  2. feat: коммит типа feat добавляет новую функцию в ваш код (соответствует MINOR в Cемантическом Версионировании).
  3. BREAKING CHANGE: коммит, который имеет сноску BREAKING CHANGE или коммит, заканчивающийся восклицательным знаком (!) после типа или контекста, вводящий изменение(я), нарушающие обратную совместимость (соответствует MAJOR в Cемантическом Версионировании). BREAKING CHANGE может быть частью коммита любого типа.
  4. Другие типы коммитов разрешены. Например, @commitlint/config-conventional (основан на соглашении Angular) рекомендует build, chore, ci, docs, style, refactor, perf, test и другие.
  5. Другие сноски коммитов могут быть аналогичны соглашению 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.

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

Зачем использовать «Соглашение о коммитах»

FAQ (часто задаваемые вопросы)

Как мне поступать с сообщениями коммитов на начальном этапе разработки?

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

Типы в заголовке коммита должны быть прописными или строчными?

Выберите тот, который больше всего вам нравится, и строго ему следуйте.

Что мне делать, если коммит соответствует более чем одному типу?

По возможности вернитесь назад и сделайте несколько коммитов. Часть преимущества «Соглашения о коммитах» - его способность побуждать нас делать более организованные коммиты и PRs (pull requests, или запросы на вытягивание).

Разве это не препятствует интенсивной разработке и быстрой итерации?

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

Может ли «Соглашение о коммитах» привести разработчиков к ограничению типов совершаемых ими коммитов, потому что они будут думать в соответствии с предоставленными типами?

«Соглашение о коммитах» побуждает нас делать больше определённых типов коммитов, таких, как fix. Помимо этого, гибкость «Соглашения о коммитах» позволяет вашей команде придумывать свои собственные типы и со временем изменять их.

Как это связано с Семантическим Версионированием?

Коммиты типа fix должны быть переведены в выпуски PATCH, feat — в MINOR, BREAKING CHANGE, независимо от типа, — в MAJOR.

Как мне довести свои расширения до спецификации «Соглашение о коммитах». Например, @jameswomack/standard-commit-spec?

Мы рекомендуем использовать Семантическое Версионирование для выпуска ваших собственных расширений для этой спецификации (и призываем вас создавать эти расширения!).

Что мне делать, если я случайно использовал неправильный тип коммита?

Когда вы использовали неправильный тип, но соответствующий спецификации. Например, fix вместо feat

Перед объединением или выпуском ошибки мы рекомендуем использовать git rebase -i для редактирования истории коммитов. После выпуска редактирование будет отличаться в зависимости от того, какие инструменты и процессы вы используете.

Когда вы использовали тип, не указанный в спецификации. Например, feet вместо feat

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

Все ли мои участники должны использовать спецификацию «Соглашения о коммитах»?

Нет! Если вы используете рабочий процесс на основе соединения (squash) коммитов в Git, то ведущие специалисты по сопровождению могут приводить в порядок сообщения коммитов по мере их слияния (merge), не добавляя нагрузки для обычных коммиттеров. Обычный рабочий процесс для этого состоит в том, чтобы ваша система Git автоматически соединяла коммиты из PR и представляла форму для ведущего сопровождающего, чтобы ввести более подходящее сообщение коммита для слияния.

Как «Соглашение о коммитах» обрабатывает отмену коммитов?

Отмена изменений кода может быть сложной:

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

Одна из рекомендаций — использовать тип revert и сноску, которая ссылается на отменяемые хэш-суммы коммитов. Например:

revert: let us never again speak of the noodle incident

Refs: 676104e, a215868