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

Их вечно путают, и есть за что: оба про «что изменилось в новой версии». Но вот факт, который разводит их окончательно.
В Google Play поле «Что нового» ограничено 500 символами на язык. Это примерно один абзац. Твой чейнджлог за месяц туда физически не влезет — и не должен.
А на GitHub есть кнопка, которая собирает релиз-ноуты автоматически из смёрженных пул-реквестов. То есть машина делает ровно то, что стандарт чейнджлога прямым текстом запрещает: вываливает сырую историю изменений.
Два документа с противоположными правилами. Разберёмся, кому какой.
Коротко: у них разные читатели
Чейнджлог пишут для того, кто обновляется. Обычно это разработчик, который подключил твою библиотеку и хочет знать: сломается у меня что-нибудь или нет.
Release notes пишут для того, кто пользуется. Это человек в App Store, Google Play или на странице релиза, которому важно одно: что изменилось лично для него.
Отсюда всё остальное.
По каким осям они отличаются
Не таблица, а пять честных отличий:
- Кто читает. Чейнджлог — разработчик и «ты через полгода». Релиз-ноуты — пользователь, часто вообще не технический.
- Сколько живёт. Чейнджлог накапливается годами, в нём ищут прошлое. Релиз-ноуты живут до следующего релиза, дальше их почти никто не откроет.
- Что попадает. В чейнджлог — всё заметное снаружи, включая скучное: помеченные к удалению функции, закрытые уязвимости, изменения формата. В релиз-ноуты — только то, что человек заметит, открыв приложение.
- Каким языком. Чейнджлог сухой и точный: «изменён формат ответа
/api/orders». Релиз-ноуты — обычным человеческим: «заказы теперь грузятся быстрее». - Где живёт. Чейнджлог — файл в репозитории, рядом с кодом. Релиз-ноуты — карточка в сторе, страница релиза, письмо, экран «что нового» в приложении.
Есть и шестое отличие, техническое: чейнджлог курируют руками, а релиз-ноуты часто генерируют. У GitHub автосборка выдаёт список пул-реквестов, список авторов и ссылку на полное сравнение версий — удобно для разработчиков проекта, но пользователю такой текст не нужен.
Кому что подойдёт
Без увиливаний:
Ты делаешь библиотеку, пакет, API. Веди чейнджлог, он обязателен. Твой читатель — разработчик, и ему нужен полный список с пометками про совместимость, привязанный к номерам версий. Релиз-ноуты в этом случае не нужны вовсе: страница релиза может просто цитировать нужный кусок файла.
Ты делаешь приложение в сторе. Релиз-ноуты обязательны — поле всё равно придётся заполнить, вопрос лишь в том, будет там «исправлены ошибки» или что-то осмысленное. Чейнджлог полезен, но как внутренний документ.
Ты делаешь сайт или веб-сервис. Формально не обязано ничего. Практично — вести чейнджлог для себя и раз в несколько релизов писать короткую заметку «что нового» для пользователей.
Ты один и времени нет. Веди чейнджлог. Из него релиз-ноуты пишутся за две минуты обратным ходом: выбрал три самых заметных пункта и переписал по-человечески. В другую сторону не работает — из абзаца в сторе историю проекта не восстановить.
Как писать одно из другого
Рабочая схема простая, и она экономит всё время:
- Ведёшь чейнджлог по ходу дела, как единственный источник правды.
- Перед выкаткой смотришь в него и выбираешь два-три пункта, которые пользователь реально заметит.
- Переписываешь их без терминов: не «исправлена гонка в очереди задач», а «уведомления больше не приходят дважды».
- Всё, что не попало в эти три пункта, остаётся в файле и никуда не девается.
Правило отбора: если пункт нельзя закончить словами «...теперь тебе не придётся», в релиз-ноуты он, скорее всего, не нужен.
Главная ошибка: один и тот же текст везде
Соблазн понятный: написал один раз — вставил во все места. Разваливается это по трём причинам.
Момент чтения разный. Чейнджлог открывают после обновления, когда что-то отвалилось и надо понять почему. Карточку в сторе читают до — решая, обновляться ли вообще. Один текст не может одновременно объяснять поломку и продавать обновление.
Лимит. Пятьсот символов — это три-четыре строки. Вставив туда кусок чейнджлога, ты получишь обрубок на середине слова, причём обрежется, скорее всего, самое важное.
Язык. Лимит в сторе считается на каждый язык — то есть текст ещё и переводить. Чейнджлог обычно живёт на одном языке (чаще английском), и это нормально: его читатель — разработчик. А пользователю в его стране нужен его язык, иначе он просто пролистает.
Отсюда практический вывод: не копируй, а выжимай. Одна и та же работа описывается в двух документах по-разному, и это не дублирование, а перевод с языка изменений на язык пользы.
Обязательно ли вести оба?
Нет. Обязателен тот, у которого есть настоящий читатель. У библиотеки это чейнджлог, у приложения в сторе — релиз-ноуты. Второй документ заводи только тогда, когда почувствовал, что первого не хватает.
Что писать в сторе, если релиз чисто технический?
Правду в одну строку — «ускорили загрузку и починили пару мелких ошибок». Это честнее, чем шаблонное «исправления и улучшения», и лучше, чем выдумывать несуществующую функцию. Пустое поле в сторе тоже вариант хуже: люди читают эту карточку перед обновлением.
Можно ли автоматизировать релиз-ноуты полностью?
Автосборка — хорошая заготовка, но не финал. Она перечисляет всё смёрженное, включая внутренний рефакторинг, и говорит языком коммитов. Оставь автогенерацию себе как черновик и всегда правь руками верхние три строки — их прочитают, остальное почти нет.
Курс «Профессия 2027: ИИ-архитектор»: шаг за шагом от основ компьютера до своего приложения и первых клиентов. 543 коротких урока на телефоне.





