Как писать release notes, которые реально читают

Чтобы писать release notes, которые читают, отвечайте на один вопрос в каждой записи: что читатель теперь может сделать, чего не мог раньше, и что ему нужно для этого сделать. Ставьте всё с дедлайном первым, называйте, кого это касается, пишите «действий не требуется», когда это правда, и пропускайте релизы, которым нечего сказать. Всё остальное на этой странице — применение этого правила.

Исправления багов и улучшения производительности.

Каждый продукт когда-нибудь публиковал это. Причина редко в лени: так получается, когда release notes пишутся изнутри, кем-то, кто провёл две недели в диффе и уже не видит, какие части заинтересуют постороннего. Лучший тон это не исправит; ответ на вопрос — да.

Что должны включать release notes?

Release notes должны включать для каждого изменения, заслуживающего упоминания: что читатель теперь может сделать, кого это касается, что ему нужно сделать (включая «ничего»), и когда вступает в силу то, у чего есть дедлайн. Они не должны включать номера внутренних тикетов, названия компонентов, которые использует только команда, или номер версии как единственный заголовок.

Разделение между release note и записью changelog — это то, что делает возможным этот список: changelog хранит всё, поэтому заметки могут что-то опускать. Размеченные примеры каждого вида записи собраны в статье примеры release notes.

Вопрос, на который отвечает каждая запись

Что читатель теперь может сделать, чего не мог раньше, и что ему нужно для этого сделать?

Если запись не может на это ответить, она принадлежит changelog, а не release notes. Обе половины важны. Первая половина — это ценность. Вторая половина — та, которую забывают команды, и именно она порождает тикеты в поддержку, когда её нет.

Два примера второй половины, выполняющей реальную работу:

• «Существующие вебхуки продолжат работать до 1 ноября. После этой даты неподписанные payload будут отклоняться.»
• «Действий не требуется. Существующие экспорты автоматически перекодируются при следующем открытии.»

Второй пример явно говорит «действий не требуется». Эту фразу стоит писать каждый раз, потому что читатель, который её не находит, предполагает худшее.

Как следует упорядочивать release notes?

Упорядочивайте их по последствиям для читателя, никогда — по части системы, которая изменилась. Группировка по API, панели, мобильному приложению и инфраструктуре — это ваша организационная схема, а не проблема читателя.

1. Breaking change и всё, у чего есть дедлайн. Всегда первым, даже если это мелочь. Если читатель перестаёт читать после одной строки, это должна быть та строка, которую он должен был прочитать. Если дедлайн — это sunset, запись должна звучать как уведомление об устаревании.
2. Что нового и чего они хотели. По одному на абзац, с результатом в первом предложении.
3. Что улучшилось. Баги, о которых сообщили, лимиты, которые подняли, что было медленным.
4. Всё остальное, списком. Обновления зависимостей, внутренние рефакторинги, мелкие тексты. По одной строке каждое. Никто не читает этот раздел, и всё же он должен быть, потому что тот, кто его ищет, действительно в нём нуждается.

Переписывание

До:

v4.2.0 Исправлена проблема, из-за которой endpoint POST /exports периодически возвращал 500 под нагрузкой. Рефакторинг воркера экспорта. Обновлён node-pg до 8.11. Улучшена обработка ошибок в сериализаторе CSV.

После:

Экспорты больше не падают на больших аккаунтах. Аккаунты с более чем примерно 50 000 строк могли получить 500 при запуске экспорта, чаще в конце месяца. Это исправлено, и теперь экспорты любого размера сами повторяют попытку вместо того, чтобы падать. Действий не требуется, и любой экспорт, упавший на прошлой неделе, можно просто запустить заново.

Также в 4.2.0: node-pg 8.11, более понятные ошибки в сериализаторе CSV.

Тот же релиз. Второй вариант называет затронутый аккаунт, момент, когда было хуже всего, что изменилось, и что делать. Обновление зависимости не исчезло, оно просто перестало быть заголовком. Статья лучшие практики release notes содержит остальные правила, которым следует это переписывание, каждое с ценой пропуска.

Что стоит удалить

• «Мы рады объявить.» Читатель ещё не рад. Заслужите это в следующем предложении.
• Внутренние номера тикетов. PROJ-4471 ничего не значит вне вашего трекера. Если записи нужна ссылка, дайте ссылку на страницу документации.
• Названия компонентов, которые использует только ваша команда. Если вы переименовали «пайплайн приёма данных», скажите «импорты».
• Номер версии как единственный заголовок. v4.2.0 — это ярлык для архива, а не резюме.
• Скриншоты страницы настроек, которую никто не посещал. Покажите то, что изменилось, в действии.

Как часто следует публиковать release notes?

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

Changelog продолжает фиксировать всё. Таково разделение труда: changelog полон, заметки избирательны. Если вы поддерживаете changelog структурированным по ходу дела, написание заметок становится отбором и переписыванием, а не археологией.

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

Всё это предполагает страницу, которую вы полностью контролируете, без ограничения длины и с работающими ссылками. Release notes для мобильных приложений разбирает, что меняется, когда поверхность — это листинг App Store или Play Store. Экстренные release notes разбирают другое исключение: что меняется, когда не остаётся времени вообще следовать обычному процессу написания.

Один тест перед публикацией

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

FAQ

Насколько длинными должны быть release notes? Такими длинными, каких требуют значимые изменения, и ни строкой больше. Релиз с одним breaking change и двумя улучшениями — это три абзаца. Наполнение тихого релиза, чтобы он казался значительным — это как читатели учатся пропускать заметки.

Кто должен писать release notes? Человек, понимающий изменение, отредактированный кем-то, кто его не понимает. Инженерка знает, что изменилось; редакторка знает, что посторонний поймёт неправильно. Написание записи в момент merge, пока инженерка ещё помнит, — это практика, которая делает это дешёвым.

Должны ли release notes включать исправления багов? Да, те, о которых кто-то сообщил или с которыми столкнулся. Укажите симптом, который видел читатель, а не причину. «Экспорты более 50 000 строк падали» — это исправление, которое читатель узнаёт; «исправлена гонка в воркере экспорта» — это сообщение коммита.

В чём разница между release notes и changelog? Changelog — это полный, непрерывный реестр; release notes — это отобранное сообщение об одном релизе, написанное для людей, которые ещё не решили, интересует ли их это. Более длинный ответ — в changelog vs release notes.

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

По теме на changeloop: Шаблон релиз-нот, Примеры changelog