Общепринятые Коммиты 1.0.0-beta.2

Главное

Как разработчики приложений с открытым исходным кодом, использующие слияние (squash) git’а в ветку master должны писать общепринятые сообщения коммитов.

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

<type>[optional область]: <краткое описание>

[optional тело]

[optional подвал]

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

fix: - коммит типа fix, который исправляет баги в вашем коде (он соотносится с PATCH в правилах семантического управления версиями).
feat: - коммит type feat, который добавляет новую функциональность в ваш код (он соотносится с MINOR в правилах семантического управления версиями).
BREAKING CHANGE: - коммит, который содержит текст BREAKING CHANGE: в начале своего необязательного тела или подвала, и несет в себе описание нарушений обратной совместимости в API (он соотносится с MAJOR в правилах семантического управления версиями). BREAKING CHANGE может быть частью коммита любого типа.
Другие: коммиты, отличные от fix: и feat: так же разрешены, например, commitlint-config-conventional (основанный на the Angular convention) рекомендует chore:, docs:, style:, refactor:, perf:, test: и другие. Мы так же рекомендуем improvement для коммитов, которые улучшают текущую реализацию без добавления новой функциональности или исправления ошибок. Обратите внимание, что данный тип коммитов не управляется данной спецификацией и не имеет никакого соотношения в правилах семантического управления версиями (за исключением случае, если он не содержит в себе BREAKING CHANGE). Область (scope) может быть определена для любого типа коммита, чтоб описать контекст коммита. Она содержится в круглых скобках, например, feat(parser): add ability to parse arrays.

Примеры

Коммит, добавляющий новую функциональность и содержащий описание нарушения обратной совместимости в теле

feat: allow provided config object to extend other configs

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

Коммит без тела

docs: correct spelling of CHANGELOG

Коммит с указанной областью (scope)

feat(lang): added polish language

Коммит, исправляющий баги и содержащий (необязательный) номер в баг-трекере (issue) в подвале

fix: minor typos in code

see the issue for details on the typos fixed

fixes issue #12

Вступление

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

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

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

Внедряя это соглашение, мы создаем общий язык, который упрощает отладку между проектами.

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

Слова “ДОЛЖЕН”, “ДОЛЖНО”, “ДОЛЖНЫ” (“MUST”, “SHOULD”, “SHALL”), “МОГУТ”, “МОЖЕТ” (“MAY”) и “НЕ ОБЯЗАТЕЛЬНАЯ” (“OPTIONAL”) в этом документе должны интерпретироваться как описано в RFC 2119.

Коммиты ДОЛЖНЫ начинаться с префикса, который содержит существительное feat, fix и др., за которым следует двоеточие и пробел.
Тип feat ДОЛЖЕН использоваться для коммитов, которые добавляют новую функциональность в ваше приложение или библиотеку.
Тип fix ДОЛЖЕН использоваться для коммитов, которые исправляют баги в вашем приложении или библиотеки.
НЕ ОБЯЗАТЕЛЬНАЯ область (scope) МОЖЕТ быть указана после типа. Область - это фраза, описывающая контекст кодовой базы, измененной коммитом, заключенная в круглые скобки. Например, fix(parser):.
Краткое описания ДОЛЖНО следовать сразу же после указания префикса типа/области. Краткое описание - это сжатое описание изменения кода, которое несет в себе коммит, например, fix: array parsing issue when multiple spaces were contained in string.
Тело коммита содержит в себе дополнительное, полное описание о изменении кодовой базы. Оно МОЖЕТ следовать после краткого описания. Тело ДОЛЖНО идти после краткого описания, через одну пустую строку.
Подвал МОЖЕТ идти после тела коммита через одну пустую строку. Подвал ДОЛЖЕН содержать дополнительную ссылку на запись в баг-трекере (issue) об изменениях в кодовой базы (т.е. issue, которое он исправляет, например Fixes #13).
Нарушения обратной совместимости ДОЛЖНЫ содержаться в самом начале тела или подвала коммита. Нарушения обратной совместимости ДОЛЖНЫ начинаться с текста в верхнем регистре BREAKING CHANGE, за которым следует двоеточие и пробел.
Описание нарушения обратной совместимости ДОЛЖНО следовать сразу же после BREAKING CHANGE: . Оно должно разъяснять, что изменилось в API. Например, BREAKING CHANGE: environment variables now take precedence over config files.
Подвал ДОЛЖЕН содержать только BREAKING CHANGE, внешние ссылки, ссылки на номера задач в баг-трекере (issue), и другую мета-информацию.
Типы отличные от feat и fix МОГУТ использоваться в сообщениях коммитов.

Почему нужно использовать Общепринятые Коммиты

Автоматически создаваемые CHANGELOG’и.
Автоматически определяемая семантическая версия приложения или библиотеки (основываясь на типах коммитов).
Коммуникация о характере изменения между товарищами по команде, общественностью и другими заинтересованными сторонами.
Автоматически срабатываемый процесс сборки и публикации.
Людям проще участвовать в вашем проекте, потому что им доступна более структурированная история коммитов.

FAQ

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

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

В каком регистре я должен писать заголовки коммитов?

Любой регистр можно использовать, но лучше во всей истории использовать один стиль.

Что мне делать, если коммит должен содержать больше одного типа?

Вернитесь назад и сделайте несколько коммитов, если это возможно. Часть из преимуществ использования Общепринятых Коммитов

это его способность побуждать делать более организованные коммиты и PR’ы.

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

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

Могут ли Общепринятые Коммиты заставить разработчиков ограничивать их типы коммитов, потому что им придется думать об этих типах?

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

Как она связывается с правилами семантического управления версиями SemVer?

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

Как я должен версионировать мои расширения к спецификации Общепринятых Коммитов, например, `@jameswomack/conventional-commit-spec`?

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

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

Что если вы использовали тип, который имеет спецификацию, но это неправильный тип. Например, `fix` вместо `feat`

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

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

Это не конец света, это просто обозначает, что коммит будет упущен при работе утилит, основанных на спецификации.

Должны ли все мои соавторы использовать спецификацию Conventional Commit?

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

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