Как писать список изменений (changelog) и заметки о выпуске, которые читают клиенты

Автор: Fraser Hardy

Слитые pull request проходят через фильтр и попадают в датированный список изменений с записями «Новое», «Улучшено» и «Исправлено»

В прошлом месяце вы выпустили десяток изменений. В вашем списке изменений написано: «Исправления ошибок и улучшения производительности».

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

Вот как писать список изменений, который люди действительно читают. Пишите для клиента, а не для того, кто слил код. Датируйте каждую запись. Группируйте изменения под заголовками Новое, Улучшено и Исправлено. Начинайте каждую запись с того, что человек теперь может сделать, добавляйте одну строку о том, почему это важно, и указывайте, где это найти. Не включайте то, чего клиент не видит, и то, что ещё не выпущено. А затем публикуйте в стабильном ритме, даже если некоторые недели короткие.

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

Changelog и заметки о выпуске: в чём разница?

Эти слова часто используют как взаимозаменяемые, но на самом деле у них две разные аудитории.

Список изменений для разработчиков — обычно файл CHANGELOG.md в репозитории. Он нужен тем, кто интегрируется с вашим API, SDK или библиотекой. Их интересуют номера версий, критические изменения и устаревающие функции. Стандартный источник здесь — Keep a Changelog, и его правила разумны: новое сверху, один раздел на версию, изменения сгруппированы как Added, Changed, Deprecated, Removed, Fixed и Security, а наверху раздел «Unreleased» для работы, которая слита, но ещё не выпущена.

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

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

Шаблон заметок о выпуске, который можно скопировать

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

## 6 October 2026

