Семантическое версионирование. Conventional Changelog

Обновлено 2023-07-19 5 мин. для прочтения

Пакет 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 должен быть включён в новую версию.

Links to this note

Education Programming