diff --git a/config.yaml b/config.yaml index 9c6cdbe..a22b568 100755 --- a/config.yaml +++ b/config.yaml @@ -118,9 +118,11 @@ languages: - label: GitHub url: 'https://github.com/conventional-commits/conventionalcommits.org' versions: - current: v1.0.0-beta.2 + current: v1.0.0-beta.4 list: - v1.0.0-beta.2 + - v1.0.0-beta.3 + - v1.0.0-beta.4 ja: weight: 2 diff --git a/content/v1.0.0-beta.3/index.ru.md b/content/v1.0.0-beta.3/index.ru.md new file mode 100644 index 0000000..8cd1a05 --- /dev/null +++ b/content/v1.0.0-beta.3/index.ru.md @@ -0,0 +1,221 @@ +--- +draft: false +aliases: ["/ru/"] +--- + +# Conventional Commits 1.0.0-beta.3 + +## Summary + +Conventional Commits - это простое соглашение о том, как нужно писать сообщения commit'ов. +Оно описывает простой набор правил для создания понятной истории commit'ов, +а так же позволяет проще разрабатывать инструменты автоматизации, основанные на +истории commit'ов. Данное соглашение совместимо с [SemVer](http://semver.org), +описывая новые функции (features), исправления (fixes) и изменения, нарушающие +обратную совместимость (breaking changes) в сообщениях commit'ов. + +Сообщения commit'ов должны быть следующей структуры: + +--- + +``` +[optional scope]: + +[optional body] + +[optional footer] +``` +--- + +
+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). +
+Контекст (scope) может быть объявлен рядом с типом commit'а для добавления дополнительной +информации о контексте. Он должен содержаться в круглых скобках, например, `feat(parser): add ability to parse arrays`. + +## Examples + +### Сообщение 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'а без тела +``` +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 +``` + +## Specification + +Слова “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'а пустой строкой. +Подвал должен (SHOULD) содержать упоминания, касающиехся изменений в коде (такие, как номера задач, которые были решение, т.е.,`Fixes #13`). +1. Описание изменений, нарушающий обратную совместимость, должно (MUST) нахожиться в самом начале подвала (footer) или тела сообщения commit'a. +Описание изменений, нарушающий обратную совместимость, должно (MUST) состоять из текста `BREAKING CHANGE`, пробела и двоеточия. +1. Описание изменений, нарушающий обратную совместимость должно включаьб то, что изменилось в API. Например, +_BREAKING CHANGE: environment variables now take precedence over config files._ +1. Подвал (footer) должен (MUST) включать только внешние ссылки, номера задач (issue) и прочу мета-информацию, +которая относиться к изменениям, нарушающим обратную совместимость (BREAKING CHANGE). +1. Типы отличные от `feat` и `fix` могут (MAY) быть использованы в ваших commit'ах. + +## Почему нужно использовать 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 Commit вдохновлены и основаны на +[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-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 Commit спецификации. +Используется для 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): набор инструментов и окружение для разработки с нулевой конфигурацией, котовое работать из коробки. + +[![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). \ No newline at end of file