Управление заметками о выпуске

Как вы управляете журналом изменений или примечаниями к релизам в OSS?

Что касается меня самого, то в наши дни я не использую файл CHANGELOG и почти исключительно пользуюсь релизами на GitHub.

Для этого есть 3 основные причины:

1. Управлять сотнями репозиториев становится все сложнее.
2. GitHub Releases становится лучше
3. CHANGELOG имеет тенденцию конфликтовать в больших проектах

Примечания к релизам

GitHub имеет возможность автоматически генерировать заметки о релизах.

Эта функция суммирует заявки на исправление, которые были объединены с текущей версией. Она весьма полезна, поскольку включает в себя ссылку на каждый запрос, имя автора и список соавторов для этой версии. Если вы попытаетесь создать это самостоятельно, это будет не так просто. Больше всего мне нравится то, что эта функция официально предоставляется GitHub.

Если вы поместите .github/release.yml, он также сгенерирует отдельные разделы в соответствии с метками, прикрепленными к pull request’ам. Поскольку мне нравится формат, похожий на keep-a-changelog, я подготовил эти 6 меток:

• добавить
• изменить
• deprecate
• исправить
• удалить
• безопасность

В основном, я добавляю эти метки во время рецензирования, но даже если я забуду это сделать, я могу добавить их перед выпуском.

Ярлыки

Подготавливать эти метки для каждого репозитория вручную очень хлопотно, поэтому я автоматизировал это с помощью github-label-sync-action. Если вы поместите название, описание и цвет каждой метки в .github/labels.yml, она будет автоматически синхронизирована с GitHub.

Более того, я хотел бы автоматизировать процесс подготовки YAML-файлов этой конфигурации, поэтому я создал для этого r7kamura/github-keepachangelog-template и использую gitcp для копирования его в текущий каталог.

gitcp r7kamura/github-keepachangelog-template

Рабочие процессы

В эти дни я также использую GitHub Actions для автоматизации процесса публикации новых версий, таких как теги и релизы. Например, при использовании пакета npm мы помещаем version в manifest.json. У меня есть рабочий процесс, который обнаруживает изменение версии и автоматически создает новый тег Git, новый релиз GitHub и так далее.

Поскольку подготовка таких рабочих процессов для каждого репозитория отнимает много времени, я использую Reusable workflows и организую свои собственные рабочие процессы в r7kamura/workflows.

Это пример рабочего процесса для выпуска моего расширения VSCode из vscode-ruby-light:

name: release

on:
  push:
    branches:
      - main

jobs:
  release:
    uses: r7kamura/workflows/.github/workflows/vscode-extension-release.yml@main
    secrets:
      vsce-token: ${{ secrets.VSCE_TOKEN }}

Просто напишите это, измените поле version в package.json и git push, и это автоматически создаст новый git-тег, новый GitHub Release с автоматически сгенерированными заметками о выпуске, сборку расширения и публикацию его на VSCode marketplace.

Подведение итогов

Я написал о том, как я управляю своими заметками о выпуске.

Заметки о выпуске — это очень важный источник информации для пользователей. Однако я понимаю, что поддерживать их может быть сложно. Я хотел бы иметь возможность автоматизировать это и управлять ими без затрат.