mirror of
https://github.com/conventional-commits/conventionalcommits.org.git
synced 2025-09-18 21:07:48 +02:00
docs(ru): format documentation for consistency
This commit is contained in:
Иванов Павел Романович
parent
9b8b992729
commit
ec7a65ff2f
@ -8,9 +8,9 @@ aliases: ["/ru/"]
|
|||||||
## Главное
|
## Главное
|
||||||
|
|
||||||
Спецификация «Соглашение о коммитах» — простое соглашение о том, как нужно
|
Спецификация «Соглашение о коммитах» — простое соглашение о том, как нужно
|
||||||
писать сообщения коммитов. Оно описывает простой набор правил для создания
|
писать сообщения коммитов. Оно описывает простой набор правил для создания
|
||||||
понятной истории коммитов, а также позволяет проще разрабатывать инструменты
|
понятной истории коммитов, а также позволяет проще разрабатывать инструменты
|
||||||
автоматизации, основанные на истории коммитов. Данное соглашение совместимо с
|
автоматизации, основанные на истории коммитов. Данное соглашение совместимо с
|
||||||
[Семантическим Версионированием](https://semver.org/lang/ru/), описывая новые функции, исправления и
|
[Семантическим Версионированием](https://semver.org/lang/ru/), описывая новые функции, исправления и
|
||||||
изменения, нарушающие обратную совместимость в сообщениях коммитов.
|
изменения, нарушающие обратную совместимость в сообщениях коммитов.
|
||||||
|
|
||||||
@ -25,6 +25,7 @@ aliases: ["/ru/"]
|
|||||||
|
|
||||||
[необязательная(ые) сноска(и)]
|
[необязательная(ые) сноска(и)]
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
<br />
|
<br />
|
||||||
@ -40,7 +41,7 @@ aliases: ["/ru/"]
|
|||||||
_контекста_, вводящий изменение(я), нарушающие обратную совместимость
|
_контекста_, вводящий изменение(я), нарушающие обратную совместимость
|
||||||
(соответствует [`MAJOR`](https://semver.org/lang/ru/#%D0%BA%D1%80%D0%B0%D1%82%D0%BA%D0%BE) в Семантическом Версионировании).
|
(соответствует [`MAJOR`](https://semver.org/lang/ru/#%D0%BA%D1%80%D0%B0%D1%82%D0%BA%D0%BE) в Семантическом Версионировании).
|
||||||
`BREAKING CHANGE` может быть частью коммита любого _типа_.
|
`BREAKING CHANGE` может быть частью коммита любого _типа_.
|
||||||
1. Другие _типы_ коммитов разрешены. Например,
|
1. Другие _типы_ коммитов разрешены. Например,
|
||||||
[@commitlint/config-conventional](https://github.com/conventional-changelog/commitlint/tree/master/%40commitlint/config-conventional) (основан
|
[@commitlint/config-conventional](https://github.com/conventional-changelog/commitlint/tree/master/%40commitlint/config-conventional) (основан
|
||||||
на [соглашении Angular](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines)) рекомендует `build`, `chore`,
|
на [соглашении Angular](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines)) рекомендует `build`, `chore`,
|
||||||
`ci`, `docs`, `style`, `refactor`, `perf`, `test` и другие.
|
`ci`, `docs`, `style`, `refactor`, `perf`, `test` и другие.
|
||||||
@ -51,12 +52,13 @@ aliases: ["/ru/"]
|
|||||||
`BREAKING CHANGE`).
|
`BREAKING CHANGE`).
|
||||||
<br /><br />
|
<br /><br />
|
||||||
_Контекст_ может быть добавлен к _типу_ коммита, чтобы предоставить
|
_Контекст_ может быть добавлен к _типу_ коммита, чтобы предоставить
|
||||||
дополнительную контекстную информацию; она содержится в скобках. Например,
|
дополнительную контекстную информацию; она содержится в скобках. Например,
|
||||||
`feat(parser): add ability to parse arrays`.
|
`feat(parser): add ability to parse arrays`.
|
||||||
|
|
||||||
## Примеры
|
## Примеры
|
||||||
|
|
||||||
### Сообщение коммита с _описанием_ и _сноской_ `BREAKING CHANGE`
|
### Сообщение коммита с _описанием_ и _сноской_ `BREAKING CHANGE`
|
||||||
|
|
||||||
```
|
```
|
||||||
feat: allow provided config object to extend other configs
|
feat: allow provided config object to extend other configs
|
||||||
|
|
||||||
@ -64,16 +66,19 @@ BREAKING CHANGE: `extends` key in config file is now used for extending other co
|
|||||||
```
|
```
|
||||||
|
|
||||||
### Сообщение коммита с `!` для привлечения внимания к `BREAKING CHANGE`
|
### Сообщение коммита с `!` для привлечения внимания к `BREAKING CHANGE`
|
||||||
|
|
||||||
```
|
```
|
||||||
feat!: send an email to the customer when a product is shipped
|
feat!: send an email to the customer when a product is shipped
|
||||||
```
|
```
|
||||||
|
|
||||||
### Сообщение коммита с _контекстом_ и `!` для привлечения внимания к `BREAKING CHANGE`
|
### Сообщение коммита с _контекстом_ и `!` для привлечения внимания к `BREAKING CHANGE`
|
||||||
|
|
||||||
```
|
```
|
||||||
feat(api)!: send an email to the customer when a product is shipped
|
feat(api)!: send an email to the customer when a product is shipped
|
||||||
```
|
```
|
||||||
|
|
||||||
### Сообщение коммита вместе с `!` и _сноской_ `BREAKING CHANGE`
|
### Сообщение коммита вместе с `!` и _сноской_ `BREAKING CHANGE`
|
||||||
|
|
||||||
```
|
```
|
||||||
chore!: drop support for Node 6
|
chore!: drop support for Node 6
|
||||||
|
|
||||||
@ -81,16 +86,19 @@ BREAKING CHANGE: use JavaScript features not available in Node 6.
|
|||||||
```
|
```
|
||||||
|
|
||||||
### Сообщение коммита без _тела_
|
### Сообщение коммита без _тела_
|
||||||
|
|
||||||
```
|
```
|
||||||
docs: correct spelling of CHANGELOG
|
docs: correct spelling of CHANGELOG
|
||||||
```
|
```
|
||||||
|
|
||||||
### Сообщение коммита с _контекстом_
|
### Сообщение коммита с _контекстом_
|
||||||
|
|
||||||
```
|
```
|
||||||
feat(lang): add polish language
|
feat(lang): add polish language
|
||||||
```
|
```
|
||||||
|
|
||||||
### Сообщение коммита с _телом_ из нескольких абзацев и несколькими _сносками_
|
### Сообщение коммита с _телом_ из нескольких абзацев и несколькими _сносками_
|
||||||
|
|
||||||
```
|
```
|
||||||
fix: prevent racing of requests
|
fix: prevent racing of requests
|
||||||
|
|
||||||
@ -117,25 +125,25 @@ Refs: #123
|
|||||||
функционал в ваше приложение или вашу библиотеку.
|
функционал в ваше приложение или вашу библиотеку.
|
||||||
1. _Тип_ `fix` должен (MUST) использоваться, когда коммит исправляет баг в
|
1. _Тип_ `fix` должен (MUST) использоваться, когда коммит исправляет баг в
|
||||||
вашем приложении или вашей библиотеке.
|
вашем приложении или вашей библиотеке.
|
||||||
1. _Контекст_ может (MAY) следовать после _типа_. _Контекст_ должен (MUST)
|
1. _Контекст_ может (MAY) следовать после _типа_. _Контекст_ должен (MUST)
|
||||||
быть существительным, заключённым в круглые скобки, описывающий часть
|
быть существительным, заключённым в круглые скобки, описывающий часть
|
||||||
кодовой базы, которую затронул коммит. Например, `fix(parser)`.
|
кодовой базы, которую затронул коммит. Например, `fix(parser)`.
|
||||||
1. _Описание_ должно (MUST) следовать сразу за двоеточием (`:`) и пробелом
|
1. _Описание_ должно (MUST) следовать сразу за двоеточием (`:`) и пробелом
|
||||||
(` `) после _типа_ или _контекста_. _Описание_ представляет собой краткое
|
(` `) после _типа_ или _контекста_. _Описание_ представляет собой краткое
|
||||||
изложение изменений кода. Например, `fix: array parsing issue when multiple
|
изложение изменений кода. Например, `fix: array parsing issue when multiple
|
||||||
spaces were contained in string`.
|
spaces were contained in string`.
|
||||||
1. _Тело_ коммита может (MAY) следовать после короткого _описания_, добавляя
|
1. _Тело_ коммита может (MAY) следовать после короткого _описания_, добавляя
|
||||||
дополнительную контекстную информацию об изменениях в коде. _Тело_ должно
|
дополнительную контекстную информацию об изменениях в коде. _Тело_ должно
|
||||||
(MUST) отделяться от _описания_ одной пустой строкой.
|
(MUST) отделяться от _описания_ одной пустой строкой.
|
||||||
1. _Тело_ коммита имеет произвольную форму и может (MAY) состоять из любого
|
1. _Тело_ коммита имеет произвольную форму и может (MAY) состоять из любого
|
||||||
количества абзацев, разделённых новой строкой.
|
количества абзацев, разделённых новой строкой.
|
||||||
1. В одной или нескольких _сносках_ может (MAY) быть одна пустая строка после
|
1. В одной или нескольких _сносках_ может (MAY) быть одна пустая строка после
|
||||||
_тела_. Каждая _сноска_ должна (MUST) состоять из токена слова, за которым
|
_тела_. Каждая _сноска_ должна (MUST) состоять из токена слова, за которым
|
||||||
следует разделитель `:<пробел>` или `<пробел>#`, за которым следует
|
следует разделитель `:<пробел>` или `<пробел>#`, за которым следует
|
||||||
строковое значение (основано на [git trailer format](https://git-scm.com/docs/git-interpret-trailers)).
|
строковое значение (основано на [git trailer format](https://git-scm.com/docs/git-interpret-trailers)).
|
||||||
1. Токен _сноски_ должен (MUST) использовать `-` вместо пробельных символов.
|
1. Токен _сноски_ должен (MUST) использовать `-` вместо пробельных символов.
|
||||||
Например, `Acked-by` (это помогает отличить раздел _сноски_ от его _тела_,
|
Например, `Acked-by` (это помогает отличить раздел _сноски_ от его _тела_,
|
||||||
состоящего из нескольких абзацев). Исключение составляет `BREAKING CHANGE`,
|
состоящего из нескольких абзацев). Исключение составляет `BREAKING CHANGE`,
|
||||||
которое может (MAY) также использоваться как токен.
|
которое может (MAY) также использоваться как токен.
|
||||||
1. _Сноска_ может (MAY) содержать пробелы и символы новой строки, а считывание
|
1. _Сноска_ может (MAY) содержать пробелы и символы новой строки, а считывание
|
||||||
должно (MUST) завершаться при обнаружении следующей допустимой пары
|
должно (MUST) завершаться при обнаружении следующей допустимой пары
|
||||||
@ -144,15 +152,15 @@ Refs: #123
|
|||||||
_сноске_ коммита.
|
_сноске_ коммита.
|
||||||
1. Если `BREAKING CHANGE` включено в _сноску_, то оно должно (MUST) состоять из
|
1. Если `BREAKING CHANGE` включено в _сноску_, то оно должно (MUST) состоять из
|
||||||
прописного текста `BREAKING CHANGE`, за которым следует двоеточие (`:`),
|
прописного текста `BREAKING CHANGE`, за которым следует двоеточие (`:`),
|
||||||
пробел (` `) и _описание_. Например, `BREAKING CHANGE: environment
|
пробел (` `) и _описание_. Например, `BREAKING CHANGE: environment
|
||||||
variables now take precedence over config files`.
|
variables now take precedence over config files`.
|
||||||
1. Если критические изменения находятся в _типе_ или _контексте_, то они должны
|
1. Если критические изменения находятся в _типе_ или _контексте_, то они должны
|
||||||
(MUST) быть обозначены восклицательным знаком (`!`), непосредственно перед
|
(MUST) быть обозначены восклицательным знаком (`!`), непосредственно перед
|
||||||
двоеточием (`:`). Если используется восклицательный знак (`!`), то
|
двоеточием (`:`). Если используется восклицательный знак (`!`), то
|
||||||
`BREAKING CHANGE` может (MAY) быть опущен в _сноске_, а _описание_ коммита
|
`BREAKING CHANGE` может (MAY) быть опущен в _сноске_, а _описание_ коммита
|
||||||
должно (SHALL) использоваться для описания критического изменения.
|
должно (SHALL) использоваться для описания критического изменения.
|
||||||
1. В ваших сообщениях коммитов могут (MAY) использоваться _типы_, отличные от
|
1. В ваших сообщениях коммитов могут (MAY) использоваться _типы_, отличные от
|
||||||
`feat` и `fix`. Например, `docs: updated ref docs`.
|
`feat` и `fix`. Например, `docs: updated ref docs`.
|
||||||
1. Единицы информации, которые составляют «Соглашение о коммитах», не должны
|
1. Единицы информации, которые составляют «Соглашение о коммитах», не должны
|
||||||
(MUST NOT) обрабатываться разработчиками как чувствительные к регистру, за
|
(MUST NOT) обрабатываться разработчиками как чувствительные к регистру, за
|
||||||
исключением `BREAKING CHANGE`, которое должно (MUST) быть прописными.
|
исключением `BREAKING CHANGE`, которое должно (MUST) быть прописными.
|
||||||
@ -161,22 +169,22 @@ Refs: #123
|
|||||||
|
|
||||||
## Зачем использовать «Соглашение о коммитах»
|
## Зачем использовать «Соглашение о коммитах»
|
||||||
|
|
||||||
* Автоматическое создание списков изменения.
|
- Автоматическое создание списков изменения.
|
||||||
* Автоматическое определение семантического повышения версии (на основе _типов_
|
- Автоматическое определение семантического повышения версии (на основе _типов_
|
||||||
совершённых коммитов).
|
совершённых коммитов).
|
||||||
* Информирование товарищей по команде, общественности и других заинтересованных
|
- Информирование товарищей по команде, общественности и других заинтересованных
|
||||||
сторон о характере изменений.
|
сторон о характере изменений.
|
||||||
* Запуск процессов сборки и публикации.
|
- Запуск процессов сборки и публикации.
|
||||||
* Упрощать людям участие в ваших проектах, позволив им изучить более
|
- Упрощать людям участие в ваших проектах, позволив им изучить более
|
||||||
структурированную историю коммитов.
|
структурированную историю коммитов.
|
||||||
|
|
||||||
## FAQ (часто задаваемые вопросы)
|
## FAQ (часто задаваемые вопросы)
|
||||||
|
|
||||||
### Как мне поступать с сообщениями коммитов на начальном этапе разработки?
|
### Как мне поступать с сообщениями коммитов на начальном этапе разработки?
|
||||||
|
|
||||||
Мы рекомендуем действовать так, как если бы вы уже выпустили продукт. Обычно
|
Мы рекомендуем действовать так, как если бы вы уже выпустили продукт. Обычно
|
||||||
*кто-то*, даже если это ваши коллеги-разработчики программного обеспечения,
|
_кто-то_, даже если это ваши коллеги-разработчики программного обеспечения,
|
||||||
использует ваше программное обеспечение. Они захотят знать, что исправлено,
|
использует ваше программное обеспечение. Они захотят знать, что исправлено,
|
||||||
что ломается и т. д.
|
что ломается и т. д.
|
||||||
|
|
||||||
### _Типы_ в заголовке коммита должны быть прописными или строчными?
|
### _Типы_ в заголовке коммита должны быть прописными или строчными?
|
||||||
@ -185,21 +193,21 @@ Refs: #123
|
|||||||
|
|
||||||
### Что мне делать, если коммит соответствует более чем одному _типу_?
|
### Что мне делать, если коммит соответствует более чем одному _типу_?
|
||||||
|
|
||||||
По возможности вернитесь назад и сделайте несколько коммитов. Часть
|
По возможности вернитесь назад и сделайте несколько коммитов. Часть
|
||||||
преимущества «Соглашения о коммитах» - его способность побуждать нас делать
|
преимущества «Соглашения о коммитах» - его способность побуждать нас делать
|
||||||
более организованные коммиты и PRs (pull requests, или
|
более организованные коммиты и PRs (pull requests, или
|
||||||
запросы на вытягивание).
|
запросы на вытягивание).
|
||||||
|
|
||||||
### Разве это не препятствует интенсивной разработке и быстрой итерации?
|
### Разве это не препятствует интенсивной разработке и быстрой итерации?
|
||||||
|
|
||||||
Это препятствует быстрому неорганизованному движению. Это поможет вам быстро
|
Это препятствует быстрому неорганизованному движению. Это поможет вам быстро
|
||||||
продвигаться в долгосрочной перспективе в нескольких проектах с разными
|
продвигаться в долгосрочной перспективе в нескольких проектах с разными
|
||||||
участниками.
|
участниками.
|
||||||
|
|
||||||
### Может ли «Соглашение о коммитах» привести разработчиков к ограничению _типов_ совершаемых ими коммитов, потому что они будут думать в соответствии с предоставленными _типами_?
|
### Может ли «Соглашение о коммитах» привести разработчиков к ограничению _типов_ совершаемых ими коммитов, потому что они будут думать в соответствии с предоставленными _типами_?
|
||||||
|
|
||||||
«Соглашение о коммитах» побуждает нас делать больше определённых _типов_
|
«Соглашение о коммитах» побуждает нас делать больше определённых _типов_
|
||||||
коммитов, таких, как `fix`. Помимо этого, гибкость «Соглашения о коммитах»
|
коммитов, таких, как `fix`. Помимо этого, гибкость «Соглашения о коммитах»
|
||||||
позволяет вашей команде придумывать свои собственные _типы_ и со временем
|
позволяет вашей команде придумывать свои собственные _типы_ и со временем
|
||||||
изменять их.
|
изменять их.
|
||||||
|
|
||||||
@ -208,7 +216,7 @@ Refs: #123
|
|||||||
Коммиты _типа_ `fix` должны быть переведены в выпуски `PATCH`, `feat` — в
|
Коммиты _типа_ `fix` должны быть переведены в выпуски `PATCH`, `feat` — в
|
||||||
`MINOR`, `BREAKING CHANGE`, независимо от _типа_, — в `MAJOR`.
|
`MINOR`, `BREAKING CHANGE`, независимо от _типа_, — в `MAJOR`.
|
||||||
|
|
||||||
### Как мне довести свои расширения до спецификации «Соглашение о коммитах». Например, `@jameswomack/standard-commit-spec`?
|
### Как мне довести свои расширения до спецификации «Соглашение о коммитах». Например, `@jameswomack/standard-commit-spec`?
|
||||||
|
|
||||||
Мы рекомендуем использовать Семантическое Версионирование для выпуска
|
Мы рекомендуем использовать Семантическое Версионирование для выпуска
|
||||||
ваших собственных расширений для этой спецификации (и призываем вас создавать
|
ваших собственных расширений для этой спецификации (и призываем вас создавать
|
||||||
@ -216,24 +224,24 @@ Refs: #123
|
|||||||
|
|
||||||
### Что мне делать, если я случайно использовал неправильный _тип_ коммита?
|
### Что мне делать, если я случайно использовал неправильный _тип_ коммита?
|
||||||
|
|
||||||
#### Когда вы использовали неправильный _тип_, но соответствующий спецификации. Например, `fix` вместо `feat`
|
#### Когда вы использовали неправильный _тип_, но соответствующий спецификации. Например, `fix` вместо `feat`
|
||||||
|
|
||||||
Перед объединением или выпуском ошибки мы рекомендуем использовать `git rebase
|
Перед объединением или выпуском ошибки мы рекомендуем использовать `git rebase
|
||||||
-i` для редактирования истории коммитов. После выпуска редактирование будет
|
-i` для редактирования истории коммитов. После выпуска редактирование будет
|
||||||
отличаться в зависимости от того, какие инструменты и процессы вы используете.
|
отличаться в зависимости от того, какие инструменты и процессы вы используете.
|
||||||
|
|
||||||
#### Когда вы использовали _тип_, не указанный в спецификации. Например, `feet` вместо `feat`
|
#### Когда вы использовали _тип_, не указанный в спецификации. Например, `feet` вместо `feat`
|
||||||
|
|
||||||
В худшем случае это ещё не конец света, если коммит не соответствует
|
В худшем случае это ещё не конец света, если коммит не соответствует
|
||||||
спецификации «Соглашения о коммитах». Это просто означает, что коммит будет
|
спецификации «Соглашения о коммитах». Это просто означает, что коммит будет
|
||||||
пропущен инструментами, основанными на спецификации.
|
пропущен инструментами, основанными на спецификации.
|
||||||
|
|
||||||
### Все ли мои участники должны использовать спецификацию «Соглашения о коммитах»?
|
### Все ли мои участники должны использовать спецификацию «Соглашения о коммитах»?
|
||||||
|
|
||||||
Нет! Если вы используете рабочий процесс на основе соединения (squash)
|
Нет! Если вы используете рабочий процесс на основе соединения (squash)
|
||||||
коммитов в Git, то ведущие специалисты по сопровождению могут приводить в
|
коммитов в Git, то ведущие специалисты по сопровождению могут приводить в
|
||||||
порядок сообщения коммитов по мере их слияния (merge), не добавляя нагрузки для
|
порядок сообщения коммитов по мере их слияния (merge), не добавляя нагрузки для
|
||||||
обычных коммиттеров. Обычный рабочий процесс для этого состоит в том, чтобы
|
обычных коммиттеров. Обычный рабочий процесс для этого состоит в том, чтобы
|
||||||
ваша система Git автоматически соединяла коммиты из PR и представляла форму для
|
ваша система Git автоматически соединяла коммиты из PR и представляла форму для
|
||||||
ведущего сопровождающего, чтобы ввести более подходящее сообщение коммита для
|
ведущего сопровождающего, чтобы ввести более подходящее сообщение коммита для
|
||||||
слияния.
|
слияния.
|
||||||
@ -241,17 +249,18 @@ Refs: #123
|
|||||||
### Как «Соглашение о коммитах» обрабатывает отмену коммитов?
|
### Как «Соглашение о коммитах» обрабатывает отмену коммитов?
|
||||||
|
|
||||||
Отмена изменений кода может быть сложной:
|
Отмена изменений кода может быть сложной:
|
||||||
|
|
||||||
- Вы отменяете изменения нескольких коммитов?
|
- Вы отменяете изменения нескольких коммитов?
|
||||||
- Если вы отмените изменения новых функций, должен ли следующий выпуск быть
|
- Если вы отмените изменения новых функций, должен ли следующий выпуск быть
|
||||||
патчем?
|
патчем?
|
||||||
|
|
||||||
«Соглашение о коммитах» не делает явных попыток определить поведение отмены
|
«Соглашение о коммитах» не делает явных попыток определить поведение отмены
|
||||||
изменений. Вместо этого мы оставляем авторам инструментов использование
|
изменений. Вместо этого мы оставляем авторам инструментов использование
|
||||||
гибкости _типов_ и _сносок_ для разработки своей логики для обработки отмены
|
гибкости _типов_ и _сносок_ для разработки своей логики для обработки отмены
|
||||||
изменений.
|
изменений.
|
||||||
|
|
||||||
Одна из рекомендаций — использовать _тип_ `revert` и _сноску_, которая
|
Одна из рекомендаций — использовать _тип_ `revert` и _сноску_, которая
|
||||||
ссылается на отменяемые хэш-суммы коммитов. Например:
|
ссылается на отменяемые хэш-суммы коммитов. Например:
|
||||||
|
|
||||||
```
|
```
|
||||||
revert: let us never again speak of the noodle incident
|
revert: let us never again speak of the noodle incident
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user