conventionalcommits.org/content/v1.0.0/index.ru.md

draft	aliases
false	/ru/

Соглашение о коммитах 1.0.0

Главное

Спецификация «Соглашение о коммитах» — простое соглашение о том, как нужно писать сообщения коммитов. Оно описывает простой набор правил для создания понятной истории коммитов, а также позволяет проще разрабатывать инструменты автоматизации, основанные на истории коммитов. Данное соглашение совместимо с семантическим версионированием, описывая новые функции, исправления и изменения, нарушающие обратную совместимость в сообщениях коммитов.

Сообщения коммитов должны быть следующей структуры:

---

<тип>[необязательный контекст]: <описание>

[необязательное тело]

[необязательная(ые) сноска(и)]

---

Коммит содержит следующие структурные элементы для передачи намерений пользователям вашей библиотеки:

1. fix: коммит типа fix исправляет баг в вашем коде (соответствует PATCH в семантическом версионировании).
2. feat: коммит типа feat добавляет новую функцию в ваш код (соответствует MINOR в семантическом версионировании).
3. BREAKING CHANGE: коммит, который имеет сноску BREAKING CHANGE или коммит, заканчивающийся восклицательным знаком (!) после типа или контекста, вводящий изменение(я), нарушающие обратную совместимость (соответствует MAJOR в семантическом версионировании). BREAKING CHANGE может быть частью коммита любого типа.
4. Другие типы коммитов разрешены. Например, @commitlint/config-conventional (основан на соглашении Angular) рекоммендует build, chore, ci, docs, style, refactor, perf, test и другие.
5. Другие сноски коммитов могут быть аналогичны соглашению git trailer format.

Дополнительные типы не требуются «Соглашению о коммитах» и не имеют неявного эффекта в семантическом версионировании (если только они не включают BREAKING CHANGE).

Контекст может быть добавлен к типу коммита, чтобы предоставить дополнительную контекстную информацию; она содержится в скобках. Например, feat(parser): add ability to parse arrays.

Примеры

Сообщение коммита с описанием и сноской BREAKING CHANGE

feat: allow provided config object to extend other configs

BREAKING CHANGE: `extends` key in config file is now used for extending other config files

Чтобы привлечь внимание к критическим изменением, к сообщению коммита добавляется !

refactor!: drop support for Node 6

Сообщение коммита вместе с ! и сноской BREAKING CHANGE.

refactor!: drop support for Node 6

BREAKING CHANGE: refactor to use JavaScript features not available in Node 6.

Сообщение коммита без тела

docs: correct spelling of CHANGELOG

Сообщение коммита с контекстом.

feat(lang): add polish language

Сообщение коммита с телом из нескольких абзацев и несколькими сносками

fix: correct minor typos in code

see the issue for details

on typos fixed.

Reviewed-by: Z
Refs #133

Спецификация

Слова «MUST», «MUST NOT», «REQUIRED», «SHALL», «MAY» и «OPTIONAL» в данном документе должны интерпретироваться как в RFC 2119.

