Примеры release notes для каждого вида изменений

Лучшие примеры release notes коротки, называют, кого это касается, и говорят, что делать дальше. Ниже по одному примеру на каждый вид изменений, который вам предстоит выпускать, с объяснением, почему он работает, чтобы вы могли взять форму и подставить свои факты.

Все примеры выдуманы, для вымышленного приложения для выставления счетов Tidepool.

Что общего у хороших примеров release notes?

Они говорят пользователям, что изменилось и что им с этим делать, если нужно что-то делать, и говорят это словами пользователей. У каждого вида изменений своя задача, поэтому форма записи от вида к виду меняется.

Как выглядит хорошая заметка о новой функции?

Хорошая заметка о функции начинается с того, что читатель теперь может сделать, и называет планы или роли, которым это доступно. Реализацию она пропускает.

Отправляйте счета на языке клиента. Теперь для каждого клиента можно выбрать язык, и его счета, напоминания и страница оплаты будут на нём. Французский, немецкий, испанский и португальский доступны на всех планах. Настройка находится на странице клиента, в разделе «Настройки оплаты».

Заголовок это фраза, которую читатель сказал бы вслух, а текст даёт охват и место настройки. Читатель, пробежавший глазами только жирную строку, всё равно знает, что выпущено. Общий метод разобран в статье как писать release notes.

Как выглядит хорошая заметка об улучшении?

Заметка об улучшении описывает изменение, которое читатель почувствует, и ставит измеренную цифру, если она есть. Если цифры нет, скажите, что читателю больше не нужно делать.

Список счетов загружается примерно в три раза быстрее. Аккаунты с более чем 5 000 счетов раньше ждали список около девяти секунд. Теперь он открывается примерно за три. Действий не требуется.

«Улучшения производительности» ничего не говорят читателю, а девять секунд против трёх это утверждение, которое он проверит в понедельник утром. Завершающее «Действий не требуется» отвечает на вопрос, который есть у каждого читателя.

Как выглядит хорошая заметка об исправлении бага?

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

Исправлено: напоминания уходили дважды в день оплаты. Некоторые клиенты получали по два одинаковых напоминания, если срок счёта выпадал на последний день месяца. Это исправлено. Уже отправленные напоминания не затронуты, и повторно отправлять ничего не нужно.

Заголовок начинается со слова «Исправлено», чтобы пробегающий глазами мог отсортировать запись с первого взгляда, а настоящее условие (последний день месяца) идёт сразу следом.

Как писать release notes о breaking change?

Заметка о breaking change начинается с даты и затронутой группы, а затем в той же записи даёт миграцию. В release notes она идёт первой, потому что это единственная запись, которую читатель не должен пропустить.

Подписи вебхуков станут обязательными с 1 декабря 2026 года. С этой даты Tidepool перестаёт отправлять неподписанные payload вебхуков. Это касается всех, кто принимает вебхуки без проверки заголовка Tidepool-Signature. Для миграции проверяйте заголовок с помощью секрета в разделе «Настройки, Разработчикам». Если вы уже проверяете подписи, действий не требуется.

Дата стоит в заголовке, поэтому переживает беглое чтение. Затронутая группа названа по тому, что она делает, а последнее предложение отпускает тех, у кого всё в порядке, и это снижает нагрузку на поддержку. Руководство по breaking changes объясняет, как решить, считается ли изменение таковым.

Как выглядит заметка об исправлении уязвимости?

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

Безопасность: ссылки для сброса пароля можно было использовать повторно. С 3 по 17 сентября 2026 года ссылка для сброса пароля оставалась действительной после первого использования. Признаков того, что этим пользовались, мы не нашли. Это исправлено, а все неиспользованные ссылки аннулированы. Если вы запрашивали сброс в этот период, запросите новую ссылку.

Точный период позволяет читателю оценить собственный риск, а фраза об использовании отвечает на первый вопрос, который задаёт любой. «Потенциальная проблема» выглядит как сокрытие, поэтому пишите то, что вам известно.

