Наверное, перед каждым разработчиком вставал вопрос о том, какую версию присвоить своему проекту после очередного внесенного в него изменения. 1.0.1? Или 1.1.0? Делать это вручную довольно нудно. В какой-то момент можно просто забыть о том, что версию проекта вообще-то нужно было бы поднять. А в случае командной разработки надо еще следить за тем, чтобы все разработчики ответственно следили за обновлением версии, да еще и нужно остерегаться возможных коллизий, чтобы версии разных разработчиков случайно не пересеклись.
Однако если ваш проект хранится в репозитории на GitHub, то автоматизировать версионирование не составит вам особого труда. Достаточно настроить небольшой Workflow, который будет запускать замечательный инструмент от Google под названием Release Please. С помощью него мы одним выстрелом убьем сразу трех зайцев:
- Автоматизируем версионирование
- Добавим в проект файл CHANGELOG.MD, в который автоматически будет записываться история внесенных изменений
- Автоматизируем выпуск релизов
Release Please сделает всю грязную работу за нас, а в конце сформирует pull request с изменениями, которые мы позже примем в проект.
Все, что потребуется от нас, это соблюдать соглашение о коммитах.
Соглашение о коммитах
Желательно ознакомиться с первоисточником, тем более что он полностью переведен на русский язык.
Но если коротко, то сообщение каждого коммита должно начинаться с определенного типа:
fix - если мы исправили в проекте ошибку. Например:
fix: Исправлена ошибка при проведении документа установки цен
Такие коммиты будут повышать номер патча в вашей версии: 0.0.1, 0.0.2, 0.0.3 и т.д.
feat - если мы добавили в проект новый функционал:
feat: Добавлена возможность выбора валюты отчета
Такие коммиты будут повышать минорную версию: 0.1.0, 0.2.0, 0.3.0 и т.д.
Встает вопрос когда и как повышать мажорную версию проекта - 1.0.0, 2.0.0, 3.0.0? Если следовать все тому же соглашению, то повышать мажорную версию нужно только тогда, когда в ваш проект внесены "обратно несовместимые изменения", т.е. когда конечному пользователю просто обновиться на новую версию будет недостаточно - придется еще что-то менять и перенастраивать. А выпустить такую версию можно очень просто: достаточно после типа добавить восклицательный знак (!). Например:
feat!: Реализована новая версия API
Альтернативный вариант мажорного обновления - это использование в теле коммита словосочетания "BREAKING CHANGE":
feat: Реализована новая версия API
BREAKING CHANGE: Старая версия API более не поддерживается
Помимо 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 (подробнее), поэтому вполне возможно, что вы сможете воспользоваться этим инструментом так, как это подойдет под ваше окружение.
На этом все. Спасибо за внимание!
