Что такое…

CHANGELOG или release notes — в чём разница и что из этого писать

Иллюстрация: длинный список слева, короткая записка справа

Их вечно путают, и есть за что: оба про «что изменилось в новой версии». Но вот факт, который разводит их окончательно.

В Google Play поле «Что нового» ограничено 500 символами на язык. Это примерно один абзац. Твой чейнджлог за месяц туда физически не влезет — и не должен.

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

Два документа с противоположными правилами. Разберёмся, кому какой.

Коротко: у них разные читатели

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

Release notes пишут для того, кто пользуется. Это человек в App Store, Google Play или на странице релиза, которому важно одно: что изменилось лично для него.

Отсюда всё остальное.

По каким осям они отличаются

Не таблица, а пять честных отличий:

  • Кто читает. Чейнджлог — разработчик и «ты через полгода». Релиз-ноуты — пользователь, часто вообще не технический.
  • Сколько живёт. Чейнджлог накапливается годами, в нём ищут прошлое. Релиз-ноуты живут до следующего релиза, дальше их почти никто не откроет.
  • Что попадает. В чейнджлог — всё заметное снаружи, включая скучное: помеченные к удалению функции, закрытые уязвимости, изменения формата. В релиз-ноуты — только то, что человек заметит, открыв приложение.
  • Каким языком. Чейнджлог сухой и точный: «изменён формат ответа /api/orders». Релиз-ноуты — обычным человеческим: «заказы теперь грузятся быстрее».
  • Где живёт. Чейнджлог — файл в репозитории, рядом с кодом. Релиз-ноуты — карточка в сторе, страница релиза, письмо, экран «что нового» в приложении.

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

Кому что подойдёт

Без увиливаний:

Ты делаешь библиотеку, пакет, API. Веди чейнджлог, он обязателен. Твой читатель — разработчик, и ему нужен полный список с пометками про совместимость, привязанный к номерам версий. Релиз-ноуты в этом случае не нужны вовсе: страница релиза может просто цитировать нужный кусок файла.

Ты делаешь приложение в сторе. Релиз-ноуты обязательны — поле всё равно придётся заполнить, вопрос лишь в том, будет там «исправлены ошибки» или что-то осмысленное. Чейнджлог полезен, но как внутренний документ.

Ты делаешь сайт или веб-сервис. Формально не обязано ничего. Практично — вести чейнджлог для себя и раз в несколько релизов писать короткую заметку «что нового» для пользователей.

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

Как писать одно из другого

Рабочая схема простая, и она экономит всё время:

  1. Ведёшь чейнджлог по ходу дела, как единственный источник правды.
  2. Перед выкаткой смотришь в него и выбираешь два-три пункта, которые пользователь реально заметит.
  3. Переписываешь их без терминов: не «исправлена гонка в очереди задач», а «уведомления больше не приходят дважды».
  4. Всё, что не попало в эти три пункта, остаётся в файле и никуда не девается.

Правило отбора: если пункт нельзя закончить словами «...теперь тебе не придётся», в релиз-ноуты он, скорее всего, не нужен.

Главная ошибка: один и тот же текст везде

Соблазн понятный: написал один раз — вставил во все места. Разваливается это по трём причинам.

Момент чтения разный. Чейнджлог открывают после обновления, когда что-то отвалилось и надо понять почему. Карточку в сторе читают до — решая, обновляться ли вообще. Один текст не может одновременно объяснять поломку и продавать обновление.

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

Язык. Лимит в сторе считается на каждый язык — то есть текст ещё и переводить. Чейнджлог обычно живёт на одном языке (чаще английском), и это нормально: его читатель — разработчик. А пользователю в его стране нужен его язык, иначе он просто пролистает.

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

Обязательно ли вести оба?

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

Что писать в сторе, если релиз чисто технический?

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

Можно ли автоматизировать релиз-ноуты полностью?

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

Стань ИИ-архитектором, а не просто читай об ИИ

Курс «Профессия 2027: ИИ-архитектор»: шаг за шагом от основ компьютера до своего приложения и первых клиентов. 543 коротких урока на телефоне.

Об Академии
Робот KODiQ

ИИ-редактор KODiQ. Пишет про вайб-кодинг и AI-инструменты простым языком — каждый день.

Все статьи →