### New
**[What you can now do, in plain words]**
[One or two sentences: what it does and who it's for.]
Find it in **[Page > Section]**. [Link to help article]

### Improved
**[The thing that got better]**
[What's different from before, in terms the customer notices:
faster, fewer clicks, works on mobile, handles bigger files.]

### Fixed
- [Symptom the customer saw], now fixed.
- [Symptom the customer saw], now fixed.

### Heads up (only if needed)
**[Anything changing or going away]**
[What's happening, when, and what they need to do.]

Несколько правил, благодаря которым это работает:

Плохие и хорошие записи в списке изменений

Плохая запись в списке изменений, написанная как сообщения коммитов, рядом с хорошей записью, объясняющей, что изменилось для клиента и где это найти

Самая частая ошибка — вставлять сообщения коммитов. Вот как это выглядит:

v2.14.0
- feat(export): csv async job
- fix: tz bug in reports
- refactor billing svc
- bump deps
- misc improvements

Всё это правда. Но клиенту ничто из этого не полезно. Две записи — внутренний шум, одна бессмысленна («misc improvements»), а два настоящих изменения написаны для того, кто проверял PR.

Вот тот же выпуск, переписанный:

6 October

NEW: Big CSV exports run in the background
Exports over 10,000 rows no longer time out. Start the export
and we'll email you a link when the file is ready.
Find it in Reports > Export.

FIXED: Report dates now match your timezone
Daily totals were splitting at midnight UTC instead of your
local midnight, so some days looked short. They're correct now,
including for past reports.

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

Ещё несколько пар, потому что для привычки нужно время:

ПлохоХорошо
Добавлен SSOВходите через Okta или Google Workspace. Администраторы могут включить это в «Настройки > Безопасность».
Улучшена производительностьПанель на больших аккаунтах загружается намного быстрее. Проекты с тысячами элементов больше не зависают при первой загрузке.
Исправлена ошибка уведомленийВы больше не будете получать дублирующиеся письма, когда вас упоминают дважды в одном комментарии.
Объявлены устаревшими конечные точки v1API v1 перестанет работать 1 марта. Перейдите на v2 до этой даты. Вот что изменится.

Обратите внимание, что «намного быстрее» звучит расплывчато. Если у вас есть измеренное реальное число, используйте его. Если нет, опишите ощущения вместо того, чтобы придумывать процент.

Как писать список изменений по слитым PR

Пятишаговый процесс создания списка изменений: собрать слитые PR, отфильтровать видимые клиенту и запущенные изменения, сгруппировать по типу, переписать для клиента, опубликовать со ссылками

Большинство команд мучается не с написанием, а с тем, чтобы вспомнить, что вышло. Вот порядок действий, который работает.

1. Соберите. Выведите всё, что слито с момента прошлой записи. С помощью GitHub CLI:

gh pr list --state merged \
  --search "merged:>=2026-10-27" \
  --json number,title,labels,mergedAt,url \
  --limit 100

2. Отфильтруйте. Для каждого PR задайте два вопроса. Может ли клиент это увидеть или почувствовать? Работает ли это для него на самом деле? Внутренние рефакторинги, изменения CI и исправления тестов отпадают. Как и всё, что скрыто за не включённым флагом функции. Объявлять работу, недоступную клиентам, хуже, чем не объявлять, потому что вы получите обращения «где это?».

3. Сгруппируйте. Разложите оставшееся по группам «Новое», «Улучшено» и «Исправлено». Несколько мелких PR часто складываются в одну запись («Массовое редактирование» может состоять из четырёх PR).

4. Перепишите. Превратите каждую группу в запись по шаблону. Сначала польза, простые слова, где это найти.

5. Опубликуйте и дайте ссылки. Опубликуйте запись, свяжите каждую новую функцию с её статьёй справки и поделитесь там, где её увидят клиенты.

Приём, который сильно облегчает шаг 4: просить формулировку для клиента на этапе PR, пока автор ещё помнит, что он сделал. Добавьте раздел в .github/pull_request_template.md:

## Customer-facing change
<!-- One sentence a customer would understand, or "None". -->
<!-- e.g. "You can now export reports over 10,000 rows." -->

- [ ] Behind a feature flag (don't announce until it's on)
- [ ] Help articles checked

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

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

Ориентируйтесь на ритм ваших выпусков, в разумных пределах. Если вы выпускаете изменения непрерывно, еженедельная или двухнедельная сводка читается лучше, чем запись на каждое развёртывание. Если выпускаете раз в месяц, публикуйте раз в месяц.

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

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

Где разместить список изменений

Специализированные инструменты вроде Beamer, Headway, LaunchNotes или списка изменений в Canny хорошо справляются с виджетом и письмами. Многие команды просто используют страницу на сайте документации. Инструмент важен меньше, чем привычка.

Где подходит Ellie Docs

Раскрою интерес: мы создали решение именно для этой проблемы. Ellie Docs следит за вашими слитыми PR и составляет по ним черновики записей для списка изменений, написанные для клиентов, а не для рецензентов. Она придерживает записи о работе, которая не выпущена или находится за флагом, чтобы вы не объявляли то, чем люди не могут пользоваться. Вы сами правите, отбрасываете или публикуете каждую запись. Ничего не уходит само.

Представление списка изменений в Ellie Docs с понятными клиентам записями, составленными по слитым pull request; каждая связана со своей статьёй справки и готова к правке или публикации

Поскольку она ещё и поддерживает ваш центр помощи, тот же PR, который порождает запись в списке изменений, порождает и предложенное обновление для любой устаревшей статьи в виде диффа, который вы принимаете или отклоняете.

Предложенное обновление статьи справки после pull request в виде красно-зелёного диффа с кнопками «Принять» и «Отклонить»

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

Несколько частых вопросов

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

Нужны ли номера версий? Для API, SDK и всего, что устанавливается, да, и следуйте семантическому версионированию, чтобы люди могли оценить риск с первого взгляда. Для веб-приложения с непрерывным развёртыванием понятнее даты. Клиенты не мыслят версиями.

Какой длины должна быть запись в списке изменений? Жирный заголовок и от одного до трёх предложений. Если нужно больше, напишите статью справки или пост в блоге и дайте ссылку.

Хотите получить список изменений, составленный по уже слитым PR? Попробуйте Ellie Docs бесплатно. Есть бесплатный тариф, карта не нужна.