Кто пишет changelog, а кто должен

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

Почему автор PR не автоматически лучший автор changelog?

Потому что он знает реализацию, не обязательно влияние, а это разные виды знания. Где останавливаются conventional commits разбирает этот разрыв со стороны сообщения коммита: fix(auth): reject expired refresh tokens корректно и не говорит клиентке ничего, а тот, кто написал это исправление, часто наименее готов его перевести, потому что думал в терминах бага часами и потерял внешний взгляд на то, что на самом деле испытала пользовательница. Та же причина, по которой технические писательницы существуют как профессия: перевод реализации в её влияние — отдельный навык от того, чтобы построить саму вещь, и он требует практики независимо от того, насколько разработчик хорош в самом коде.

Значит ли это, что продукт или поддержка должны писать каждую запись вместо этого?

Нет, потому что у них противоположный разрыв: они знают, что важно пользовательницам, но не всегда что на самом деле было выпущено, что производит записи читаемые, но иногда неверные по охвату, утверждение «теперь поддерживает X» для функции, всё ещё скрытой за флагом, или исправление, описанное как полное, когда покрывает только один из трёх случаев. Режим сбоя записей, написанных разработчицами, — нечитаемо-но-точно; режим сбоя записей, написанных PM-ками, — читаемо-но-непроверено. Ни одна роль не владеет обеими половинами того, что нужно хорошей записи.

Как на самом деле выглядит рабочая модель ответственности?

Черновик от того, кто ближе всего к изменению, проверенный тем, кто ближе всего к пользовательнице, с одним названным человеком, ответственным за финальную формулировку, вместо того чтобы все предполагали, что кто-то другой поймает проблемы. Черновику важнее существовать и быть точным, чем быть хорошим; грубое предложение, написанное разработчицей, которое верно говорит, что изменилось, — лучшая отправная точка, чем отполированное, но непроверенное, потому что переписать ради ясности легче, чем переписать ради правильности. Шаг review — там, где PM или лидер поддержки читает черновик и задаёт единственный вопрос, ловящий разрыв читаемости: поняла бы я это, если бы не видела код.

Должен ли всегда отвечать один и тот же человек, или это ротируется?

Названная и стабильная роль побеждает ротирующуюся, по крайней мере для финального одобрения. Ротирующаяся владелица означает, что каждую запись проверяет кто-то, заново выводящий соглашения команды с нуля, что ровно то, как голос дрейфует от записи к записи, и читательница начинает замечать, что changelog написан комитетом. Один человек, или очень маленькая стабильная группа, накапливает суждения со временем, когда говорить «улучшено» против называть конкретное число, когда исправлению нужна собственная запись против сворачивания в пакет, и это суждение стоит больше, чем равномерное распределение работы.

Черновик (разработчица, из PR):
"Fixed pagination cursor not respecting the `sort` param
in some edge cases."

Проверено (владелица changelog, сверено с реальным PR):
"Исправлено: экспорт, отсортированный по дате, мог
возвращать результаты не по порядку после первой
страницы. Теперь согласовано на всех страницах."

Нужно ли маленькой команде столько процесса ради одной строки текста?

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

Что происходит, когда никто не отвечает за финальную запись?

Changelog деградирует неровно вместо того, чтобы сломаться явно, что хуже, потому что никто не замечает, пока читательница на это не укажет. Некоторые записи остаются чёткими, потому что тому, кто их писал, было не всё равно; другие становятся размытыми, «различные улучшения и исправления ошибок», потому что тот, кто их писал, спешил, и никто не поймал это до публикации. Ограничения формата Keep a Changelog ловят структурный дрейф, пропущенные даты, неверные категории, но ничто в шаблоне не ловит размытую запись, которая технически хорошо отформатирована, а это ровно тот разрыв, который названная владелица призвана закрыть.

FAQ

Должна ли владелица changelog быть инженерной ролью или продуктовой? Любая может работать, если у человека есть и техническая беглость, чтобы проверять охват, и достаточная дистанция от реализации, чтобы писать для внешней читательницы; должность важна меньше, чем то, может ли она делать обе половины, или знает, у кого спросить о половине, которую не может сделать сама.

Подходит ли ротирующийся дежурный график для ответственности за changelog? Для объёма иногда, если команда слишком мала, чтобы один человек проверял всё; для голоса и суждения нет, потому что это ровно то, что размывает ротация. Ротация, разделяющая нагрузку черновиков при сохранении одной стабильной ревьюерки, получает выгоду без дрейфа.

Какой самый быстрый признак, что с текущей настройкой ответственности что-то не так? Записи, точные, но нечитаемые, или читаемые, но неверные по охвату, в шаблоне, следующем за тем, кто их написал. Если качество коррелирует с автором вместо того, чтобы оставаться стабильным, разрыв — в ответственности, а не в умении писать.

Уменьшает ли автоматизация то, насколько важна ответственность? Она уменьшает объём необходимого письма, а не объём необходимого суждения. Автоматизация changelog разбирает, что pipeline может безопасно генерировать, форматирование, публикацию, кросс-постинг; формулировка, группировка и что считается достойным упоминания остаются человеческими решениями независимо от того, насколько автоматизирован pipeline.

Что если автор PR и ревьюер расходятся во мнении о формулировке? Решает ревьюер, потому что вопрос, на который он отвечает, поймёт ли это внешняя читательница, — именно тот, ради которого существует роль. Это не делает мнение разработчика бесполезным: если разногласие о точности, а не о формулировке, ревьюер уступает, потому что охват — половина автора, за которую отвечает он. Разделение двух видов разногласий, формулировка против точности, останавливает большинство из них до того, как они превратятся в противостояние.

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

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