mirror of
https://github.com/conventional-commits/conventionalcommits.org.git
synced 2024-11-15 10:55:16 +01:00
179 lines
16 KiB
Markdown
179 lines
16 KiB
Markdown
---
|
||
draft: false
|
||
aliases: ["/ru/"]
|
||
---
|
||
|
||
# Общепринятые Коммиты 1.0.0-beta.2
|
||
|
||
## Главное
|
||
|
||
Как разработчики приложений с открытым исходным кодом, использующие слияние (squash) git'а в ветку `master` должны писать
|
||
общепринятые сообщения коммитов.
|
||
|
||
Сообщения коммитов должны иметь следующую структуру:
|
||
|
||
---
|
||
|
||
```
|
||
<type>[optional область]: <краткое описание>
|
||
|
||
[optional тело]
|
||
|
||
[optional подвал]
|
||
```
|
||
---
|
||
|
||
<br />
|
||
Коммиты включают следующие элементы, чтоб сообщить пользователям вашей библиотеки, что ни в себе содержат:
|
||
|
||
1. **fix:** - коммит _типа_ `fix`, который исправляет баги в вашем коде (он соотносится с [`PATCH`](http://semver.org/#summary)
|
||
в правилах семантического управления версиями).
|
||
1. **feat:** - коммит _type_ `feat`, который добавляет новую функциональность в ваш код (он соотносится с
|
||
[`MINOR`](http://semver.org/#summary) в правилах семантического управления версиями).
|
||
1. **BREAKING CHANGE:** - коммит, который содержит текст `BREAKING CHANGE:` в начале своего необязательного тела или подвала,
|
||
и несет в себе описание нарушений обратной совместимости в API (он соотносится с [`MAJOR`](http://semver.org/#summary)
|
||
в правилах семантического управления версиями).
|
||
BREAKING CHANGE может быть частью коммита любого _типа_.
|
||
1. Другие: коммиты, _отличные_ от `fix:` и `feat:` так же разрешены, например,
|
||
[commitlint-config-conventional](https://github.com/marionebl/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` для коммитов, которые улучшают текущую реализацию без добавления новой функциональности
|
||
или исправления ошибок. Обратите внимание, что данный тип коммитов не управляется данной спецификацией и не
|
||
имеет никакого соотношения в правилах семантического управления версиями (за исключением случае, если он не содержит в
|
||
себе BREAKING CHANGE).
|
||
<br />
|
||
Область (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](http://keepachangelog.com/en/0.3.0/)).
|
||
|
||
Общепринятые Коммиты - это простое соглашение для написания сообщений коммитов. Оно определяет простой
|
||
набор правил для создания точной истории коммитов, а так же упрощает написание автоматических утилит поверх истории коммитов.
|
||
Данное соглашение совместимо с правилами семантического управления версиями [SemVer](http://semver.org), описывая
|
||
правила добавления новой функциональности, исправления багов и описания нарушения обратной совместимости в сообщениях коммитов.
|
||
|
||
Внедряя это соглашение, мы создаем общий язык, который упрощает отладку между проектами.
|
||
|
||
## Спецификация
|
||
|
||
Слова “ДОЛЖЕН”, “ДОЛЖНО”, “ДОЛЖНЫ” (“MUST”, “SHOULD”, “SHALL”), “МОГУТ”, “МОЖЕТ” (“MAY”) и “НЕ ОБЯЗАТЕЛЬНАЯ” (“OPTIONAL”)
|
||
в этом документе должны интерпретироваться как описано в [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt).
|
||
|
||
1. Коммиты ДОЛЖНЫ начинаться с префикса, который содержит существительное `feat`, `fix` и др., за которым следует
|
||
двоеточие и пробел.
|
||
1. Тип `feat` ДОЛЖЕН использоваться для коммитов, которые добавляют новую функциональность в ваше приложение или библиотеку.
|
||
1. Тип `fix` ДОЛЖЕН использоваться для коммитов, которые исправляют баги в вашем приложении или библиотеки.
|
||
1. НЕ ОБЯЗАТЕЛЬНАЯ область (scope) МОЖЕТ быть указана после типа. Область - это фраза, описывающая контекст кодовой
|
||
базы, измененной коммитом, заключенная в круглые скобки. Например, `fix(parser):`.
|
||
1. Краткое описания ДОЛЖНО следовать сразу же после указания префикса типа/области. Краткое описание - это сжатое описание изменения
|
||
кода, которое несет в себе коммит, например, `fix: array parsing issue when multiple spaces were contained in string.`
|
||
1. Тело коммита содержит в себе дополнительное, полное описание о изменении кодовой базы. Оно МОЖЕТ следовать после краткого описания.
|
||
Тело ДОЛЖНО идти после краткого описания, через одну пустую строку.
|
||
1. Подвал МОЖЕТ идти после тела коммита через одну пустую строку. Подвал ДОЛЖЕН содержать дополнительную ссылку на
|
||
запись в баг-трекере (issue) об изменениях в кодовой базы (т.е. issue, которое он исправляет, например `Fixes #13`).
|
||
1. Нарушения обратной совместимости ДОЛЖНЫ содержаться в самом начале тела или подвала коммита. Нарушения обратной совместимости
|
||
ДОЛЖНЫ начинаться с текста в верхнем регистре `BREAKING CHANGE`, за которым следует двоеточие и пробел.
|
||
1. Описание нарушения обратной совместимости ДОЛЖНО следовать сразу же после `BREAKING CHANGE: `. Оно должно разъяснять,
|
||
что изменилось в API. Например, `BREAKING CHANGE: environment variables now take precedence over config files.`
|
||
1. Подвал ДОЛЖЕН содержать только `BREAKING CHANGE`, внешние ссылки, ссылки на номера задач в баг-трекере (issue), и
|
||
другую мета-информацию.
|
||
1. Типы отличные от `feat` и `fix` МОГУТ использоваться в сообщениях коммитов.
|
||
|
||
## Почему нужно использовать Общепринятые Коммиты
|
||
|
||
* Автоматически создаваемые CHANGELOG'и.
|
||
* Автоматически определяемая семантическая версия приложения или библиотеки (основываясь на типах коммитов).
|
||
* Коммуникация о характере изменения между товарищами по команде, общественностью и другими заинтересованными сторонами.
|
||
* Автоматически срабатываемый процесс сборки и публикации.
|
||
* Людям проще участвовать в вашем проекте, потому что им доступна более структурированная история коммитов.
|
||
|
||
## FAQ
|
||
|
||
### Как я должен писать сообщения коммитов на начальной стадии разработки?
|
||
|
||
Мы рекомендуем писать сообщения коммитов так, как будто вы уже выпустили продукт. Как правило, *кто-то*, например,
|
||
ваши коллеги, уже используют ваш код. И они хотят знать, что исправилось, что изменилось, какие нарушения обратной
|
||
совместимости появились и т.д.
|
||
|
||
### В каком регистре я должен писать заголовки коммитов?
|
||
|
||
Любой регистр можно использовать, но лучше во всей истории использовать один стиль.
|
||
|
||
### Что мне делать, если коммит должен содержать больше одного типа?
|
||
|
||
Вернитесь назад и сделайте несколько коммитов, если это возможно. Часть из преимуществ использования Общепринятых Коммитов
|
||
- это его способность побуждать делать более организованные коммиты и PR'ы.
|
||
|
||
### Разве это не препятствует быстрому развитию и быстрой интеграции?
|
||
|
||
Это препятствует быстрому развитию в неорганизованном виде. Это помогает быстро двигаться в нескольких проектах
|
||
с несколькими участниками.
|
||
|
||
### Могут ли Общепринятые Коммиты заставить разработчиков ограничивать их типы коммитов, потому что им придется думать об этих типах?
|
||
|
||
Общепринятые Коммиты побуждают делать больше коммитов с определенными типами, такими как `fix`. Кроме того, гибкость
|
||
Общепринятые Коммиты позволяют вашей команде создавать свои собственные типы и изменять их с течением времени.
|
||
|
||
### Как она связывается с правилами семантического управления версиями [SemVer](http://semver.org)?
|
||
|
||
`fix` тип коммита должен быть отражен в `PATCH`-релизе. `feat` тип коммита должен быть отражен в `MINOR`-релизе.
|
||
Коммиты с `BREAKING CHANGE` в теле или подвале, не зависимо от типа, должны быть отражены в `MAJOR`-релизе.
|
||
|
||
### Как я должен версионировать мои расширения к спецификации Общепринятых Коммитов, например, `@jameswomack/conventional-commit-spec`?
|
||
|
||
Мы рекомендуем использовать [SemVer](http://semver.org) для релизов ваших расширений к этой спецификации (и рекомендуем делать эти расширения!).
|
||
|
||
### Что мне делать, если я случайно использовал не тот тип коммита?
|
||
|
||
#### Что если вы использовали тип, который имеет спецификацию, но это неправильный тип. Например, `fix` вместо `feat`
|
||
|
||
Перед слиянием или релизом ошибки, мы рекомендуем использовать `git rebase -i` для редактирования истории коммитов. После
|
||
`release`, исправления будут отличаться в зависимости от того, какие инструменты вы используете.
|
||
|
||
#### Когда вы использовали тип, *не* описанный спецификацией, например, `feet` вместо `feat`
|
||
|
||
Это не конец света, это просто обозначает, что коммит будет упущен при работе утилит, основанных на спецификации.
|
||
|
||
### Должны ли все мои соавторы использовать спецификацию Conventional Commit?
|
||
|
||
Нет! Если ваш рабочий процесс основа на использовании слияния (squash) Git, сопровождающий проекта может отчистить
|
||
историю всех предыдущих коммитов при их слияния, не добавляя рабочей нагрузки на случайные коммиты. Обычно,
|
||
рабочий процесс строится на том, что ваша система Git автоматически объединяет (squash) все предыдущие коммиты пред
|
||
перед pull-запросом и предоставляет форму сопровождающему проекта для ввода нового коммита.
|