1. Коммиты должны (MUST) начинатся с типа, который является существительным: feat, fix и т. д. За ним следует необязательный (OPTIONAL) контекст, необязательный (OPTIONAL) восклицательный знак (!) и обязательные (REQUIRED) двоеточие (:) и пробел ( ).
2. Тип feat должен (MUST) использоваться, когда коммит добавляет новый функционал в ваше приложение или вашу библиотеку.
3. Тип fix должен (MUST) использоваться, когда коммит исправляет баг в вашем приложении или вашей библиотеке.
4. Контекст может (MAY) следовать после типа. Контекст должен (MUST) быть существительным, заключённым в круглые скобки, описывающий часть кодовой базы, которую затронул коммит. Например, fix(parser).
5. Описание должно (MUST) следовать сразу за двоеточием (:) и пробелом ( ) после типа или контекста. Описание представляет собой краткое изложение изменений кода. Например, fix: array parsing issue when multiple spaces were contained in string.
6. Тело коммита может (MAY) следовать после короткого описания, добавляя дополнительную контекстную информацию об изменениях в коде. Тело должно (MUST) отделяться от описания одной пустой строкой.
7. Тело коммита имеет произвольную форму и может (MAY) состоять из любого количества абзацев, разделённых новой строкой.
8. В одной или нескольких сносках может (MAY) быть одна пустая строка после тела. Каждая сноска должна (MUST) состоять из токена слова, за которым следует разделитель :<пробел> или <пробел>#, за которым следует строковое значение (основано на git trailer format).
9. Токен сноски должен (MUST) использовать - вместо пробельных символов. Например, Acked-by (это помогает отличить раздел сноски от его тела, состоящего из нескольких абзацев). Исключение составляет BREAKING CHANGE, которое может (MAY) также использоваться как токен.
10. Сноска может (MAY) содержать пробелы и символы новой строки, а парсер должен (MUST) завершаться при обнаружении следующей допустимой пары токен-разделитель сноски.
11. Критические изменения должны (MUST) быть указаны в типе, контесте или сноске коммита.
12. Если BREAKING CHANGE включено в сноску, то оно должно (MUST) состоять из прописного текста BREAKING CHANGE, за которым следует двоеточие (:), пробел ( ) и описание. Например, BREAKING CHANGE: environment variables now take precedence over config files.
13. Если критические изменения находятся в типе или контексте, то они должны (MUST) быть обозначены восклицательным знаком (!), непосредственно перед двоеточием (:). Если используется восклицательный знак (!), то BREAKING CHANGE может (MAY) быть опущен в сноске, а описание коммита должно (SHALL) использоваться для описания критического изменения.
14. В ваших сообщениях коммитов могут (MAY) использоваться типы, отличные от feat и fix. Например, docs: updated ref docs.
15. Единицы информации, которые составляют «Соглашение о коммитах», не должны (MUST NOT) обрабатываться разработчиками как чувствительные к регистру, за исключением BREAKING CHANGE, которое должно (MUST) быть прописными.
16. BREAKING-CHANGE должен (MUST) быть синонимом BREAKING CHANGE при использовании в качестве токена в сноске.

Зачем использовать «Соглашение о коммитах»

• Автоматическое создание списков изменения.
• Автоматическое определение семантического повышения версии (на основе типов совершённых коммитов).
• Информирование товарищей по команде, общественности и других заинтересованных сторон о характере изменений.
• Запуск процессов сборки и публикации.
• Упростите людям участие в ваших проектах, позволив им изучить более структурированную историю коммитов.

FAQ (часто задаваемые вопросы)

Как мне поступать с сообщениями коммитов на начальном этапе разработки?

Мы рекомендуем действовать так, как если бы вы уже выпустили продукт. Обычно кто-то, даже если это ваши коллеги-разработчики программного обеспечения, использует ваше программное обеспечение. Они захотят знать, что исправлено, что ломается и т. д.

Типы в заголовке коммита должны быть прописными или строчными?

Выберите тот, который больше всего вам нравится, и строго ему следуйте.

Что мне делать, если коммит соответствует более чем одному типу?

По возможности вернитесь назад и сделайте несколько коммитов. Частью преимущества «Соглашения о коммитах» является способность побуждать нас делать более организованные коммиты и PRs (pull requests, или пулл-реквесты, или запросы на вытягивание).

Разве это не препятствует интенсивной разработке и быстрой итерации?

Это препятствует быстрому неорганизованному движению. Это поможет вам быстро продвигаться в долгосрочной перспективе в нескольких проектах с разными участниками.

Может ли «Соглашение о коммитах» привести разработчиков к ограничению типов совершаемых ими коммитов, потому что они будут думать в соответствии с предоставленными типами?

«Соглашение о коммитах» побуждают нас делать больше определённых типов коммитов, таких как fix. Помимо этого, гибкость «Соглашения о коммитах» позволяет вашей команде придумывать свои собственные типы и со временем изменять их.

Как это связано с семантическим версионированием?

Коммиты типа fix должны быть переведены в выпуски PATCH, feat — в MINOR, BREAKING CHANGE, независимо от типа, — в MAJOR.

Как мне довести свои расширения до спецификации «Соглашение о коммитах». Например, @jameswomack/standard-commit-spec?

Мы рекомендуем использовать семантическое версионирование для выпуска ваших собственных расширений для этой спецификации (и призываем вас создавать эти расширения!).

Что мне делать, если я случайно использовал неправильный тип коммита?

