Шаблон релиз-нот

Шаблон

Всё в квадратных скобках — это заполнитель. Всё остальное стоит сохранить, включая порядок: пользователи ищут то, что их затрагивает, поэтому критические изменения идут первыми, а внутренняя работа не появляется вовсе.

## [Продукт] [версия] - [дата]

[Одно предложение о том, для чего этот релиз. Пропустите для
рутинных релизов.]

### Критические изменения
- [Что сломалось, что изменить и до какого срока. Дайте ссылку
  на шаги миграции.]

### Новое
- [Функция, описанная как результат. «Закрепите фильтр и
  используйте его снова», а не «добавлена модель SavedView».]

### Улучшено
- [Что стало быстрее, понятнее или надёжнее, и примерно насколько.]

### Исправлено
- [Симптом, который увидел пользователь, а не причина в коде.]

Если раздел пуст, удалите заголовок. Пустой раздел «Исправлено» читается так, будто ничего не исправлено, а заголовок без ничего под ним заставляет читателей думать, что страница не загрузилась.

Тот же шаблон, заполненный

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

## Acme API 4.2 - 20 августа 2026

Пагинация теперь основана на курсоре во всех endpoint'ах списков.

### Критические изменения
- `?page=` удалён во всех endpoint'ах списков. Используйте значение
  `nextCursor` из предыдущего ответа. `?page=` возвращает 400
  после 1 октября 2026. Шаги миграции:
  acme.example/docs/pagination

### Новое
- Сохранённые представления во входящих. Закрепите фильтр один
  раз и используйте его снова из боковой панели.
- Webhook'и теперь можно ограничить одним проектом.

### Улучшено
- Endpoint'ы списков отвечают примерно в четыре раза быстрее на
  крупных аккаунтах.
- Задача экспорта теперь сообщает о прогрессе вместо того,
  чтобы казаться зависшей.

### Исправлено
- Приглашённые участники больше не видят пустую панель до
  первого входа.
- Временные метки в экспортах теперь учитывают часовой пояс
  аккаунта.

Что входит в каждый раздел

Критические изменения

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

Новое

Опишите результат, а не объект, который вы построили. Проверка в том, имеет ли строка смысл для того, кто никогда не видел вашего кода. «Сохранённые представления во входящих» проходит проверку. «Добавлена модель SavedView и её миграция» — нет.

Улучшено

Количественно оценивайте там, где можете честно. «Быстрее» стоит почти ничего, и читатели это учитывают; «примерно в четыре раза быстрее на крупных аккаунтах» стоит прочтения и задаёт ожидание, за которое с вас можно спросить. Если не можете измерить, скажите, что лучше, опровержимым способом.

Исправлено

Пишите симптом, а не причину. Пользователи ищут в этих заметках то, что с ними произошло, поэтому «приглашённые участники попадали на пустую панель» находимо, а «исправлена гонка данных в кэше членства» — нет.

Варианты

Четыре раздела применимы к большинству релизов. Три случая требуют изменения:

• Релизы мобильных приложений. Магазины приложений показывают короткое поле «что нового», поэтому начните с одного предложения, которое можно прочитать в листинге магазина, затем дайте ссылку на полные заметки. Проверка магазина также может задержать сборку на дни, поэтому датируйте заметки по дате релиза, а не по дате объединения.
• API-релизы. Версионируйте заметки так же, как версионируете API, и поместите окно устаревания прямо в заметки, а не только в документацию. Потребитель API читает заметки именно для того, чтобы узнать, сколько у него времени.
• Внутренние или административные инструменты. Уберите раздел «Улучшено» и объедините его с «Исправлено». Внутренним пользователям важно, изменился ли их рабочий процесс, а длинный раздел «Улучшено» это скрывает.

Четыре правила, которые делают их читаемыми

1. Пишите для того, кто не знает ваш код. Никаких имён файлов, имён веток, идентификаторов тикетов, названий сервисов, внутренних кодовых имён.
2. Опускайте всё без видимого для пользователя эффекта. Обновления зависимостей, рефакторинг, изменения CI и исправления опечаток относятся к истории коммитов, а не к релиз-нотам. Самый распространённый способ, которым умирают релиз-ноты, — заполнение их работой, которую никто вне команды не видит.
3. Одна запись, одно изменение. Если строке нужно слово «и» дважды, это, вероятно, две записи.
4. Публикуйте в ритме, на который люди могут положиться, даже если ритм — «когда бы мы ни выпустили релиз». Заметки, которые появляются четыре раза за неделю, а потом не появляются два месяца, воспринимаются как шум.

Формат релиз-нот: части по порядку

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

1. Заголовок, который говорит, что изменилось для читателя, а не номер версии. Версия идёт меньшей строкой под ним, с датой в формате ISO (2026-08-29), чтобы читаться одинаково в любой локали.
2. Критические изменения и всё со сроком, первыми, даже если они небольшие. Если читатель останавливается после одного абзаца, это тот абзац, который ему был нужен.
3. Что нового, один пункт на абзац, с результатом в первом предложении и требуемым действием, включая «действие не требуется», указанным каждый раз.
4. Исправления и улучшения, затем всё остальное в виде однострочного списка внизу. Обновления зависимостей и внутренние изменения остаются, потому что единственному человеку, который их ищет, они действительно нужны.

В Markdown это заголовок H2, приглушённая строка версии и даты, затем разделы H3 для Критических, Новых, Улучшенных и Исправленных. В письме это тот же порядок с заголовком в качестве темы. В виджете changelog это заголовок и первый абзац, а остальное за ссылкой. Шаблон выше — это та же форма, записанная целиком.

О самом написании, а не форме, смотрите как писать релиз-ноты, которые люди действительно читают и лучшие практики релиз-нот, которые стоит сохранить в блоге.

Частые вопросы

Насколько длинными должны быть релиз-ноты?

Настолько длинными, насколько требуют изменения, влияющие на пользователей, и не длиннее. Релиз с одним исправлением бага получает две строки. Раздувание маленького релиза, чтобы он выглядел существенным, приучает людей пролистывать большие.

В чём разница между релиз-нотами и changelog?

На практике эти термины используются взаимозаменяемо. Там, где команды их различают, релиз-ноты описывают один релиз и пишутся для пользователей, а changelog — это непрерывный список всех релизов во времени. Этот шаблон охватывает один релиз; changelog — это то, что вы получаете, складывая их от новых к старым.

Должны ли релиз-ноты иметь номер версии?

Только если ваши пользователи могут его увидеть. Номера версий полезны для API, библиотек и установленного ПО, где читателю нужно знать, на какой версии он находится. Для непрерывно развёртываемого веб-приложения дата полезнее, потому что именно её пользователь может сопоставить со своим опытом.

Кто должен их писать?

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