<rmcreative>

RSS

О генерации CHANGELOG из коммитов

22 июля

Адель, автор плагина по PhpStorm для Laravel пишет:

Вообще не понимаю идею генерации changelog из гит коммитов. Она везде проскакивает. Есть даже готовая команда в шаблоне для плагинов от JetBrains. Это для совсем уж ленивых. Текст в коммите - для команды продукта, чтобы было понятно что и как конкретно сделано. Текст changelog - для юзеров. Если юзеры - это такие же php-програмисты, то наверно им будет понятен текст коммитов для юзаемого ими php-пакета.

Но как только аудитория и команда не совпадает по языку, фреймворку и т.д., то ситуация становится совсем другой. Всем интересна фича сама по себе, а не как она была сделана. И уж тем более всем по барабану на рефакторинги или оптимизации.

Другой вариант - генерить из тасков багтрекера. Это уже чуть более солидно, так делают сами JetBrains. Пример. Но это тоже для ленивых. Мало кому из юзеров интересно такое читать. Поэтому они делают более user-friendly страницы типа этой - https://www.jetbrains.com/phpstorm/whatsnew/

Каждый раз перед релизом я копирую текст всех коммитов с предыдущего релиза в одно место и пишу из них текст changelog для новой версии. Делаю текст хоть немного более маркетинговым, более понятным для юзеров. Хочу пробовать ещё видео записывать для каждого апдейта. Считаю это достаточно важным. Не стоит лениться сообщать юзерам о фичах более красиво, если вам или, хотя бы, им не плевать на продукт.

Идея генерации — она понятная, но не работает. Идея сама возникла от нежелания писать руками осмысленный CHANGELOG. А если осмысленности нет, то и аннотации к коммитам будут плохие, если вообще будут.

Про «для юзеров» верно, но в меньшей степени проблема, чем неосознанность. И тоже есть особенности. Совпадение языка не делает генерируемый CHANGELOG понятным.

Именно поэтому в Yii с самого начала писали CHANGELOG руками и просили добавлять строчку для CHANGELOG в pull request. Для повышения осознанности.

Комментарии RSS

  1. №12267
    Anatoly
    Anatoly 23 июля 2022 г., 11:27:06

    На гитхабе есть автогенерация и она прекрасно работает: docs.github.com/en/repositories/releasing-projects-on-github/automatically-generated-release-notes#about-automatically-generated-release-notes

    А повышение осознанности производится путём задания человекопонятных названий для pull request – двойная выгода.

    писали CHANGELOG руками и просили добавлять строчку для CHANGELOG в pull request

    Это плохой вариант, т.к. постоянно возникают конфликты при мерже.

  1. Почта опубликована не будет.

  2. Можно использовать синтаксис Markdown или HTML.

  3. Введите ответ в поле. Щёлкните, чтобы получить другую задачу.