conventionalcommits.org/content/v1.0.0-beta.3/index.ru.md

draft	aliases
false	/ru/

Conventional Commits 1.0.0-beta.3

Summary

Conventional Commits - это простое соглашение о том, как нужно писать сообщения commit'ов. Оно описывает простой набор правил для создания понятной истории commit'ов, а так же позволяет проще разрабатывать инструменты автоматизации, основанные на истории commit'ов. Данное соглашение совместимо с SemVer, описывая новые функции (features), исправления (fixes) и изменения, нарушающие обратную совместимость (breaking changes) в сообщениях commit'ов.

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

---

<type>[optional scope]: <description>

[optional body]

[optional footer]

---

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

1. fix: commit типа fix исправляет ошибку (bug) в вашем коде (он соответствует PATCH в SemVer)
2. feat: commit типа feat добавляет новую функцию (feature) в ваш код (он соответствует MINOR в SemVer).
3. BREAKING CHANGE: commit, который содержит текст BREAKING CHANGE: в начале своего не обязательного тела сообщения (body) или в подвале (footer), добавляет изменения, нарушающие обратную совместимость вашего API (он соответствует MAJOR в SemVer). BREAKING CHANGE может быть частью commit'а любого типа.
4. Другое: commit'ы с типами, которые отличаются от fix: и feat:, так же разрешены. Например, @commitlint/config-conventional (основанный на The Angular convention) рекомендует: chore:, docs:, style:, refactor:, perf:, test:, и другие.

Мы так же рекомендуем improvement для commit'ов, которые вносят улучшения в текущую реализацию без добавления новых функций и исправления ошибок. Обратите внимание, что данный тип не описывается данной спецификацией и не имеет эффекта в SemVer (за исключением, когда он включает BREAKING CHANGE).
Контекст (scope) может быть объявлен рядом с типом commit'а для добавления дополнительной информации о контексте. Он должен содержаться в круглых скобках, например, feat(parser): add ability to parse arrays.

Examples

Сообщение commit'а с описанием и изменениям, нарушающим обратную совместимость, в теле

feat: allow provided config object to extend other configs

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

Сообщение commit'а без тела

docs: correct spelling of CHANGELOG

Сообщение commit'а с указанием контекста (scope)

feat(lang): add polish language

Сообщение commit'а, исправляющего ошибку (fix), использующее не обязательный номер задачи (issue) в багтрекере

fix: correct minor typos in code

see the issue for details on the typos fixed

closes issue #12

Specification

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

1. Commit'ы должны (MUST) начинаться с типа, который является существительным: feat, fix, и т.д., за которым следуют не обязательное (OPTIONAL) указание контекста (scope), двоеточие и пробел.
2. Тип feat должен (MUST) использоваться, когда commit добавляет новый функционал (feature) в ваше приложение или библиотеку.
3. Тип fix должен (MUST) использоваться, когда commit исправляет ошибку (fix) в вашем приложении или библиотеки.
4. Контекст (scope) может (MAY) следовать после типа. Контекст должен (MUST) быть существительным, заключенным в круглые скобки, описывающий часть кодовой базы, которую затронул commit. Например, fix(parser):.
5. Описание должно (MUST) следовать через пробел сразу же после типа/контекста. Описание - это краткая выжимка об изменениях кода, например, fix: array parsing issue when multiple spaces were contained in string.
6. Тело (body) commit'а может (MAY) следовать после короткого описания, добавляя дополнительную информацию об изменениях в коде. Тело должно (MUST) отделяться от короткого описания одной пустой строкой.
7. Подвал (footer) может (MAY) быть добавлен и отделен от тела commit'а пустой строкой. Подвал должен (SHOULD) содержать упоминания, касающиехся изменений в коде (такие, как номера задач, которые были решение, т.е.,Fixes #13).
8. Описание изменений, нарушающий обратную совместимость, должно (MUST) нахожиться в самом начале подвала (footer) или тела сообщения commit'a. Описание изменений, нарушающий обратную совместимость, должно (MUST) состоять из текста BREAKING CHANGE, пробела и двоеточия.
9. Описание изменений, нарушающий обратную совместимость должно включаьб то, что изменилось в API. Например, BREAKING CHANGE: environment variables now take precedence over config files.
10. Подвал (footer) должен (MUST) включать только внешние ссылки, номера задач (issue) и прочу мета-информацию, которая относиться к изменениям, нарушающим обратную совместимость (BREAKING CHANGE).
11. Типы отличные от feat и fix могут (MAY) быть использованы в ваших commit'ах.

Почему нужно использовать Conventional Commits

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

FAQ

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

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

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

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

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

Вернитесь назад и сделайте несколько commit'ов, если это возможно. Часть из преимуществ использования Conventional Commits - это его способность побуждать делать более организованные коммиты и PR'ы.

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

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

Могут ли Conventional Commits заставить разработчиков ограничивать их типы commit'ов, потому что им придется думать об этих типах?

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

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

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

Как я должен версионировать мои расширения к спецификации Conventional Commits, например, @jameswomack/conventional-commit-spec?

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

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

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

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

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

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

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

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