Автоматизация changelog и её пределы

Автоматизация changelog работает, когда она автоматизирует сбор, классификацию и публикацию, и останавливается на отборе и формулировке. Автоматизируйте всё — и вы доставляете отформатированный git log; не автоматизируйте ничего — и changelog пишется рывками, по памяти, перед релизами. Полезный вопрос в том, какие части автоматизировать, а не сколько.

Проекты автоматизации changelog проваливаются в одном из двух направлений, и оба предсказуемы уже с первой встречи по дизайну. Автоматизируйте слишком мало, и changelog становится документом, который кто-то должен обновлять, что означает, что он обновляется рывками, кем бы ни выпала короткая соломинка. Автоматизируйте слишком много, и он превращается в отформатированный git log: полный, точный, и никем не читаемый.

Какие части changelog следует автоматизировать?

Три из четырёх шагов. Сбор и публикацию полностью; классификацию как первый проход с человеческим переопределением; отбор и формулировку никогда.

Сбор. Извлечение изменений из места, где они происходят (коммиты, PR, тикеты), и помещение их в список. Автоматизируйте это полностью. Люди плохи в этом, это утомительно, и это шаг, который пропускается под дедлайном. Conventional commits или метки PR — обычное сырьё.

Классификация. Решение, является ли что-то Added, Fixed, Changed, Deprecated, Removed или Security. Автоматизируйте первый проход из типа коммита или метки PR, и позвольте человеку переопределить. Точность здесь около восьмидесяти процентов только из метаданных, а неверные двадцать процентов концентрируются именно на записях, которые важны, потому что двусмысленность коррелирует со значимостью.

Отбор и формулировка. Решение о том, что должен узнать читатель, и как это сказать. Не автоматизируйте это. Это вся ценность артефакта. Всё остальное — логистика.

Публикация. Доставка готовых записей на страницу, в ленту, письмо, in-app виджет, канал Slack. Автоматизируйте полностью, и из одного источника. Сюда на самом деле уходит большая часть ручных усилий, и почти никто это не считает. Это также шаг, который может сообщить человеку, попросившему изменение, что оно выпущено, что и есть вся суть замыкания петли обратной связи со стороны changelog. У почтовой половины этого шага своя форма, в шаблоне письма об обновлении продукта.

Последний пункт стоит обдумать. Команды склонны видеть changelog как проблему письма, а затем тратят большую часть времени на распространение: копирование записей в инструмент почты, переформатирование для in-app, вставку в Slack, обновление страницы документации. Написание занимает час. Копирование занимает час на каждый релиз, навсегда, и это часть, которую должна иметь машина.

Что происходит, когда граница сдвигается?

Сдвиньте её вверх, и получите дамп git. Полная автоматизация из коммитов производит bump deps, fix flaky test, wip и address review comments перед клиентами. Каждая команда, сделавшая это, потом добавила фильтр, и фильтр — это шаг отбора, повторно введённый под другим именем, с худшей эргономикой.

Сдвиньте её вниз, и получите рывки. Полностью ручной сбор означает, что записи пишутся по памяти в момент релиза. Это тот режим, о котором предупреждает Keep a Changelog с самого начала, и он тихо ухудшается: changelog выглядит поддерживаемым вплоть до той самой недели, когда ни у кого не было времени.

Как выглядит pipeline автоматизации changelog?

Четыре шага, с ровно одними человеческими воротами, размещёнными там, где черновик становится публичным.

1. При merge выводите черновик записи из PR: тип из метки или префикса коммита, заголовок как первый черновик, ссылка обратно на PR, зафиксированный автор. Поместите его в неопубликованную корзину.
2. Любой может редактировать любой черновик в любой момент, и редактирование дёшево. Большинство получает одну переписанную строку.
3. Выпуск релиза требует, чтобы каждая запись в корзине была либо отредактирована, либо явно помечена как внутренняя. Эти ворота — весь дизайн. Без них черновики выпускаются неотредактированными в загруженную неделю.
4. Публикация — это разветвление из выпущенного набора: публичная страница, лента, письмо, виджет, пост в Slack. Один источник, несколько отображений, без копирования.

Шаг 3 — единственное место, где нужен человек, и он занимает около десяти минут на релиз, как только черновики приличные. Там, где вовлечён запрос клиента, черновик также несёт issue, который он закрывает, что позволяет шагу 4 уведомить попросившего; шаблон запроса функции спроектирован так, чтобы эта ссылка пережила процесс. Где этот шаг стоит в общем потоке релиза, рассказывает статья процесс управления релизами.

Что автоматизация требует от ваших данных?

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

Записи должны быть структурированы: тип, дата, версия или идентификатор релиза, аудитория, тело и ссылка. Тогда файл, страница, лента и письмо — все представления. Этот структурный момент — единственное, что стоит сделать правильно перед выбором инструмента, потому что это то, что нельзя дёшево добавить позже. Ничто из этого не работает, если запись на самом деле не создаётся для каждого изменения, которому она нужна; обязательная запись в changelog в CI разбирает, как заставить pipeline отклонять merge без записи, вместо того чтобы оставлять этот шаг на память.

Мы строим changeloop, где changelog сначала лента, а потом уже страница, так что читайте это как заинтересованность, а не беспристрастную рекомендацию; цены — это один бесплатный репозиторий без карты, достаточный, чтобы увидеть форму. Инструменты для changelog — наш обзор того, что ещё существует, включая продукты, с которыми мы конкурируем, а генератор changelog выполняет шаги сбора и классификации в браузере, если вы хотите увидеть вывод перед тем, как обязаться на pipeline.

Тест

Посчитайте минуты между объединённым изменением и видимостью этого изменения для клиентки, которая не читает ваш репо. Если большинство этих минут — это кто-то, копирующий текст между инструментами, автоматизация, которая вам нужна, находится в публикации, а не в написании.

FAQ

Может ли ИИ написать changelog? Он может составить черновик. Модель, которой дан объединённый pull request, чаще всего производит пригодный первый черновик заголовка и тела, что и есть сбор и классификация, сделанные лучше. Отбор — стоит ли вообще что-то говорить читателю, и финальная формулировка всё ещё нуждаются в человеке, знающем аудиторию, и pipeline, публикующий черновики без этих ворот, автоматизировал не тот шаг.

В чём разница между генератором changelog и автоматизацией changelog? Генератор превращает коммиты в отформатированный список один раз, по запросу. Автоматизация работает при каждом merge, поддерживает неопубликованную корзину, обусловливает релиз человеческим ревью, и публикует на каждую поверхность из одного источника. Генератор — это первый шаг pipeline, выполняемый вручную.

Следует ли автоматизировать changelog из коммитов или из pull request? Из pull request, где единицей изменения является PR: заголовок и описание пишутся один раз, для всего изменения, и PR связывает issue, который закрывает. Вывод на основе коммитов работает, когда коммит является единицей и следует конвенции.

Как предотвратить публикацию внутренних изменений автоматизацией? Классифицируйте chore, ci, test, refactor и обновления зависимостей как внутренние по умолчанию, и сделайте продвижение к публичности осознанным актом. Обратный по умолчанию, публичное если только кто-то не скроет, — это как bump deps достигает клиентов.

Технические утверждения в этой статье не проходили независимую проверку. Если здесь что-то не так, сообщите нам, и мы исправим.

По теме на changeloop: Сравнение инструментов changelog, Генератор changelog