114 lines
13 KiB
Markdown
114 lines
13 KiB
Markdown
---
|
||
aliases:
|
||
- changelog
|
||
tags:
|
||
- maturity/🌱
|
||
date: 2025-02-13
|
||
---
|
||
Changelog (журнал изменений) — это больше, чем просто список исправлений и новых фич. Это коммуникационный мост между разными участниками продуктовой команды и будущими версиями системы. Это способ зафиксировать эволюцию продукта, сделать его предсказуемым и понятным, а также избежать хаоса, который неизбежно наступает, когда изменения теряются в глубинах репозиториев или устных обсуждений.
|
||
|
||
Changelog — это структурированный журнал изменений в сервисе или продукте. Хороший сhangelog отвечает на три ключевых вопроса:
|
||
1. **Что изменилось?** (новые возможности, исправления, улучшения, депрекейшены)
|
||
2. **Почему это изменилось?** (какие проблемы решены, какие задачи стояли)
|
||
3. **Как это влияет на систему и пользователей?** (что нужно учесть при обновлении, есть ли [[../other/Backward compatibility|backward compatibility]])
|
||
|
||
**Зачем это нужно?**
|
||
- **Прозрачность**. Разработчики, DevOps-инженеры и даже пользователи должны понимать, что происходит с системой и как это влияет на их работу.
|
||
- **История развития**. Changelog фиксирует техническую эволюцию проекта и помогает анализировать причины изменений.
|
||
- Обратная совместимость. Понимание изменений помогает избежать неожиданных проблем при обновлении версий.
|
||
- **Взаимодействие с пользователями и заказчиками**. Хорошо написанный changelog упрощает адаптацию пользователей к новым версиям, а также служит маркетинговым инструментом, демонстрируя активное развитие продукта.
|
||
|
||
**Ограничения и возможные проблемы**
|
||
- **Слабая структура и хаос**. Если changelog ведется нерегулярно или его формат непоследователен, он теряет свою пользу.
|
||
- **Избыточность**. Если changelog превращается в поток технических подробностей, понятных только разработчикам, он перестает быть полезным.
|
||
- **Недостаточная детализация**. Формулировка «Исправлены баги» или «Улучшена производительность» не дает читателям никакой полезной информации.
|
||
|
||
**Типовая структура**
|
||
- **Изменения API**. Включает все изменения, влияющие на взаимодействие с внешними системами и пользователями API:
|
||
- Добавлено: новые эндпоинты, новые параметры запросов/ответов.
|
||
- Изменено: изменения контрактов API, изменения кодов ответов, обновление документации API.
|
||
- Удалено: устаревшие эндпоинты или версии API, удаленные параметры запросов/ответов.
|
||
- Введение новых ограничений (rate-limiting, авторизация и т. д.).
|
||
- **Изменения межсервисных взаимодействий**. Фиксируются изменения в том, какие сервисы вызывают друг друга и зачем. Сюда не включаются изменения API.
|
||
- Начали вызывать новый сервис.
|
||
- Перестали вызывать сервис
|
||
- Изменена схема вызова между сервисами
|
||
- billing теперь вызывается асинхронно через очередь вместо синхронного REST-запроса.
|
||
- **Изменения конфигураций**. Фиксирует изменения, влияющие на настройки системы:
|
||
- Новые переменные окружения.
|
||
- Изменение значений конфигурационных параметров.
|
||
- Введение новых фич-флагов.
|
||
- Изменения в форматах конфигурационных файлов.
|
||
- **Исправления багов**. Список устраненных проблем, влияющих на работу системы:
|
||
- Критические фиксы, вызывавшие падения или утечки памяти.
|
||
- Исправления в логике расчетов, валидации данных, обработке ошибок.
|
||
- Баги, связанные с интеграциями и совместимостью.
|
||
- Обновления зависимостей, исправляющие известные уязвимости.
|
||
- **Новый функционал**. В этом разделе фиксируются все новые возможности, которые появляются в системе:
|
||
- **Добавленные фичи**. Новые возможности, модули, крупные изменения в логике работы сервиса.
|
||
- **Новые сценарии использования**, появившиеся после обновления.
|
||
- **Поддержка новых технологий и интеграций**.
|
||
- **Технические изменения**. Изменения, которые не влияют напрямую на API, но важны для работы системы:
|
||
- Оптимизация алгоритмов и производительности.
|
||
- Рефакторинг кода и переработка архитектуры.
|
||
- Улучшение логирования (новые уровни логов, новые метрики).
|
||
- Обновления зависимостей.
|
||
- Изменения в CI/CD, механизме деплоя, мониторинге.
|
||
- **Устаревшие функции**. Функциональность, которая будет удалена в будущем, с указанием сроков и альтернатив:
|
||
- Устаревшие API и их замены.
|
||
- Удаляемые конфигурационные параметры.
|
||
- Фичи, которые больше не поддерживаются.
|
||
- **Действия при обновлении**. Что необходимо сделать перед или после обновления:
|
||
- Запуск миграций базы данных.
|
||
- Очистка кэша или пересборка индексов.
|
||
- Обновление конфигурации окружения.
|
||
- Ручной запуск скриптов или дополнительных процессов.
|
||
|
||
**Как писать полезный changelog?**
|
||
1. **Соблюдайте структуру**
|
||
2. **Changelog не должен быть черновиком разработки**
|
||
1. Если что-то добавили и потом убрали до релиза, этого никогда не существовало для пользователя.
|
||
2. Не нужно записывать историю разработки — changelog фиксирует только итоговые изменения.
|
||
3. **Пишите понятно**. Ваша целевая аудитория это люди, которые не погружены в ваш сервис.
|
||
1. Избегайте технического жаргона, если это не критично.
|
||
2. Описывайте изменения так, чтобы их мог понять человек, не знакомый с внутренним устройством системы.
|
||
3. Указывайте контекст: что исправлено и почему.
|
||
4. Фиксируйте причину изменений
|
||
4. Не просто «обновлен API», а «обновлен API для поддержки новых параметров, влияющих на X».
|
||
5. Добавляйте ссылки на тикеты, если это возможно.
|
||
5. **Обновляйте changelog перед релизом, а не после.** Changelog должен быть частью процесса разработки, а не постфактум-документом.
|
||
6. **Синхронизируйте с версиями.**
|
||
1. Используйте версионирование (например, [[../other/Семантическое версионирование|Semantic Versioning]]).
|
||
2. Если выпускается патч, changelog должен отражать только исправления ошибок, а не все изменения за последние месяцы.
|
||
|
||
**Процесс ведения changelog**
|
||
Чтобы changelog был полезным и актуальным, он должен вестись в рамках строгого процесса:
|
||
5. **Changelog фиксирует только выпущенные изменения**
|
||
1. В changelog должны попадать только те изменения, которые вошли в релиз
|
||
2. Если во время разработки что-то добавили, а затем удалили до выпуска версии, то это **не должно оставлять следов в changelog**. Например, если в SNAPSHOT-версии добавили API, а потом удалили его до релиза, то запись о нем просто удаляется, а не заменяется на «удалили API».
|
||
6. **Разработчик, выполняющий доработку, отвечает за корректное добавление записей в changelog**. Изменения не должны теряться — каждая доработка должна быть зафиксирована в changelog, а не оставаться только в коде или коммитах.
|
||
7. **Ревьювер обязан проверить наличие и корректность записей в changelog**.
|
||
- Проверка changelog становится такой же важной частью code review, как и сам код.
|
||
- Запись должна быть понятной, отражать суть изменений и быть написана простым языком.
|
||
- Ревьювер должен убедиться, что не попали временные изменения, не вошедшие в релиз.
|
||
|
||
**Дополнительные советы**
|
||
- Можно настроить сбор changelog на основе PR-описаний, но важно, чтобы в итоговый changelog попадали только финальные изменения. Генерация changelog из commit history (например, Conventional Commits) может помочь, но требует жесткой дисциплины.
|
||
- Если пользователи или команда часто задают вопросы по changelog, это сигнал, что его стоит делать понятнее.
|
||
- Можно тестировать понятность changelog, давая его прочитать коллегам, не участвовавшим в разработке изменения.
|
||
- Changelog старых версий не должен меняться после их выпуска.
|
||
|
||
***
|
||
## Мета информация
|
||
**Область**:: [[../../meta/zero/00 Эффективная разработка|00 Эффективная разработка]]
|
||
**Родитель**::
|
||
**Источник**::
|
||
**Создана**:: [[2025-02-13]]
|
||
**Автор**::
|
||
### Дополнительные материалы
|
||
-
|
||
|
||
### Дочерние заметки
|
||
<!-- QueryToSerialize: LIST FROM [[]] WHERE contains(Родитель, this.file.link) or contains(parents, this.file.link) -->
|
||
|