Автоматическое версионирование проектов в GitHub Actions

Наверное, перед каждым разработчиком вставал вопрос о том, какую версию присвоить своему проекту после очередного внесенного в него изменения. 1.0.1? Или 1.1.0? Делать это вручную довольно нудно. В какой-то момент можно просто забыть о том, что версию проекта вообще-то нужно было бы поднять. А в случае командной разработки надо еще следить за тем, чтобы все разработчики ответственно следили за обновлением версии, да еще и нужно остерегаться возможных коллизий, чтобы версии разных разработчиков случайно не пересеклись.

Однако если ваш проект хранится в репозитории на GitHub, то автоматизировать версионирование не составит вам особого труда. Достаточно настроить небольшой Workflow, который будет запускать замечательный инструмент от Google под названием Release Please. С помощью него мы одним выстрелом убьем сразу трех зайцев:

1. Автоматизируем версионирование
2. Добавим в проект файл CHANGELOG.MD, в который автоматически будет записываться история внесенных изменений
3. Автоматизируем выпуск релизов

Release Please сделает всю грязную работу за нас, а в конце сформирует pull request с изменениями, которые мы позже примем в проект.

Все, что потребуется от нас, это соблюдать соглашение о коммитах.

Соглашение о коммитах

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

Но если коротко, то сообщение каждого коммита должно начинаться с определенного типа:

fix - если мы исправили в проекте ошибку. Например:

 
Такие коммиты будут повышать минорную версию: 0.1.0, 0.2.0, 0.3.0 и т.д.

Встает вопрос когда и как повышать мажорную версию проекта - 1.0.0, 2.0.0, 3.0.0? Если следовать все тому же соглашению, то повышать мажорную версию нужно только тогда, когда в ваш проект внесены "обратно несовместимые изменения", т.е. когда конечному пользователю просто обновиться на новую версию будет недостаточно - придется еще что-то менять и перенастраивать. А выпустить такую версию можно очень просто: достаточно после типа добавить восклицательный знак (!). Например:

Альтернативный вариант мажорного обновления - это использование в теле коммита словосочетания "BREAKING CHANGE":

Помимо fix и feat мы можем использовать и другие типы в сообщениях коммитов: docs, ci, chore, test и другие, но на версионирование такие сообщения уже влиять не будут - они нужны скорее как сигналы.

Практический пример

Перейдем от слов к действию. Рассмотрим весь процесс на реальном примере - в расширении для интеграции 1С и Telegram затесалась ошибка, после исправления которой мы хотим автоматически поднять версию релиза с 0.12.0 на 0.12.1.

Перед тем как взяться за исправление ошибки, настроим Workflow.

Разработка расширения ведется в EDT, настроена работа с репозиторием в GitHub. Все исходники нашего проекта, которые в последствии и выгружаются в репозиторий, хранятся по следующему пути:

Именно с исходниками мы и будем работать, но только сделаем это не через EDT, а с помощью VS Code. Предварительно создадим отдельную ветку для настройки CI в GitHub, переключимся на эту ветку, и уже после этого откроем каталог 1c-telegram-bot-management в VS Code. 

Далее делаем следующее:

Создаем каталог .github\workflows, в котором инициализируем файл release-build.yml со следующим содержимым:

on:
  push:
    branches: [main]
  workflow_dispatch:

permissions:
  contents: write
  pull-requests: write

name: release-please

jobs:
  release-please:
    runs-on: ubuntu-latest
    steps:
      - uses: googleapis/release-please-action@v4
        with:
          token: ${{ secrets.MY_RELEASE_PLEASE_TOKEN }}

Именно этот файл и будет у нас запускаться в GitHub Actions. Вызываться он будет автоматически при каждом push в ветку main или же при ручном вызове (за это отвечает строчка workflow_dispatch). Этим файлом выполняется лишь одно действие: запускается release-please-action. Под это же действие мы выдаем права на внесение изменений и создание pull request (секция permissions), а также передаем токен авторизации.

Далее создаем еще два файла специально под настройки Release Please: 

.release-please-manifest.json, в котором указываем текущую версию нашего проекта:

{".":"0.12.0"}

И release-please-config.json, в котором прописываем настройки Release Please:

{
  "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json",
  "release-type": "simple",
  "extra-files": [
    "Управление_торговлей_демо_Telegram.TelegramBotManagement/src/Configuration/Configuration.mdo"
  ],
  "packages": {
    ".": {}
  }
}

На файле release-please-config.json остановимся чуть подробнее. Здесь мы указали две важные настройки:

• release-type - Release Please из под коробки поддерживает версионирование проектов на самых разных стеках - node, php, dart, python и многих других. Конечно, 1С в этом списке нет, поэтому мы выбираем тип релиза simple.

• extra-files - так как Release Please сам не знает, где в 1С хранится информация о версии проекта (в данном случае речь о версии расширения), то путь к этому файлу нужно указать вручную. Именно по пути Управление_торговлей_демо_Telegram.TelegramBotManagement/src/Configuration/Configuration.mdo и содержится информация корневого узла расширения, в том числе и его версия. Кроме того, внутри этого файла нужно с помощью специального комментария (<!-- x-release-please-version -->) указать конкретную позицию, где указана версия. В последствии Release Please с помощью регулярного выражения разберет эту строчку и заменит номер версии на новый.

С полным описанием доступных свойств файла release-please-config.json можно ознакомиться здесь.

В итоге у нас должна получиться такая картина:

Коммитим изменения, и мерджим с основной веткой.

Теперь создаем новую ветку для того, чтобы исправить ошибку. Возвращаемся в EDT, переключаемся на новую ветку, исправляем ошибку, и вот настал момент истины - коммитим и пушим изменения:



Далее создаем pull request и мерджим изменения в основную ветку. Если все сделано правильно, то сразу после этого у нас автоматически срабатывает GitHub Action:



А в результате его исполнения у нас появляется автоматический pull request:



Смотрим, какие файлы были изменены:



Отлично! Изменен номер версии расширения, плюс создан новый файл CHANGELOG.MD с историей изменений.



Принимаем pull request и смотрим дальше: у нас появился автоматический релиз!



Ну и напоследок возвращаемся в EDT, переключаемся на основную ветку, получаем изменения и видим - версия действительно обновилась, как мы того и хотели:



Ложка дегтя

Есть два очевидных недостатка. Во-первых, хотелось бы, чтобы при создании релиза из исходников EDT автоматически собирался файл .cfe. К сожалению, пока не удалось найти способ сделать это внутри GitHub Actions без установленной платформы. Буду рад, если кто подскажет, как это можно было бы реализовать. Или же можно все-таки установить платформу и собрать .cfe через интерфейс командной строки.

Во-вторых, этот сценарий отлично подходит при работе в EDT, но при работе из конфигуратора (например, хранилище + Git) постоянно будет стираться обязательный комментарий напротив версии (<!-- x-release-please-version -->). Но думаю, что эту проблему вполне можно обойти с помощью OneScript.

Кроме того, Release Please доступен в виде CLI (подробнее), поэтому вполне возможно, что вы сможете воспользоваться этим инструментом так, как это подойдет под ваше окружение.

На этом все. Спасибо за внимание!