Пусть GitLab API делает скучные вещи
Я большой фанат GitLab, и я уверен, что вы тоже, если вы сразу же прочитали эту статью. Некоторое время назад я просмотрел их API, чтобы узнать о возможностях, которые он предлагает. И я обнаружил кое-что, что сэкономило мне много времени:
В этой статье вы узнаете, как автоматически обновлять примечания к выпуску с помощью GitLab API, приложив немного дисциплины и немного волшебства.
Предпосылки
Давайте начнем с некоторых базовых знаний, что такое примечание к выпуску?
Примечание к выпуску (журнал изменений) – это файл со списком изменений, внесенных в новую версию проекта. Этот файл условно называется CHANGELOG.md.
Записи журнала изменений сгруппированы в соответствии с их типологией, будь то fix, feature change, deprecation, performance, new feature или многие другие…
Для более реалистичных примеров вы можете посмотреть:
Почему обновление журнала изменений — это боль… но необходимость?
Перечисление всех изменений между двумя версиями заканчивается утомительной и раздражающей задачей. Вам нужно сопоставить (почти) каждый коммит с конкретной целью, как упомянутые чуть выше.
Это означает, что сообщения фиксации достаточно ясны, чтобы их можно было классифицировать. Но давайте будем честными, не так-то просто быть как можно более явным в каждом коммите.
Но действительно ли необходимо отслеживать эти изменения?
Что ж, если вы используете или поддерживаете пакет, используемый сообществом, это обязательно! В примечаниях к выпуску будут (частично) документированы изменения каждой версии пакета. Это один из способов представить новые функции, а также предупредить о критических изменениях. Таким образом, ваши «клиенты» будут предупреждены и адаптируют свою кодовую базу.
Журналы изменений также являются способом записи истории проекта (независимо от его вида). Наконец, если вы тесно сотрудничаете с командой продукта, это ссылка на содержание каждого нового выпуска.
Как упоминалось ранее, это скучная задача, если вы делаете это вручную. Будем надеяться, что существуют решения с использованием сторонней библиотеки, такой как semantic-release для пользователей Node, gitchangelog для Python или Commitizen для разработчиков .NET. Однако это означает настройку и поддержку плагина.
Если вы используете GitLab в качестве платформы для управления версиями кода, вам очень повезло, потому что Тануки может обновить для вас примечания к выпуску!
Предупреждение: это решение работает, только если вы используете семантическое управление версиями (например: v X.Y.Z).
GitLab API спешит на помощь!
Уверен, вы знаете, что GitLab — это не просто платформа для версий кода. Вы можете управлять отставанием своей команды, определять непрерывную интеграцию своих проектов, отслеживать производительность ваших приложений и отслеживать инфраструктуру вашей организации…
И вы также можете делать все это и многое другое с помощью GitLab API.
Что касается безопасности, многие из этих действий требуют токена аутентификации, я позволю вам выяснить, как получить такой токен с документами.
Объяснения ресурсов
Среди всех возможностей, предлагаемых API, нас интересует ресурс Repository API:
Мы будем взаимодействовать с конечной точкой журнала изменений, которая отвечает за создание записей журнала изменений между двумя версиями и вставку их в файл CHANGELOG.md.
Если этого файла нет в вашем репозитории, GitLab добавит его автоматически!
Во-первых, хорошая привычка ради вашей git-истории
Эта конечная точка GitLab использует не очень известную функцию git: Git Trailers. Они выглядят как тег, помечающий вашу фиксацию, и вам нужно предоставить их в конце зафиксировать запись следующим образом:
<commit message subject> <Commit message description - optional> Changelog: <value>
Здесь value будет обозначать категорию, которую вы хотите применить к этой фиксации, вы можете дать ей любое имя. Трейлер Changelog принимает следующие значения: added, fixed, changed, deprecated, removed, security, performance, other (Подробнее о записях журнала изменений здесь).
Таким образом, более реалистичным примером будет:
Service Layer: Refactor the BillingService Remove useless files and make some other stuff Changelog: changed
Самое главное — это использование этого Changelog: changed. Поэтому в измененном списке файла CHANGELOG.md появится новая запись.
Вы можете найти более подробную информацию об использовании git trailer с GitLab API здесь:
Мой личный совет
Надеюсь, нас не заставят использовать git trailer для каждого отправляемого коммита… Это будет утомительно.
Я придумал решение включить трейлер git только в сообщении коммита мерж-реквеста. Независимо от того, сжимаете ли вы коммиты или нет после слияния; останется только 1 единственный коммит с трейлером git и, таким образом, всего 1 запись в примечании к выпуску!
Затем небольшой скрипт для автоматизации
Прежде чем углубляться в код, вам понадобятся некоторые важные детали для запросов к GitLab API.
Во-первых, токен доступа к проекту для аутентификации при вызове GitLab API. Вы найдете все детали для его создания здесь. Этот токен должен предоставлять области действия read_api и read_repository.
Во-вторых, Project ID вашего проекта, вы можете найти его на странице Общие настройки вашего проекта.
Затем вы можете найти ниже простой скрипт nodeJS, который получает версию приложения и вызывает API GitLab:
Перед выполнением вам необходимо установить axios и dotenv с
npm i --save-dev axios dotenvилиyarn add -D axios dotenv
В качестве альтернативы, вот его версия Bash, где номер версии приложения хранится в файле VERSION.md.
Разбуди зверя!
Наконец, вы выбираете, когда скрипт должен быть запущен
Этот скрипт можно запустить в любой момент, но, конечно же, самый важный момент — сразу после создания тега. Возможны два варианта:
- Сразу после версии тега
- В конце конвейера тега CI
В своем проекте я добавил команду NPM, которая использует хук postversion и запускает скрипт на основе обновленного номера версии в package.json.
Другой вариант кажется более аккуратным. Действительно, это гарантирует, что тег, который вы создали в удаленном репозитории, запустил полный конвейер CI и компилируется, тестируется и «упаковывается». После всех этих последовательных проверок можно опубликовать примечание к выпуску.
Отсюда вы узнали следующее:
- Git Trailers — хороший способ пометить ваши коммиты (или мерж-реквесты).
- Они используются GitLab API для создания записей журнала изменений.
- Благодаря простому скрипту вы можете обновлять примечания к выпуску автоматически без каких-либо дополнительных действий.
Предупреждение об управлении версиями git
Поскольку вы можете запустить скрипт в любой версии кода (ветви), вы можете столкнуться с конфликтами. Это зависит от используемого вами управления версиями git.
Самые популярные git-управления версиями — это магистральная и Git Flow-разработка (подробнее здесь). Если вы не знакомы с этим понятием, это просто способ, которым вы версионируете свой код и обрабатываете новые изменения в конкретной среде (интеграция, подготовка, предварительная подготовка, производство).
Магистраль
Если вы работаете с транковым стилем, то нет проблем. Примечания к выпуску всегда будут обновляться в соответствии с последней опубликованной версией.
Git поток
Поскольку Git Flow разработан для нескольких веток, необходима синхронизация веток. Изменения могут быть перезаписаны и не будут отображаться в примечаниях к выпуску. Затем хитрость заключается в том, чтобы указать другой трейлер git, чтобы идентифицировать изменения между ветвями.
Основной вариант использования (представленный ниже) — исправление ошибок или оперативное исправление от master. Здесь изменения из master отмечены тегом Исправить git trailer. Поэтому коммиты с этим трейлером не будут отфильтровываться при вычислении журнала изменений для x.y+2.0 версии.
Ниже вы можете найти обновленную версию скрипта узла для вызова GitLab API. Вы заметите, что текущая ветка извлекается с использованием метода exec.
Заключить
Отслеживание изменений с помощью примечаний к выпуску должно быть НЕОБХОДИМОдля программных проектов.
Будь то для продукта или технических целей, это доказательство прозрачности. Вы должны согласиться, что это не так сложно внедрить, просто требуется дисциплина, чтобы сделать записи журнала изменений как можно более явными.
Еще раз, GitLab сияет благодаря различным возможностям, которые предлагает эта платформа; здесь с API репозитория. Вы также можете посмотреть на альтернативу GitHub, если она больше подходит для вашей ситуации.
