Как писать release notes, которые реально читают
6 мин чтения обновлено
Чтобы писать release notes, которые читают, отвечайте на один вопрос в каждой записи: что читатель теперь может сделать, чего не мог раньше, и что ему нужно для этого сделать. Ставьте всё с дедлайном первым, называйте, кого это касается, пишите «действий не требуется», когда это правда, и пропускайте релизы, которым нечего сказать. Всё остальное на этой странице сводится к применению этого правила.
Release note, построенная так, по одной строке на раздел:
## 2.4.0 (18 октября 2026)
Breaking: GET /v1/export удаляется 1 декабря 2026. Используйте
GET /v2/exports.
Новое: отчёт можно запланировать, чтобы он приходил на почту
каждый понедельник.
Улучшено: дашборды с более чем 50 графиками загружаются примерно
вдвое быстрее.
Исправлено: экспорт CSV больше не теряет последнюю строку очень
больших отчётов.
Полная версия, со строкой-резюме и местом под каждый раздел, это шаблон release notes. Эта статья о том, как писать заметки одного релиза; привычки, которые держат их хорошими от релиза к релизу, описаны в лучших практиках release notes.
Исправления багов и улучшения производительности.
Каждый продукт когда-нибудь публиковал это. Причина редко в лени: так получается, когда release notes пишутся изнутри, кем-то, кто провёл две недели в диффе и уже не видит, какие части заинтересуют постороннего. Лучший тон это не исправит, а ответ на вопрос исправит.
Что должны включать release notes?
Release notes должны включать для каждого изменения, заслуживающего упоминания: что читатель теперь может сделать, кого это касается, что ему нужно сделать (включая «ничего»), и когда вступает в силу то, у чего есть дедлайн. Они не должны включать номера внутренних тикетов, названия компонентов, которые использует только команда, или номер версии как единственный заголовок.
| Включить | Опустить |
|---|---|
| Результат, словами читателя | Реализацию, словами команды |
| Кого касается, по плану, роли или версии API | «Некоторые пользователи» |
| Требуемое действие, или «действий не требуется» | Тишину, которую читатель заполняет худшим сценарием |
| Дату для всего, у чего есть дедлайн | Номер версии вместо даты |
| Ссылку на документацию с объяснением | Ссылку на pull request |
| Баги, о которых сообщили люди, и поднятый лимит | Внутренние id тикетов |
| Скучный раздел, по одной строке, внизу | Скучный раздел, смешанный с новостями |
Разделение между release note и записью changelog делает возможным этот список: changelog хранит всё, поэтому заметки могут что-то опускать. Размеченные примеры каждого вида записи собраны в статье примеры release notes, а исправления, записи, которые чаще всего пишут плохо, получили собственное руководство в release notes об исправлении багов. Та же идея лежит в основе первого принципа Keep a Changelog: changelog пишут для людей, а не для машин.
Вопрос, на который отвечает каждая запись
Что читатель теперь может сделать, чего не мог раньше, и что ему нужно для этого сделать?
Если запись не может на это ответить, она принадлежит changelog, а не release notes. Обе половины важны. Первая половина несёт ценность. Вторую половину забывают команды, и именно она порождает тикеты в поддержку, когда её нет.
Два примера второй половины, выполняющей реальную работу:
- «Существующие вебхуки продолжат работать до 1 ноября. После этой даты неподписанные payload будут отклоняться.»
- «Действий не требуется. Существующие экспорты автоматически перекодируются при следующем открытии.»
Второй пример явно говорит «действий не требуется». Эту фразу стоит писать каждый раз, потому что читатель, который её не находит, предполагает худшее.
Как следует упорядочивать release notes?
Упорядочивайте их по последствиям для читателя, никогда по части системы, которая изменилась. Группировка по API, панели, мобильному приложению и инфраструктуре отражает вашу организационную схему, а не проблема читателя.
- Breaking change и всё, у чего есть дедлайн. Всегда первым, даже если это мелочь. Если читатель перестаёт читать после одной строки, это должна быть та строка, которую он должен был прочитать. Если дедлайн задаёт sunset, запись должна звучать как уведомление об устаревании.
- Что нового и чего они хотели. По одному на абзац, с результатом в первом предложении.
- Что улучшилось. Баги, о которых сообщили, лимиты, которые подняли, что было медленным.
- Всё остальное, списком. Обновления зависимостей, внутренние рефакторинги, мелкие тексты. По одной строке каждое. Никто не читает этот раздел, и всё же он должен быть, потому что тот, кто его ищет, действительно в нём нуждается.
Переписывание
До:
v4.2.0 Исправлена проблема, из-за которой endpoint
POST /exportsпериодически возвращал 500 под нагрузкой. Рефакторинг воркера экспорта. Обновлёнnode-pgдо 8.11. Улучшена обработка ошибок в сериализаторе CSV.
После:
Экспорты больше не падают на больших аккаунтах. Аккаунты с более чем примерно 50 000 строк могли получить 500 при запуске экспорта, чаще в конце месяца. Это исправлено, и теперь экспорты любого размера сами повторяют попытку вместо того, чтобы падать. Действий не требуется, и любой экспорт, упавший на прошлой неделе, можно просто запустить заново.
Также в 4.2.0:
node-pg8.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 секунд. Если за это время он не может понять, требуется ли от него что-то, заметки не готовы, какими бы точными они ни были. О том, что такое release notes и каким четырём аудиториям они служат, читайте в статье release notes программного обеспечения.
FAQ
Насколько длинными должны быть release notes? Такими длинными, каких требуют значимые изменения, и ни строкой больше. Релиз с одним breaking change и двумя улучшениями занимает три абзаца. Наполнение тихого релиза, чтобы он казался значительным, приучает читателей пропускать заметки.
Кто должен писать release notes? Человек, понимающий изменение, отредактированный кем-то, кто его не понимает. Инженерка знает, что изменилось; редакторка знает, что посторонний поймёт неправильно. Написание записи в момент merge, пока инженерка ещё помнит, делает это дешёвым.
Должны ли release notes включать исправления багов? Да, те, о которых кто-то сообщил или с которыми столкнулся. Укажите симптом, который видел читатель, а не причину. «Экспорты более 50 000 строк падали» читатель узнаёт как исправление; «исправлена гонка в воркере экспорта» остаётся сообщением коммита.
В чём разница между release notes и changelog? Changelog ведётся как полный, непрерывный реестр; release notes дают отобранное сообщение об одном релизе, написанное для людей, которые ещё не решили, интересует ли их это. Более длинный ответ дан в changelog vs release notes.
Технические утверждения в этой статье не проходили независимую проверку. Если здесь что-то не так, сообщите нам, и мы исправим.