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

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

Пакет 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 Установка

1yarn [global] add [--dev] conventional-commits-detector

3.1.2 Использование

1npx conventional-commits-detector

В результате получим возможный тип коммитов.

3.2 conventional-recommended-bump

узнать на основе коммитов, какая версия рекомендуется.

3.2.1 Установка

1yarn [global] add [--dev] conventional-recommended-bump

3.2.2 Использование

1npx conventional-recommended-bump -p angular

Здесь angular — название пресета.

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

3.3 standard-changelog

Генерация журнала изменений с использованием соглашений о коммитах angular.

3.3.1 Установка

1yarn [global] add [--dev] standard-changelog

3.3.2 Использование

Параметры запуска можно посмотреть следующим образом:

1npx standard-changelog --help

Генерация файла журнала выполняется следующим образом:

1npx standard-changelog

или

1npx standard-changelog -i CHANGELOG.md -s

3.4 conventional-changelog-cli

Создаёт журнал изменений из метаданных git (если соглашение о коммитах отлично от angular).

3.4.1 Установка

1yarn [global] add [--dev] conventional-changelog-cli

3.4.2 Использование

1cd my-project
2npx conventional-changelog -p angular -i CHANGELOG.md -s

Если инструмент используется впервые и нужно учесть все предыдущие журналы изменений, можно выполнить команду:

1cd my-project
2npx conventional-changelog -p angular -i CHANGELOG.md -s -r 0

3.5 commitizen

Утилита, реализующая интерактивный процесс для генерации коммита.

3.5.1 Установка

1yarn [global] add [--dev] commitizen

При этом устанавливается скрипт git-cz, который мы и будем использовать для коммитов.

3.5.2 Использование

Сконфигурим формат коммитов. Для этого добавим в файл package.json команду для формирования коммитов:
```
1"config": {
2    "commitizen": {
3        "path": "cz-conventional-changelog"
4    }
5}
```
Выполнение коммитов:
```
1git cz
```

3.6 cz-customizable

Плагин для commitizen для конфигурации формы ввода сообщений. Можно задать не только типы коммитов, но и области (scopes) коммитов.

3.6.1 Установка

1yarn [global] add [--dev] cz-customizable

При этом устанавливается скрипт git-cz, который мы и будем использовать для коммитов.

3.6.2 Использование

Сконфигурим формат коммитов. Для этого добавим в файл package.json команду для формирования коммитов (заменив стандартный плагин для commitizen) и конфигурационный файл для cz-customizable:
```
1"config": {
2    "commitizen": {
3        "path": "cz-customizable"
4    },
5    "cz-customizable": {
6        "config": ".cz-config.js"
7    }
8}
```
Пример конфигурационного файл можно скачать из репозитория cz-customizable:
```
1wget https://raw.githubusercontent.com/leoforfree/cz-customizable/master/cz-config-EXAMPLE.js -O .cz-config.js
```
Выполнение коммитов:
```
1git cz
```

В качестве примера приведу следующий конфигурационный файл (https://infostart.ru/1c/articles/1016001/):

 1"use strict";
 2
 3module.exports = {
 4    // Добавим описание на русском языке ко всем типам
 5    types: [
 6        { value: "feature", name: "feature:   Добавление нового функционала" },
 7        { value: "fix", name: "fix:       Исправление ошибок" },
 8        { value: "docs", name: "docs:      Обновление документации" },
 9        { value: "test", name: "test:      Добавление тестов" },
10        { value: "refactor",
11          name:
12          "refactor:  Правки кода без исправления ошибок или добавления новых функций"
13        },
14        { value: "perf",
15          name: "perf:      Изменения направленные на улучшение производительности"
16        },
17        { value: "style",
18          name:
19          "style:     Правки по кодстайлу (табы, отступы, точки, запятые и т.д.)"
20        },
21        { value: "build",
22          name: "build:     Сборка проекта или изменения внешних зависимостей"
23        },
24        { value: "ci", name: "ci:        Настройка CI и работа со скриптами" },
25        { value: "revert", name: "revert:    Откат на предыдущие коммиты" }
26    ],
27
28    // Область. Она характеризует фрагмент кода, которую затронули изменения
29    scopes: [
30        { name: "Кэш" },
31        { name: "ФормаОсновная" },
32        { name: "Валидация" },
33        { name: "АвтоматическоеТестирование"},
34        { name: "Отчеты" },
35        { name: "ПервыйЗапуск" },
36        { name: "ЗащитаМодуля" },
37        { name: "ТребованияКПроизводительности" },
38        { name: "ХранениеДанных" },
39        { name: "API" }
40    ],
41
42    // Возможность задать спец ОБЛАСТЬ для определенного типа коммита (пример для 'fix')
43    /*
44      scopeOverrides: {
45      fix: [
46      {name: 'style'},
47      {name: 'e2eTest'},
48      {name: 'unitTest'}
49      ]
50      },
51    */
52
53    // Поменяем дефолтные вопросы
54    messages: {
55        type: "Какие изменения вы вносите?",
56        scope: "\nВыберите ОБЛАСТЬ, которую вы изменили (опционально):",
57        // Спросим если allowCustomScopes в true
58        customScope: "Укажите свою ОБЛАСТЬ:",
59        subject: "Напишите КОРОТКОЕ описание:\n",
60        body:
61        'Напишите ПОДРОБНОЕ описание (опционально). Используйте "|" для новой строки:\n',
62        breaking: "Список BREAKING CHANGES (опционально):\n",
63        footer:
64        "Место для мета данных (тикетов, ссылок и остального). Например: SECRETMRKT-700, SECRETMRKT-800:\n",
65        confirmCommit: "Вас устраивает получившийся коммит?"
66    },
67
68    // Разрешим собственную ОБЛАСТЬ
69    allowCustomScopes: true,
70
71    // allowBreakingChanges: false, // Запрет на Breaking Changes
72    // askForBreakingChangeFirst : true, // default is false
73    allowBreakingChanges: ['feat', 'fix'],
74
75    // skip any questions you want
76    //skipQuestions: ['body'],
77
78    breaklineChar: '|', // It is supported for fields body and footer.
79
80    // Префикс для нижнего колонтитула
81    footerPrefix : 'ISSUES CLOSED:',
82
83
84    // limit subject length
85    subjectLimit: 72,
86};

3.7 conventional-github-releaser

Утилита, создающая новый выпуск на GitHub на основе метаданных git.

3.7.1 Установка

1yarn [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.
Создание релиза с определённым пресетом:
```
1conventional-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