diff --git a/content/v1.0.0/index.ru.md b/content/v1.0.0/index.ru.md index 0e26349..3a65195 100644 --- a/content/v1.0.0/index.ru.md +++ b/content/v1.0.0/index.ru.md @@ -8,9 +8,9 @@ aliases: ["/ru/"] ## Главное Спецификация «Соглашение о коммитах» — простое соглашение о том, как нужно -писать сообщения коммитов. Оно описывает простой набор правил для создания +писать сообщения коммитов. Оно описывает простой набор правил для создания понятной истории коммитов, а также позволяет проще разрабатывать инструменты -автоматизации, основанные на истории коммитов. Данное соглашение совместимо с +автоматизации, основанные на истории коммитов. Данное соглашение совместимо с [Семантическим Версионированием](https://semver.org/lang/ru/), описывая новые функции, исправления и изменения, нарушающие обратную совместимость в сообщениях коммитов. @@ -25,6 +25,7 @@ aliases: ["/ru/"] [необязательная(ые) сноска(и)] ``` + ---
@@ -40,7 +41,7 @@ aliases: ["/ru/"] _контекста_, вводящий изменение(я), нарушающие обратную совместимость (соответствует [`MAJOR`](https://semver.org/lang/ru/#%D0%BA%D1%80%D0%B0%D1%82%D0%BA%D0%BE) в Семантическом Версионировании). `BREAKING CHANGE` может быть частью коммита любого _типа_. -1. Другие _типы_ коммитов разрешены. Например, +1. Другие _типы_ коммитов разрешены. Например, [@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`, `ci`, `docs`, `style`, `refactor`, `perf`, `test` и другие. @@ -51,12 +52,13 @@ aliases: ["/ru/"] `BREAKING CHANGE`).

_Контекст_ может быть добавлен к _типу_ коммита, чтобы предоставить -дополнительную контекстную информацию; она содержится в скобках. Например, +дополнительную контекстную информацию; она содержится в скобках. Например, `feat(parser): add ability to parse arrays`. ## Примеры ### Сообщение коммита с _описанием_ и _сноской_ `BREAKING CHANGE` + ``` 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` + ``` feat!: send an email to the customer when a product is shipped ``` ### Сообщение коммита с _контекстом_ и `!` для привлечения внимания к `BREAKING CHANGE` + ``` feat(api)!: send an email to the customer when a product is shipped ``` ### Сообщение коммита вместе с `!` и _сноской_ `BREAKING CHANGE` + ``` 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 ``` ### Сообщение коммита с _контекстом_ + ``` feat(lang): add polish language ``` ### Сообщение коммита с _телом_ из нескольких абзацев и несколькими _сносками_ + ``` fix: prevent racing of requests @@ -117,25 +125,25 @@ Refs: #123 функционал в ваше приложение или вашу библиотеку. 1. _Тип_ `fix` должен (MUST) использоваться, когда коммит исправляет баг в вашем приложении или вашей библиотеке. -1. _Контекст_ может (MAY) следовать после _типа_. _Контекст_ должен (MUST) +1. _Контекст_ может (MAY) следовать после _типа_. _Контекст_ должен (MUST) быть существительным, заключённым в круглые скобки, описывающий часть - кодовой базы, которую затронул коммит. Например, `fix(parser)`. + кодовой базы, которую затронул коммит. Например, `fix(parser)`. 1. _Описание_ должно (MUST) следовать сразу за двоеточием (`:`) и пробелом - (` `) после _типа_ или _контекста_. _Описание_ представляет собой краткое - изложение изменений кода. Например, `fix: array parsing issue when multiple - spaces were contained in string`. + (` `) после _типа_ или _контекста_. _Описание_ представляет собой краткое + изложение изменений кода. Например, `fix: array parsing issue when multiple +spaces were contained in string`. 1. _Тело_ коммита может (MAY) следовать после короткого _описания_, добавляя - дополнительную контекстную информацию об изменениях в коде. _Тело_ должно + дополнительную контекстную информацию об изменениях в коде. _Тело_ должно (MUST) отделяться от _описания_ одной пустой строкой. 1. _Тело_ коммита имеет произвольную форму и может (MAY) состоять из любого количества абзацев, разделённых новой строкой. 1. В одной или нескольких _сносках_ может (MAY) быть одна пустая строка после - _тела_. Каждая _сноска_ должна (MUST) состоять из токена слова, за которым + _тела_. Каждая _сноска_ должна (MUST) состоять из токена слова, за которым следует разделитель `:<пробел>` или `<пробел>#`, за которым следует строковое значение (основано на [git trailer format](https://git-scm.com/docs/git-interpret-trailers)). 1. Токен _сноски_ должен (MUST) использовать `-` вместо пробельных символов. Например, `Acked-by` (это помогает отличить раздел _сноски_ от его _тела_, - состоящего из нескольких абзацев). Исключение составляет `BREAKING CHANGE`, + состоящего из нескольких абзацев). Исключение составляет `BREAKING CHANGE`, которое может (MAY) также использоваться как токен. 1. _Сноска_ может (MAY) содержать пробелы и символы новой строки, а считывание должно (MUST) завершаться при обнаружении следующей допустимой пары @@ -144,15 +152,15 @@ Refs: #123 _сноске_ коммита. 1. Если `BREAKING CHANGE` включено в _сноску_, то оно должно (MUST) состоять из прописного текста `BREAKING CHANGE`, за которым следует двоеточие (`:`), - пробел (` `) и _описание_. Например, `BREAKING CHANGE: environment - variables now take precedence over config files`. + пробел (` `) и _описание_. Например, `BREAKING CHANGE: environment +variables now take precedence over config files`. 1. Если критические изменения находятся в _типе_ или _контексте_, то они должны (MUST) быть обозначены восклицательным знаком (`!`), непосредственно перед - двоеточием (`:`). Если используется восклицательный знак (`!`), то + двоеточием (`:`). Если используется восклицательный знак (`!`), то `BREAKING CHANGE` может (MAY) быть опущен в _сноске_, а _описание_ коммита должно (SHALL) использоваться для описания критического изменения. 1. В ваших сообщениях коммитов могут (MAY) использоваться _типы_, отличные от - `feat` и `fix`. Например, `docs: updated ref docs`. + `feat` и `fix`. Например, `docs: updated ref docs`. 1. Единицы информации, которые составляют «Соглашение о коммитах», не должны (MUST NOT) обрабатываться разработчиками как чувствительные к регистру, за исключением `BREAKING CHANGE`, которое должно (MUST) быть прописными. @@ -161,22 +169,22 @@ Refs: #123 ## Зачем использовать «Соглашение о коммитах» -* Автоматическое создание списков изменения. -* Автоматическое определение семантического повышения версии (на основе _типов_ +- Автоматическое создание списков изменения. +- Автоматическое определение семантического повышения версии (на основе _типов_ совершённых коммитов). -* Информирование товарищей по команде, общественности и других заинтересованных +- Информирование товарищей по команде, общественности и других заинтересованных сторон о характере изменений. -* Запуск процессов сборки и публикации. -* Упрощать людям участие в ваших проектах, позволив им изучить более +- Запуск процессов сборки и публикации. +- Упрощать людям участие в ваших проектах, позволив им изучить более структурированную историю коммитов. ## FAQ (часто задаваемые вопросы) ### Как мне поступать с сообщениями коммитов на начальном этапе разработки? -Мы рекомендуем действовать так, как если бы вы уже выпустили продукт. Обычно -*кто-то*, даже если это ваши коллеги-разработчики программного обеспечения, -использует ваше программное обеспечение. Они захотят знать, что исправлено, +Мы рекомендуем действовать так, как если бы вы уже выпустили продукт. Обычно +_кто-то_, даже если это ваши коллеги-разработчики программного обеспечения, +использует ваше программное обеспечение. Они захотят знать, что исправлено, что ломается и т. д. ### _Типы_ в заголовке коммита должны быть прописными или строчными? @@ -185,21 +193,21 @@ Refs: #123 ### Что мне делать, если коммит соответствует более чем одному _типу_? -По возможности вернитесь назад и сделайте несколько коммитов. Часть +По возможности вернитесь назад и сделайте несколько коммитов. Часть преимущества «Соглашения о коммитах» - его способность побуждать нас делать более организованные коммиты и PRs (pull requests, или запросы на вытягивание). ### Разве это не препятствует интенсивной разработке и быстрой итерации? -Это препятствует быстрому неорганизованному движению. Это поможет вам быстро +Это препятствует быстрому неорганизованному движению. Это поможет вам быстро продвигаться в долгосрочной перспективе в нескольких проектах с разными участниками. ### Может ли «Соглашение о коммитах» привести разработчиков к ограничению _типов_ совершаемых ими коммитов, потому что они будут думать в соответствии с предоставленными _типами_? «Соглашение о коммитах» побуждает нас делать больше определённых _типов_ -коммитов, таких, как `fix`. Помимо этого, гибкость «Соглашения о коммитах» +коммитов, таких, как `fix`. Помимо этого, гибкость «Соглашения о коммитах» позволяет вашей команде придумывать свои собственные _типы_ и со временем изменять их. @@ -208,7 +216,7 @@ Refs: #123 Коммиты _типа_ `fix` должны быть переведены в выпуски `PATCH`, `feat` — в `MINOR`, `BREAKING CHANGE`, независимо от _типа_, — в `MAJOR`. -### Как мне довести свои расширения до спецификации «Соглашение о коммитах». Например, `@jameswomack/standard-commit-spec`? +### Как мне довести свои расширения до спецификации «Соглашение о коммитах». Например, `@jameswomack/standard-commit-spec`? Мы рекомендуем использовать Семантическое Версионирование для выпуска ваших собственных расширений для этой спецификации (и призываем вас создавать @@ -216,24 +224,24 @@ Refs: #123 ### Что мне делать, если я случайно использовал неправильный _тип_ коммита? -#### Когда вы использовали неправильный _тип_, но соответствующий спецификации. Например, `fix` вместо `feat` +#### Когда вы использовали неправильный _тип_, но соответствующий спецификации. Например, `fix` вместо `feat` Перед объединением или выпуском ошибки мы рекомендуем использовать `git rebase --i` для редактирования истории коммитов. После выпуска редактирование будет +-i` для редактирования истории коммитов. После выпуска редактирование будет отличаться в зависимости от того, какие инструменты и процессы вы используете. -#### Когда вы использовали _тип_, не указанный в спецификации. Например, `feet` вместо `feat` +#### Когда вы использовали _тип_, не указанный в спецификации. Например, `feet` вместо `feat` В худшем случае это ещё не конец света, если коммит не соответствует -спецификации «Соглашения о коммитах». Это просто означает, что коммит будет +спецификации «Соглашения о коммитах». Это просто означает, что коммит будет пропущен инструментами, основанными на спецификации. ### Все ли мои участники должны использовать спецификацию «Соглашения о коммитах»? -Нет! Если вы используете рабочий процесс на основе соединения (squash) +Нет! Если вы используете рабочий процесс на основе соединения (squash) коммитов в Git, то ведущие специалисты по сопровождению могут приводить в порядок сообщения коммитов по мере их слияния (merge), не добавляя нагрузки для -обычных коммиттеров. Обычный рабочий процесс для этого состоит в том, чтобы +обычных коммиттеров. Обычный рабочий процесс для этого состоит в том, чтобы ваша система Git автоматически соединяла коммиты из PR и представляла форму для ведущего сопровождающего, чтобы ввести более подходящее сообщение коммита для слияния. @@ -241,17 +249,18 @@ Refs: #123 ### Как «Соглашение о коммитах» обрабатывает отмену коммитов? Отмена изменений кода может быть сложной: + - Вы отменяете изменения нескольких коммитов? - Если вы отмените изменения новых функций, должен ли следующий выпуск быть патчем? «Соглашение о коммитах» не делает явных попыток определить поведение отмены -изменений. Вместо этого мы оставляем авторам инструментов использование +изменений. Вместо этого мы оставляем авторам инструментов использование гибкости _типов_ и _сносок_ для разработки своей логики для обработки отмены изменений. Одна из рекомендаций — использовать _тип_ `revert` и _сноску_, которая -ссылается на отменяемые хэш-суммы коммитов. Например: +ссылается на отменяемые хэш-суммы коммитов. Например: ``` revert: let us never again speak of the noodle incident