Когда вы использовали тип, соответствующий спецификации, но неправильный. Например, fix вместо feat

Перед объединением или выпуском ошибки мы рекомендуем использовать git rebase -i для редактирования истории коммитов. После выпуска редактирование будет отличаться в зависимости от того, какие инструменты и процессы вы используете.

Когда вы использовали тип, не указанный в спецификации. Например, feet вместо feat

В худшем случае это ещё не конец света, если коммит не соответствует спецификации «Соглашения о коммитах». Это просто означает, что коммит будет пропущен инструментами, основанными на спецификации.

Все ли мои участники должны использовать спецификацию «Соглашения о коммитах»?

Нет! Если вы используете рабочий процесс на основе соединения (squash) коммитов в Git, то ведущие специалисты по сопровождению могут приводить в порядок сообщения коммитов по мере их слияния (merge), не добавляя нагрузки для обычных коммиттеров. Обычный рабочий процесс для этого состоит в том, чтобы ваша система Git автоматически соединяла коммиты из PR и представляла форму для ведущего сопровождающего, чтобы ввести более подходящее сообщение коммита для слияния.

Как «Соглашение о коммитах» обрабатывает отмену коммитов?

Отмена изменений кода может быть сложным:

• Вы отменяете изменения нескольких коммитов?
• Если вы отмените изменения новых функций, должен ли следующий выпуск быть патчем?

«Соглашение о коммитах» не делает явных попыток определить поведение отмены изменений. Вместо этого мы оставляем авторам инструментов использовать гибкость типов и сносок для разработки своей логики для обработки отмены изменений.

Одна из рекомендаций — использовать тип revert и сноску, которая ссылается на отменяемые хэш-суммы коммитов. Например:

revert: let us never again speak of the noodle incident

Refs: 676104e, a215868

Об «Соглашении о коммитах»

Спецификация «Соглашения о коммитах» вдохновлена и в значительной степени основана на руководстве коммитов Angular.

Первый вариант этой спецификации был написан в сотрудничестве с некоторыми людьми, внёсшими свой вклад в:

• conventional-changelog — набор инструментов для анализа сообщений «Соглашения о коммитах» из историй Git.
• parse-commit-message — расширяемые утилиты для парсера, преобразования и проверки сообщений «Соглашения о коммитах».
• bumped — инструмент для выпуска программного обеспечения, который позволяет легко выполнять действия до и после выпуска новой версии вашего программного обеспечения.
• unleash — инструмент для автоматизации выпуска программного обеспечения и публикации жизненного цикла.
• lerna — инструмент для управления монорепозиториями, выросший из проекта Babel.

Инструменты для «Соглашения о коммитах»

