Changelog (журнал изменений) — это список изменений продукта, расположенный в хронологическом порядке: что добавили, исправили или убрали в каждой версии. Его читают пользователи, клиенты и команда, чтобы понимать, что нового и что поменялось.
Журнал изменений ведут для библиотек, приложений, сайтов и сервисов. У разработчиков он часто лежит в репозитории в файле CHANGELOG.md, у продуктов для пользователей — на отдельной странице «Что нового» или «Обновления». Хороший changelog пишут человеческим языком и сразу показывают пользу, а не копируют технические сообщения коммитов. Он дополняет релизы: каждый выпуск версии сопровождается записью, что в нём изменилось.
Что в нём обычно есть
- Дата и номер версии.
- Группы изменений: «Добавлено», «Изменено», «Исправлено», «Удалено», «Безопасность». Такой порядок описан в популярной рекомендации Keep a Changelog.
- Короткое описание каждого изменения и, при необходимости, ссылка на подробности.
- Пометка о несовместимых изменениях, которые требуют действий от пользователя.
Пример
Запись для сервиса записи на услуги: версия 2.4, 12 октября. Добавлено: напоминания клиентам по SMS. Исправлено: ошибка с часовым поясом при записи на вечер. Изменено: страница оплаты стала загружаться быстрее.
Как вести changelog
- Записывайте изменения сразу при выпуске, а не по памяти через месяц.
- Пишите для пользователя: «Теперь можно перенести запись одним нажатием» вместо «Рефакторинг модуля записи».
- Группируйте по типам и ставьте свежие записи сверху.
- Указывайте дату в понятном формате и версию, если она есть.
- Выделяйте изменения, ломающие привычный сценарий, и объясняйте, что делать.
- Размещайте журнал там, где его легко найти: в меню, футере или внутри продукта.
Типичные ошибки
- Копировать историю коммитов целиком: пользователю она не нужна.
- Писать расплывчато: «улучшения и исправления» ничего не говорит.
- Не обновлять журнал месяцами. Пустой changelog выглядит как заброшенный продукт.
- Скрывать неприятные изменения: уход функции или смену условий лучше объяснить честно.
Чем отличается от релиз-нотов
Релиз-ноты — рассказ об одном выпуске, обычно с акцентом на главное. Changelog — полная история всех выпусков. Многие команды используют эти понятия как синонимы.
Кому и когда это нужно
Любому продукту, который развивается. Журнал показывает клиентам, что команда работает, облегчает поддержку и помогает самим разработчикам найти момент, когда что-то сломалось. Он также помогает продуктовой команде проверять, какие фичи уже выпущены.
Частый вопрос
Чем changelog полезен небольшому сайту? Он напоминает, что именно менялось: цены, разделы, формы. Для клиентов вроде студий или фрилансеров достаточно простого списка с датами, чтобы заказчик понимал историю работ и не путал версии.