IT Developer IT Developer 10.11.2024

Автоматическая генерация Chagelog

Давайте разберемся, как автоматически генерировать журнал изменений в ваших проектах node.js. Также рассмотрим соглашения о версиях и коммитах.

Цель этой статьи — рассказать об общепринятых соглашениях в коммитах, версиях и описать принципы автоматической генерации changelog на их основе.

Для начала зададимся вопросом, для чего нам нужен changelog:

  • для внутренней документации приватного репозитория;
  • для документации общедоступного репозитория;
  • для ведения журнала, предназначенног для пользователей вашей библиотеки.

Если вы создаете changelog приватного репозитория и пубилкуете его в общем доступу, следует убедиться, что в нем нет приватной информации, например ссылок на приватный репозитории.

Semver

Semver (семантическое управление версиями) — это формальное соглашение для определения номера версии новых выпусков программного обеспечения.

Проект, использующий семантическое управление версиями, объявляет основной номер версии (major), дополнительный номер версии (minor) и номер исправления (patch) для каждого выпуска.

Например, строка версии 1.2.3 указывает на основную версию под номером 1, дополнительную версию под номером 2 и исправление под номером 3.

Семантическое управление версиями помогает пользователям программного обеспечения понять серьезность изменений в каждом новом дистрибутиве.

Описание версий:

  1. MAJOR version — меняется при внесении несовместимых изменений в API.
  2. MINOR version — меняется, когда вы добавляете функциональность с обратной совместимостью.
  3. PATCH version — меняется, когда вы делаете исправления ошибок с обратной совместимостью.

Conventional Commits

Conventional Commits — соглашение по написанию информативных сообщений коммитов. Соблюдение этого набора правил помогает создать понятную, наглядную историю изменений кодовой базы.

Формат commit сообщений:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Структура сообщения коммита по спецификации Conventional Commits:

  1. Type. Это первая часть сообщения, которая чётко указывает на категорию действий, выполненных в этом коммите. Основные типы:
    • feat — добавление новой функциональности;
    • fix — исправление ошибок;
    • refactor — изменение кода без изменения функциональности;
    • chore — автоматика;
    • docs — документация;
    • style — оформление кода;
    • perf — изменения, улучшающие производительность, без изменения функциональности;
    • test — изменения, связанные с напианием тестов.
  2. Scope. После типа коммита можно указать область — то есть дополнительную контекстную информацию. Она характеризует фрагмент кода, которую затронули изменения.
  1. Description. Должно быть лаконичным и чётким, обычно не превышает 50 символов. Оно должно начинаться с маленькой буквы и описывать суть изменений.
  2. Body. Тело сообщения предоставляет подробное описание изменений. Обычно идёт после пустой строки после заголовка.
  3. Footer. В подвале указывается дополнительная информация о коммите — кто проверил, одобрил и т.д.

Стандарт Conventional Commits способствует улучшению управления версиями и упрощает процесс работы с кодом.

Standard‑version / Release‑please

Standard‑version — это утилита для автоматизации процесса выпуска версий и генерации файла изменений.

Если ваш проект находится на github, используйте Release‑please.  

Принцип работы: нужно следовать спецификации Conventional Commits в репозитории. Когда будет готова к выпуску, запустить standard‑version.

Standard‑version выполнит следующее:

  1. Получит текущую версию репозитория, если не найдёт её в определённых файлах, вернётся к последнему тегу git.
  2. Вычислит новую версию на основе коммитов.
  3. Сгенерирует файл изменений на основе коммитов.
  4. Создаст новый коммит, включая изменённые файлы и обновлённый файл изменений.
  5. Создаст новый тег с номером новой версии.

Генерация 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.

Цитаты от разработчиков Conventional 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.