mirror of
https://github.com/conventional-commits/conventionalcommits.org.git
synced 2024-11-15 02:45:15 +01:00
172 lines
14 KiB
Markdown
172 lines
14 KiB
Markdown
---
|
||
draft: false
|
||
aliases: ["/ru/"]
|
||
---
|
||
|
||
# Conventional Commits 1.0.0-beta.3
|
||
|
||
## Summary
|
||
|
||
Conventional Commits - это простое соглашение о том, как нужно писать сообщения commit'ов.
|
||
Оно описывает простой набор правил для создания понятной истории commit'ов,
|
||
а так же позволяет проще разрабатывать инструменты автоматизации, основанные на
|
||
истории commit'ов. Данное соглашение совместимо с [SemVer](http://semver.org),
|
||
описывая новые функции (features), исправления (fixes) и изменения, нарушающие
|
||
обратную совместимость (breaking changes) в сообщениях commit'ов.
|
||
|
||
Сообщения commit'ов должны быть следующей структуры:
|
||
|
||
---
|
||
|
||
```
|
||
<type>[optional scope]: <description>
|
||
|
||
[optional body]
|
||
|
||
[optional footer]
|
||
```
|
||
---
|
||
|
||
<br />
|
||
Commit'ы могут содержать следующие структурные элементы для сообщений пользователям
|
||
вашей библиотеки:
|
||
|
||
1. **fix:** commit _типа_ `fix` исправляет ошибку (bug) в вашем коде
|
||
(он соответствует [`PATCH`](http://semver.org/#summary) в SemVer)
|
||
1. **feat:** commit _типа_ `feat` добавляет новую функцию (feature) в ваш код
|
||
(он соответствует [`MINOR`](http://semver.org/#summary) в SemVer).
|
||
1. **BREAKING CHANGE:** commit, который содержит текст `BREAKING CHANGE:`
|
||
в начале своего не обязательного тела сообщения (body) или в подвале (footer),
|
||
добавляет изменения, нарушающие обратную совместимость вашего API
|
||
(он соответствует [`MAJOR`](http://semver.org/#summary) в SemVer).
|
||
BREAKING CHANGE может быть частью commit'а любого _типа_.
|
||
1. Другое: commit'ы с _типами_, которые отличаются от `fix:` и `feat:`,
|
||
так же разрешены. Например, [@commitlint/config-conventional](https://github.com/conventional-changelog/commitlint/tree/master/%40commitlint/config-conventional)
|
||
(основанный на [The Angular convention](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines))
|
||
рекомендует: `chore:`, `docs:`, `style:`, `refactor:`, `perf:`, `test:`, и другие.
|
||
|
||
Мы так же рекомендуем `improvement` для commit'ов, которые вносят улучшения в текущую
|
||
реализацию без добавления новых функций и исправления ошибок. Обратите внимание, что
|
||
данный тип не описывается данной спецификацией и не имеет эффекта в SemVer
|
||
(за исключением, когда он включает BREAKING CHANGE).
|
||
<br />
|
||
Контекст (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](https://www.ietf.org/rfc/rfc2119.txt).
|
||
|
||
1. Commit'ы должны (MUST) начинаться с типа, который является существительным: `feat`, `fix`, и т.д.,
|
||
за которым следуют не обязательное (OPTIONAL) указание контекста (scope), двоеточие и пробел.
|
||
1. Тип `feat` должен (MUST) использоваться, когда commit добавляет новый функционал (feature) в
|
||
ваше приложение или библиотеку.
|
||
1. Тип `fix` должен (MUST) использоваться, когда commit исправляет ошибку (fix)
|
||
в вашем приложении или библиотеки.
|
||
1. Контекст (scope) может (MAY) следовать после типа. Контекст
|
||
должен (MUST) быть существительным, заключенным в круглые скобки, описывающий
|
||
часть кодовой базы, которую затронул commit. Например, `fix(parser):`.
|
||
1. Описание должно (MUST) следовать через пробел сразу же после типа/контекста.
|
||
Описание - это краткая выжимка об изменениях кода, например, _fix: array parsing issue when multiple spaces were contained in string._
|
||
1. Тело (body) commit'а может (MAY) следовать после короткого описания,
|
||
добавляя дополнительную информацию об изменениях в коде. Тело должно (MUST) отделяться
|
||
от короткого описания одной пустой строкой.
|
||
1. Подвал (footer) может (MAY) быть добавлен и отделен от тела commit'а пустой строкой.
|
||
Подвал должен (SHOULD) содержать упоминания, касающиехся изменений в коде (такие, как номера задач, которые были решение, т.е.,`Fixes #13`).
|
||
1. Описание изменений, нарушающий обратную совместимость, должно (MUST) нахожиться в самом начале подвала (footer) или тела сообщения commit'a.
|
||
Описание изменений, нарушающий обратную совместимость, должно (MUST) состоять из текста `BREAKING CHANGE`, пробела и двоеточия.
|
||
1. Описание изменений, нарушающий обратную совместимость должно включаьб то, что изменилось в API. Например,
|
||
_BREAKING CHANGE: environment variables now take precedence over config files._
|
||
1. Подвал (footer) должен (MUST) включать только внешние ссылки, номера задач (issue) и прочу мета-информацию,
|
||
которая относиться к изменениям, нарушающим обратную совместимость (BREAKING CHANGE).
|
||
1. Типы отличные от `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](http://semver.org)?
|
||
|
||
`fix` тип commit'а должен быть отражен в `PATCH`-релизе. `feat` тип commit'а должен быть отражен в `MINOR`-релизе.
|
||
Commit'ы с `BREAKING CHANGE` в теле или подвале, не зависимо от типа, должны быть отражены в `MAJOR`-релизе.
|
||
|
||
### Как я должен версионировать мои расширения к спецификации Conventional Commits, например, `@jameswomack/conventional-commit-spec`?
|
||
|
||
Мы рекомендуем использовать [SemVer](http://semver.org) для релизов ваших расширений к этой спецификации (и рекомендуем делать эти расширения!).
|
||
|
||
### Что мне делать, если я случайно использовал не тот тип commit'а?
|
||
|
||
#### Что если вы использовали тип, который имеет спецификацию, но это неправильный тип. Например, `fix` вместо `feat`
|
||
|
||
Перед слиянием или релизом ошибки, мы рекомендуем использовать `git rebase -i` для редактирования истории commit'ов. После
|
||
`release`, исправления будут отличаться в зависимости от того, какие инструменты вы используете.
|
||
|
||
#### Когда вы использовали тип, *не* описанный спецификацией, например, `feet` вместо `feat`
|
||
|
||
Это не конец света, это просто обозначает, что коммит будет упущен при работе утилит, основанных на спецификации.
|
||
|
||
### Должны ли все мои соавторы использовать спецификацию Conventional Commit?
|
||
|
||
Нет! Если ваш рабочий процесс основа на использовании слияния (squash) Git, сопровождающий проекта может отчистить
|
||
историю всех предыдущих commit'ов при их слияния, не добавляя рабочей нагрузки на случайные commit'ы. Обычно,
|
||
рабочий процесс строится на том, что ваша система Git автоматически объединяет (squash) все предыдущие commit'ы пред
|
||
перед pull-запросом и предоставляет форму сопровождающему проекта для ввода нового commit'а.
|