Автоматическая генерация Chagelog
Давайте разберемся, как автоматически генерировать журнал изменений в ваших проектах node.js. Также рассмотрим соглашения о версиях и коммитах.
Цель этой статьи — рассказать об общепринятых соглашениях в коммитах, версиях и описать принципы автоматической генерации changelog на их основе.
Для начала зададимся вопросом, для чего нам нужен changelog:
- для внутренней документации приватного репозитория;
- для документации общедоступного репозитория;
- для ведения журнала, предназначенног для пользователей вашей библиотеки.
Если вы создаете changelog приватного репозитория и пубилкуете его в общем доступу, следует убедиться, что в нем нет приватной информации, например ссылок на приватный репозитории.
Semver
Semver (семантическое управление версиями) — это формальное соглашение для определения номера версии новых выпусков программного обеспечения.
Проект, использующий семантическое управление версиями, объявляет основной номер версии (major), дополнительный номер версии (minor) и номер исправления (patch) для каждого выпуска.
Например, строка версии 1.2.3 указывает на основную версию под номером 1, дополнительную версию под номером 2 и исправление под номером 3.
Семантическое управление версиями помогает пользователям программного обеспечения понять серьезность изменений в каждом новом дистрибутиве.
Описание версий:
- MAJOR version — меняется при внесении несовместимых изменений в API.
- MINOR version — меняется, когда вы добавляете функциональность с обратной совместимостью.
- PATCH version — меняется, когда вы делаете исправления ошибок с обратной совместимостью.
Conventional Commits
Conventional Commits — соглашение по написанию информативных сообщений коммитов. Соблюдение этого набора правил помогает создать понятную, наглядную историю изменений кодовой базы.
Формат commit сообщений:
<type>[optional scope]: <description> [optional body] [optional footer(s)]
Структура сообщения коммита по спецификации Conventional Commits:
- Type. Это первая часть сообщения, которая чётко указывает на категорию действий, выполненных в этом коммите. Основные типы:
- feat — добавление новой функциональности;
- fix — исправление ошибок;
- refactor — изменение кода без изменения функциональности;
- chore — автоматика;
- docs — документация;
- style — оформление кода;
- perf — изменения, улучшающие производительность, без изменения функциональности;
- test — изменения, связанные с напианием тестов.
- Scope. После типа коммита можно указать область — то есть дополнительную контекстную информацию. Она характеризует фрагмент кода, которую затронули изменения.
- Description. Должно быть лаконичным и чётким, обычно не превышает 50 символов. Оно должно начинаться с маленькой буквы и описывать суть изменений.
- Body. Тело сообщения предоставляет подробное описание изменений. Обычно идёт после пустой строки после заголовка.
- Footer. В подвале указывается дополнительная информация о коммите — кто проверил, одобрил и т.д.
Стандарт Conventional Commits способствует улучшению управления версиями и упрощает процесс работы с кодом.
Standard‑version / Release‑please
Standard‑version — это утилита для автоматизации процесса выпуска версий и генерации файла изменений.
Если ваш проект находится на github, используйте Release‑please.
Принцип работы: нужно следовать спецификации Conventional Commits в репозитории. Когда будет готова к выпуску, запустить standard‑version.
Standard‑version выполнит следующее:
- Получит текущую версию репозитория, если не найдёт её в определённых файлах, вернётся к последнему тегу git.
- Вычислит новую версию на основе коммитов.
- Сгенерирует файл изменений на основе коммитов.
- Создаст новый коммит, включая изменённые файлы и обновлённый файл изменений.
- Создаст новый тег с номером новой версии.
Генерация changelog
Установка standard‑version:
npm i ‑‑save‑dev standard‑version
Пример настройки быстрых npm комманд, package.json:
{ "scripts": { "release": "standard‑version", "release:patch": "standard‑version ‑‑release‑as patch", "release:minor": "standard‑version ‑‑release‑as minor", "release:major": "standard‑version ‑‑release‑as major" } }
После выполенния работы над задачей, выполните коммит в соответствие с Conventional Commits.
Сообщения, указанные вне этого формата, в changelog попадать не будут.
Примеры сообщений в коммите:
feat: Добавлен новый компонент
fix: Испарвлены ошибки в компоненте
docs: Обновлена документация по компоненту
Пример с дополнительным описанием, футером и ссылкой на задачу:
feat: Добавлен новый компонент Дополнительное описание BREAKING CHANGE: Удален старый компонент, пожалйста, перепише ваш код на работу с новым компонентом finish #5
У себя в проекте вместо привычного ref для ссылок на задачи мы используем клюевое слово finish, которое является триггером для уведомелния задачника о том, что задача решена.
Больше примеров смотрите в Conventional Commits.
В merge request укажите один тип: fix, feat, docs и т.п.
В одном сообщении нельзя указывать несколько типов, поэтому это не будте работать с squash commits.
Мы рекомендуем ограничить область действия каждого PR / MR одной общей функцией или исправлением.
Выполнить смену версии, сгенерировать CHANGELOG.md и закоммитить изменения:
npx standard‑version
Для github вместо Conventional Commits надо использовать Release‑please, который поддерживает работу со squash и позволяет указать несколько изменений в одном сообщении коммита.
Заключение
Используя общепринятые соглашения о формате комменатриев Conventional Commits, вы упростите разным командам разработки чтение истории коммитов. Также это позволит вам использовать инструменты для автоматизации работы с историей коммитов, например такие как генерторы changelog.
При создании MR (PR) с опцией squash основной комменатрий следует писать в основном сообщении запроса на слияние.
Standard‑version в отличие release‑please не имеет поддержки разбора squash коммитов. Это следует иметь ввиду и указывать в итоговом тексте коммита соответсвующее сообщение, которое должно попасть в changelog.