Как написать уведомление о депрекации?

Уведомление о депрекации называет, что убирается, даёт твёрдую дату окончания и указывает замену.

Endpoint счетов v1 объявлен устаревшим и перестанет работать 1 марта 2027 года. GET /v1/invoices продолжает работать до 1 марта 2027 года, после чего будет возвращать 410 Gone. Используйте GET /v2/invoices, который возвращает те же поля плюс currency. Ответы v1 теперь содержат заголовок Sunset с датой окончания. Руководство по миграции с примерами рядом есть в документации.

Название endpoint стоит в заголовке, потому что те, кого это касается, ищут именно его, а замена стоит рядом с удалением. Заголовок Sunset показывает разработчикам, какие вызовы всё ещё идут на старую версию. Более подробно это разобрано в статье депрекация API.

Как выглядит заметка о релизе в сторе приложений?

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

Сфотографируйте бумажный чек, и Tidepool сам заполнит сумму, дату и поставщика. Тёмная тема теперь следует настройке телефона. Ещё мы исправили падение при открытии счёта из уведомления.

Самое полезное изменение стоит первым, а исправление называет ситуацию, в которой было падение. Нет номера версии и нет фразы «исправления ошибок и улучшения». Правила, специфичные для сторов, разобраны в статье release notes для мобильных приложений.

Что должна включать внутренняя заметка о релизе?

Внутренняя заметка это версия для поддержки и продаж. Она добавляет то, что публичная заметка опускает: что говорить и что не обещать.

Счета на нескольких языках выпущены сегодня (все планы). Поддержка: клиенты задают язык в «Настройках оплаты», а уже выставленные счета сохраняют исходный язык. Итальянского пока нет. Продажи: функция открыта на всех планах, так что не подавайте её как повод для апгрейда.

У каждой аудитории своя подписанная строка, а заметка проводит границу («Итальянского пока нет») раньше, чем клиент спросит. Формат и каналы разобраны в статье внутренние release notes.

Как выглядит плохая заметка о релизе после переписывания?

Плохая заметка перечисляет, что сделала команда, а не что получает читатель. Исправьте её, вынеся результат вперёд и убрав внутренний словарь.

До:

v3.8.1 Рефакторинг планировщика напоминаний. Исправлено состояние гонки в ReminderJob. Обновлён bull до 4.12. Прочие улучшения.

После:

Напоминания больше не уходят дважды. Клиенты со счётом, срок которого выпадал на последний день месяца, могли получить два напоминания. Это исправлено, а уже отправленные напоминания повторно отправлять не нужно. Действий не требуется.

Также в 3.8.1: bull обновлён до 4.12.

Обновление зависимости опустилось в строку внизу, а состояние гонки стало симптомом, который клиент узнает.

Как сохранять единообразие release notes от релиза к релизу?

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

Changeloop работает именно так: он составляет запись из каждого влитого pull request с помощью ИИ и удерживает её до одобрения человеком. На шаге одобрения редактор применяет правила выше. Чтобы сначала определиться с форматом, начните с шаблона release notes, а как выглядят готовые страницы, смотрите в примерах changelog.

FAQ

Что такое новые release notes? Новые release notes это сообщение, которое публикуется вместе с последним релизом продукта и описывает, что изменилось и что нужно сделать пользователям. Они охватывают функции, улучшения, исправления и breaking changes.

Чем release note отличается от changelog? Changelog хранит всё, для всех, кому нужна вся история. Release note выбирает из него: один релиз, написанный для читателей, которые решают, важен ли он им. Полное сравнение есть в статье changelog vs release notes.

Что значит release notes? Release notes сообщают пользователям, что изменилось в релизе. Так называют всё, что объясняет, что выпущено, от текста «Что нового» в сторе приложений до страницы на сайте компании.

Какой длины должна быть каждая запись в release notes? Для большинства записей хватает двух-четырёх предложений: результат, кого это касается и что делать. Breaking change или исправление уязвимости могут быть длиннее, потому что им нужны дата или миграция.

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

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