Семантическое версионирование. Conventional Changelog
- Пакет Conventional Changelog представляет собой набор утилит.
- Их можно использовать как вместе, так и по отдельности.
- Также можно задавать свой рабочий процесс.
Содержание
1 Репозитории
- Основной монорепозиторий: https://github.com/conventional-changelog/conventional-changelog
2 Список утилит
2.1 Основные утилиты проекта
- conventional-changelog-cli — утилита командной строки.
- standard-changelog — утилита командной строки для формата коммитов angular.
- conventional-github-releaser — создание нового релиза на GitHub из метаданных git.
- conventional-recommended-bump — узнать на основе коммитов, какая версия рекомендуется.
- conventional-commits-detector — определить, какое соглашение о коммитах использует репозиторий.
- commitizen — утилита, задающая интерфейс к написанию коммитов.
- commitlint — проверка правильности текста коммита.
2.2 Дополнительные утилиты
- cz-customizable — плагин для
commitizen
для конфигурации формы ввода сообщений. - cz-customizable-ghooks — интеграция
cz-customizable
сghooks
илиhusky
, чтобы использовать единую конфигурацию для генерации и проверки сообщений коммитов .
3 Настройка утилит
3.1 conventional-commits-detector
- Определить, какое соглашение о коммитах используется в репозитории.
3.1.1 Установка
yarn [global] add [--dev] conventional-commits-detector
3.1.2 Использование
npx conventional-commits-detector
В результате получим возможный тип коммитов.
3.2 conventional-recommended-bump
узнать на основе коммитов, какая версия рекомендуется.
3.2.1 Установка
yarn [global] add [--dev] conventional-recommended-bump
3.2.2 Использование
npx conventional-recommended-bump -p angular
Здесь angular
— название пресета.
В результате получим уровень, на который изменяется версия.
3.3 standard-changelog
Генерация журнала изменений с использованием соглашений о коммитах angular.
3.3.1 Установка
yarn [global] add [--dev] standard-changelog
3.3.2 Использование
Параметры запуска можно посмотреть следующим образом:
npx standard-changelog --help
Генерация файла журнала выполняется следующим образом:
npx standard-changelog
или
npx standard-changelog -i CHANGELOG.md -s
3.4 conventional-changelog-cli
Создаёт журнал изменений из метаданных git (если соглашение о коммитах отлично от angular).
3.4.1 Установка
yarn [global] add [--dev] conventional-changelog-cli
3.4.2 Использование
cd my-project
npx conventional-changelog -p angular -i CHANGELOG.md -s
Если инструмент используется впервые и нужно учесть все предыдущие журналы изменений, можно выполнить команду:
cd my-project
npx conventional-changelog -p angular -i CHANGELOG.md -s -r 0
3.5 commitizen
Утилита, реализующая интерактивный процесс для генерации коммита.
3.5.1 Установка
yarn [global] add [--dev] commitizen
При этом устанавливается скрипт git-cz
, который мы и будем использовать для коммитов.
3.5.2 Использование
- Сконфигурим формат коммитов. Для этого добавим в файл
package.json
команду для формирования коммитов:"config": { "commitizen": { "path": "cz-conventional-changelog" } }
- Выполнение коммитов:
git cz
3.6 cz-customizable
- Плагин для
commitizen
для конфигурации формы ввода сообщений. Можно задать не только типы коммитов, но и области (scopes) коммитов.
3.6.1 Установка
yarn [global] add [--dev] cz-customizable
- При этом устанавливается скрипт
git-cz
, который мы и будем использовать для коммитов.
3.6.2 Использование
- Сконфигурим формат коммитов. Для этого добавим в файл
package.json
команду для формирования коммитов (заменив стандартный плагин дляcommitizen
) и конфигурационный файл дляcz-customizable
:"config": { "commitizen": { "path": "cz-customizable" }, "cz-customizable": { "config": ".cz-config.js" } }
- Пример конфигурационного файл можно скачать из репозитория cz-customizable:
wget https://raw.githubusercontent.com/leoforfree/cz-customizable/master/cz-config-EXAMPLE.js -O .cz-config.js
- Выполнение коммитов:
git cz
- В качестве примера приведу следующий конфигурационный файл (https://infostart.ru/1c/articles/1016001/):
"use strict"; module.exports = { // Добавим описание на русском языке ко всем типам types: [ { value: "feature", name: "feature: Добавление нового функционала" }, { value: "fix", name: "fix: Исправление ошибок" }, { value: "docs", name: "docs: Обновление документации" }, { value: "test", name: "test: Добавление тестов" }, { value: "refactor", name: "refactor: Правки кода без исправления ошибок или добавления новых функций" }, { value: "perf", name: "perf: Изменения направленные на улучшение производительности" }, { value: "style", name: "style: Правки по кодстайлу (табы, отступы, точки, запятые и т.д.)" }, { value: "build", name: "build: Сборка проекта или изменения внешних зависимостей" }, { value: "ci", name: "ci: Настройка CI и работа со скриптами" }, { value: "revert", name: "revert: Откат на предыдущие коммиты" } ], // Область. Она характеризует фрагмент кода, которую затронули изменения scopes: [ { name: "Кэш" }, { name: "ФормаОсновная" }, { name: "Валидация" }, { name: "АвтоматическоеТестирование"}, { name: "Отчеты" }, { name: "ПервыйЗапуск" }, { name: "ЗащитаМодуля" }, { name: "ТребованияКПроизводительности" }, { name: "ХранениеДанных" }, { name: "API" } ], // Возможность задать спец ОБЛАСТЬ для определенного типа коммита (пример для 'fix') /* scopeOverrides: { fix: [ {name: 'style'}, {name: 'e2eTest'}, {name: 'unitTest'} ] }, */ // Поменяем дефолтные вопросы messages: { type: "Какие изменения вы вносите?", scope: "\nВыберите ОБЛАСТЬ, которую вы изменили (опционально):", // Спросим если allowCustomScopes в true customScope: "Укажите свою ОБЛАСТЬ:", subject: "Напишите КОРОТКОЕ описание:\n", body: 'Напишите ПОДРОБНОЕ описание (опционально). Используйте "|" для новой строки:\n', breaking: "Список BREAKING CHANGES (опционально):\n", footer: "Место для мета данных (тикетов, ссылок и остального). Например: SECRETMRKT-700, SECRETMRKT-800:\n", confirmCommit: "Вас устраивает получившийся коммит?" }, // Разрешим собственную ОБЛАСТЬ allowCustomScopes: true, // allowBreakingChanges: false, // Запрет на Breaking Changes // askForBreakingChangeFirst : true, // default is false allowBreakingChanges: ['feat', 'fix'], // skip any questions you want //skipQuestions: ['body'], breaklineChar: '|', // It is supported for fields body and footer. // Префикс для нижнего колонтитула footerPrefix : 'ISSUES CLOSED:', // limit subject length subjectLimit: 72, };
3.7 conventional-github-releaser
- Утилита, создающая новый выпуск на GitHub на основе метаданных git.
3.7.1 Установка
yarn [global] add [--dev] conventional-github-releaser
3.7.2 Использование
- Создайте новый токен для для доступа к github
- Токен создаётся по ссылке https://github.com/settings/tokens/new.
- Права для токена:
public_repo
илиrepo
. - Обязательно сразу скопируйте свой новый токен личного доступа. Нет возможности получить доступ к его значению ещё раз.
- Установите созданный токен как значение переменной окружения
CONVENTIONAL_GITHUB_RELEASER_TOKEN
. - Также можно указать свой токен аутентификации с помощью флага
-t
или--token
.
- Создание релиза с определённым пресетом:Здесь
conventional-github-releaser -p angular
angular
— один из пресетов :angular
,atom
,codemirror
,ember
,eslint
,express
,jquery
,jscs
,jshint
.
4 Примерный рабочий процесс
Внести изменения.
Зафиксировать эти изменения.
Проверить состояние Travis CI.
Изменить версию в
package.json
.Закоммитить файлы:
package.json
.Задать метку (tag).
Выложить на удалённый репозиторий (
push
).Сделать релиз (
conventional-github-releaser
)Причина, по которой вы должны зафиксировать изменения и создать метку после выполнения
standard-changelog
заключается в том, чтоCHANGELOG.md
должен быть включён в новую версию.