mirror of
https://github.com/conventional-commits/conventionalcommits.org.git
synced 2024-11-15 10:55:16 +01:00
230 lines
19 KiB
Markdown
230 lines
19 KiB
Markdown
---
|
||
draft: false
|
||
aliases: ["/ru/"]
|
||
---
|
||
|
||
# Conventional Commits 1.0.0-beta.4
|
||
|
||
## Главное
|
||
|
||
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`.
|
||
|
||
## Примеры
|
||
|
||
### Сообщение 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'a с не обязательным `!`, для того, чтобы привлечь внимание к изменениям, нарушающим обратную совместимость
|
||
```
|
||
chore!: drop Node 6 from testing matrix
|
||
|
||
BREAKING CHANGE: dropping Node 6 which hits end of life in April
|
||
```
|
||
|
||
### Сообщение 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
|
||
```
|
||
|
||
## Спецификация
|
||
|
||
Слова “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'а.
|
||
Он должен быть отделен от тела commit'а одной пустой строкой. Подвал должен (MUST)
|
||
содержать мета-информацию о commit'е. Например, связанные pull-request'ы, обсуждения,
|
||
изменения, нарушающие обратную совместимость. По одной мета-информации на строку.
|
||
1. Изменения, нарушающие обратную совместимость (breaking changes), должны (MUST) быть
|
||
указаны в самом начале тела (body) или в начале одной из строк подвала (footer).
|
||
Изменения, нарушающие обратную совместимость, должны (MUST) начинаться с текста,
|
||
написанного прописными буквами, BREAKING CHANGE, за которым должны следовать двоеточие и пробел.
|
||
1. Описание изменений, нарушающий обратную совместимость, должно (MUST) следовать после
|
||
`BREAKING CHANGE: `. В нем должно содержаться то, что изменилось в API. Например,
|
||
_BREAKING CHANGE: environment variables now take precedence over config files._
|
||
1. Типы отличные от `feat` и `fix` могут (MAY) быть использованы в ваших commit'ах.
|
||
1. Единицы информации, которые составляют обычные commit'ы, не должны (MUST NOT)
|
||
трактоваться разработчиками как регистрозависимые, за исключением BREAKING CHANGE,
|
||
который всегда должен быть написан прописными буквами.
|
||
1. Знак `!` может (MAY) быть добавлен перед `:` в тип/контекст, чтоб обратить внимание
|
||
на изменения. Строка `BREAKING CHANGE: description` должна (MUST) быть добавлена в
|
||
тело (body) или подвал (footer), если используется `!` в префиксе.
|
||
|
||
## Почему нужно использовать 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'а.
|
||
|
||
## О спецификации
|
||
|
||
Conventional Commits вдохновлены и основаны на
|
||
[Angular Commit Guidelines](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines).
|
||
|
||
Первый черновик спецификации был написан в сотрудничестве с некоторыми участниками:
|
||
|
||
* [conventional-changelog](https://github.com/conventional-changelog/conventional-changelog): набор утилит для парсинга
|
||
стандартных сообщений commit'ов из истории git.
|
||
* [bumped](https://bumped.github.io): утилита для релиза приложений, которая позволяет легко выполнять действия
|
||
до и после релиза новой версии ваших приложений.
|
||
* [unleash](https://github.com/netflix/unleash): утилита для автоматического релиза и публикации приложений.
|
||
* [lerna](https://github.com/lerna/lerna): утилита для управления моно-репозиториями, которая выросла из проекта Babel.
|
||
|
||
## Утилиты для Conventional Commits
|
||
|
||
* [php-commitizen](https://github.com/damianopetrungaro/php-commitizen): утилита для создания сообщений commit'ов, следующих Conventional Commits спецификации.
|
||
Используется для PHP-проектов, как зависимость composer, или глобально для не PHP-проектов.
|
||
* [conform](https://github.com/autonomy/conform): утилита, которая может быть использована для реализации политик в git-репозиториях, включая правила написания commit'ов.
|
||
* [standard-version](https://github.com/conventional-changelog/standard-version): утилита, для автоматического контроля версий и CHANGELOG'ов,
|
||
использующая новую кнопку `Squash` GitHub'а. Рекомендует использовать Conventional Commits в рабочем процессе.
|
||
|
||
## Проекты, использующие Conventional Commits
|
||
|
||
* [yargs](https://github.com/yargs/yargs): всеми любимый парсер параметров командной строки.
|
||
* [istanbuljs](https://github.com/istanbuljs/istanbuljs): коллекция утилит и библиотек с открытым исходным кодом для оценки покрытия
|
||
тестами вашего кода.
|
||
* [uPortal-home](https://github.com/UW-Madison-DoIT/angularjs-portal) и [uPortal-application-framework](https://github.com/UW-Madison-DoIT/uw-frame):
|
||
новый дополнительный пользовательский интерфейс [Apereo uPortal](https://www.apereo.org/projects/uportal).
|
||
* [massive.js](https://github.com/dmfay/massive-js): библиотека для доступа к данным PostrgeSQL для Node.
|
||
* [electron](https://github.com/electron/electron): утилита для создания крос-платформенных приложений на JavaScript, HTM и CSS.
|
||
* [scroll-utility](https://github.com/LeDDGroup/scroll-utility): простая в использовании утилита контроля прокрутки центральных
|
||
элементов и плавной анимации.
|
||
* [Blaze UI](https://github.com/BlazeUI/blaze): независимы от фреймворктов набор UI.
|
||
* [Monica](https://github.com/monicahq/monica): свободный менеджер персональных связей.
|
||
* [mhy](https://mhy.js.org): набор инструментов и окружение для разработки с нулевой конфигурацией, которые работают из коробки.
|
||
* [sharec](https://github.com/lamartire/sharec): минималистичный инструмент для скаффолдинга и версионирования конфигурации.
|
||
|
||
[](https://conventionalcommits.org)
|
||
|
||
_Хотите, чтоб ваш проект появился в этом списке?_ [Отправьте Pull Request](https://github.com/conventional-changelog/conventionalcommits.org/pulls).
|