conventionalcommits.org/content/v1.0.0-beta.4/index.ru.md

230 lines
19 KiB
Markdown
Raw Normal View History

2019-04-24 23:50:56 +02:00
---
draft: false
aliases: ["/ru/"]
---
# Conventional Commits 1.0.0-beta.4
## Главное
Conventional Commits - это простое соглашение о том, как нужно писать сообщения commit'ов.
Оно описывает простой набор правил для создания понятной истории commit'ов,
2019-09-30 20:44:21 +02:00
а также позволяет проще разрабатывать инструменты автоматизации, основанные на
2019-04-24 23:50:56 +02:00
истории commit'ов. Данное соглашение совместимо с [SemVer](http://semver.org),
описывая новые функции (features), исправления (fixes) и изменения, нарушающие
2019-04-24 23:50:56 +02:00
обратную совместимость (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:`,
2019-09-30 20:44:21 +02:00
также разрешены. Например, [@commitlint/config-conventional](https://github.com/conventional-changelog/commitlint/tree/master/%40commitlint/config-conventional)
2019-04-24 23:50:56 +02:00
(основанный на [The Angular convention](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines))
рекомендует: `chore:`, `docs:`, `style:`, `refactor:`, `perf:`, `test:`, и другие.
2019-09-30 20:44:21 +02:00
Мы также рекомендуем `improvement` для commit'ов, которые вносят улучшения в текущую
2019-04-24 23:50:56 +02:00
реализацию без добавления новых функций и исправления ошибок. Обратите внимание, что
данный тип не описывается данной спецификацией и не имеет эффекта в 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)
в вашем приложении или библиотеке.
2019-04-24 23:50:56 +02:00
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'а.
2019-04-24 23:50:56 +02:00
Он должен быть отделен от тела commit'а одной пустой строкой. Подвал должен (MUST)
содержать мета-информацию о commit'е. Например, связанные pull-request'ы, обсуждения,
изменения, нарушающие обратную совместимость. По одной мета-информации на строку.
1. Изменения, нарушающие обратную совместимость (breaking changes), должны (MUST) быть
2019-04-24 23:50:56 +02:00
указаны в самом начале тела (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'ов).
* Коммуникация о характере изменений между товарищами по команде, общественностью и другими заинтересованными сторонами.
2019-04-24 23:50:56 +02:00
* Автоматически срабатываемый процесс сборки и публикации.
* Людям проще участвовать в вашем проекте, потому что им доступна более структурированная история коммитов.
## FAQ
### Как я должен писать сообщения commit'ов на начальной стадии разработки?
Мы рекомендуем писать сообщения commit'ов так, как будто вы уже выпустили продукт. Как правило, *кто-то*, например,
ваши коллеги, уже используют ваш код. И они хотят знать, что исправилось, что изменилось, какие нарушения обратной
совместимости появились и т.д.
### В каком регистре я должен писать заголовки commit'ов?
Любой регистр можно использовать, но лучше во всей истории использовать один стиль.
### Что мне делать, если commit должен содержать больше одного типа?
Вернитесь назад и сделайте несколько commit'ов, если это возможно. Часть из преимуществ использования Conventional Commits - это его способность побуждать делать более организованные коммиты и PR'ы.
### Разве это не препятствует быстрому развитию и быстрой интеграции?
Это препятствует быстрому развитию в неорганизованном виде. Это помогает быстро двигаться в нескольких проектах
с несколькими участниками.
### Могут ли Conventional Commits заставить разработчиков ограничивать их типы commit'ов, потому что им придется думать об этих типах?
Conventional Commits побуждают делать больше commit'ов с определенными типами, такими как `fix`. Кроме того, гибкость
Conventional Commits позволяет вашей команде создавать свои собственные типы и изменять их с течением времени.
2019-04-24 23:50:56 +02:00
### Как это связано с правилами семантического управления версиями [SemVer](http://semver.org)?
2019-04-24 23:50:56 +02:00
`fix` тип commit'а должен быть отражен в `PATCH`-релизе. `feat` тип commit'а должен быть отражен в `MINOR`-релизе.
Commit'ы с `BREAKING CHANGE` в теле или подвале, независимо от типа, должны быть отражены в `MAJOR`-релизе.
2019-04-24 23:50:56 +02:00
### Как я должен версионировать мои расширения к спецификации 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'ы
2019-04-24 23:50:56 +02:00
перед pull-запросом и предоставляет форму сопровождающему проекта для ввода нового commit'а.
## О спецификации
Conventional Commits вдохновлены и основаны на
2019-04-24 23:50:56 +02:00
[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.
2019-04-24 23:50:56 +02:00
## Утилиты для Conventional Commits
* [php-commitizen](https://github.com/damianopetrungaro/php-commitizen): утилита для создания сообщений commit'ов, следующих Conventional Commits спецификации.
2019-04-24 23:50:56 +02:00
Используется для PHP-проектов, как зависимость composer, или глобально для не PHP-проектов.
* [conform](https://github.com/autonomy/conform): утилита, которая может быть использована для реализации политик в git-репозиториях, включая правила написания commit'ов.
* [standard-version](https://github.com/conventional-changelog/standard-version): утилита, для автоматического контроля версий и CHANGELOG'ов,
2019-04-24 23:50:56 +02:00
использующая новую кнопку `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): свободный менеджер персональных связей.
2019-08-27 18:26:19 +02:00
* [mhy](https://mhy.js.org): набор инструментов и окружение для разработки с нулевой конфигурацией, которые работают из коробки.
* [sharec](https://github.com/lamartire/sharec): минималистичный инструмент для скаффолдинга и версионирования конфигурации.
2019-04-24 23:50:56 +02:00
[![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg)](https://conventionalcommits.org)
_Хотите, чтоб ваш проект появился в этом списке?_ [Отправьте Pull Request](https://github.com/conventional-changelog/conventionalcommits.org/pulls).