• go-conventional-commit — библиотека Go для парсинга сообщений коммитов в соответствии со спецификацией.
• chglog — инструмент для парсинга сообщений «Соглашения о коммитах» из историй Git и превращения их в шаблоны списков изменений.
• fastlane-plugin — следует спецификации для управления версиями и автоматического создания списка изменений.
• commitizen/cz-cli — инструмент Node.js для создания сообщений коммитов в соответствии со спецификацией «Соглашение о коммитах».
• commitizen-tools/commitizen — инструмент, написанный на Python, для создания правил коммитов для проектов, автоматического повышения версий и автоматического создания списка изменений.
• php-commitizen — инструмент PHP, созданный для создания сообщений коммитов в соответствии со спецификацией «Соглашение о коммитах». Настраиваемый и может использоваться для проектов PHP по усмотрению автора в качестве зависимости или использоваться глобально для проектов, отличных от PHP.
• commitlint — линтер для проверки соответствия ваших сообщений коммитов формату «Соглашения о коммитах».
• gitlint — линтер сообщений коммитов Git, написанный на Python, который можно настроить для принудительного применения формата «Соглашения о коммитах».
• conform — инструмент, который можно использовать для обеспечения соблюдения политик в репозиториях Git, включая «Соглашение о коммитах».
• detect-next-version — анализируйте, обнаруживайте и получайте больше метаданных о заданном «Соглашении о коммитах».
• recommended-bump — вычисляет рекомендуемую версию на основе заданном «Соглашении о коммитах».
• git-commits-since — получает все (необработанные) коммиты с периода или (по умолчанию) из последнего тега Git семантического версионирования, плюс поддерживает плагины.
• standard-version — автоматическое управление версиями и списками изменений с помощью новой кнопки squash в GitHub и рекомендованного рабочего процесса «Соглашения о коммитах».
• Conventional Commit — предоставляет расширяемый контекст и завершение на основе шаблонов, а также проверки для «Соглашения о коммитах» в диалоговом окне коммитов VCS. Доступно для всех IDE (интегрированных сред разработки) от JetBrains.
• Git Commit Template — добавьте поддержку «Соглашения о коммитах» в редакторы JetBrains (IntelliJ IDEA, PyCharm, PhpStorm и т. д.).
• commitsar — инструмент Go для проверки совместимости коммитов в ветке с «Соглашением о коммитах». Поставляется с образом Docker для использования в CI.
• semantic-release — инструмент, который автоматизирует весь рабочий процесс выпуска пакета, включая: определение номера следующей версии, создание примечаний к выпуску и публикацию пакета.
• python-semantic-release — автоматическое семантическое управление версиями для проектов Python. Это реализация semantic-release на Python для Node.js.
• VSCode Conventional Commits — добавляет поддержку «Соглашения о коммитах» в VSCode.
• Pyhist — утилита Python для автоматического обновления версии пакета из истории Git и создания списка изменений.
• git-mkver — инструмент для автоматического применения семантического управления версиями к репозиториям Git на основе «Соглашения о коммитах».
• Conventional Commits Next Version — инструментальная и языковая независимая утилита для расчёта следующей семантической версии на основе «Соглашения о коммитах» с учётом предыдущей версии. Поддерживает монорепозитории.
• change — инструмент для создания и обновления списка изменений с помощью «Соглашения о коммитах».
• Turbogit — инструмент командной строки, который поможет вам следовать процессу «Соглашения о коммитах».

Проекты, которые используют «Соглашение о коммитах»

• NFPM — простой упаковщик deb, rpm и apk, написанный на Go.
• yargs — всеми любимый парсер аргументов командной строки в пиратской тематике.
• istanbuljs — набор инструментов и библиотек с открытым исходным кодом для добавления тестового покрытия к вашим тестам JavaScript.
• uPortal-home и uPortal-application-framework — необязательный дополнительный пользовательский интерфейс, улучшающий Apereo uPortal.
• massive.js — библиотека доступа к данным для Node.js и PostgreSQL.
• electron — создавайте кроссплатформенные настольные приложения с помощью JavaScript, HTML и CSS.
• scroll-utility — простой в использовании пакет служебных программ прокрутки для центрирования элементов и плавной анимации.
• Blaze UI — свободный от фреймворков набор инструментов пользовательского интерфейса с открытым исходным кодом.
• Monica — система управления личными отношениями с открытым исходным кодом.
• mhy — готовый к использованию универсальный набор инструментов и среда разработки с нулевой конфигурацией.
• @tandil/diffparse — простой парсер файлов Diff (унифицированный формат diff).
• @tandil/diffsplit — простое разделение .diff и .patch на файлы.
• @thi.ng/umbrella — экосистема с широким охватом и монорепозиторий из 148+ проектов TypeScript для функциональной разработки на основе данных.
• yii2-basic-firestarter — 🔥 улучшенный шаблон приложения Yii2.
• dcyou/resume — 😎 шаблон для простого и быстрого создания онлайн-резюме.
• Nintex Forms — легко создавайте динамические онлайн-формы для сбора и отправки точных и актуальных данных.
• Tina CMS — набор инструментов с открытым исходным кодом для встраивания интерфейсного управления контентом на ваш веб-сайт.
• Belajarpython — индонезийский сайт с открытым исходным кодом по обучению программирования на Python.
• Uno Platform — создавайте мобильные, настольные и WebAssembly приложения с помощью C# и XAML. Сегодня. Открытый исходный код и профессиональная поддержка.
• Jenkins X — обеспечивает автоматизацию конвейера, встроенный GitOps и среды предварительного просмотра, чтобы помочь командам сотрудничать и ускорить доставку своего программного обеспечения в любом масштабе.

Хотите, чтобы ваш проект был в этом списке? Отправьте PR!