Git-история, changelog и журнал эксперимента: что именно фиксировать при изменениях
Когда после обновления поведение системы меняется, команде обычно нужно ответить сразу на несколько разных вопросов. Что было изменено в коде. Что вошло в релиз. Что именно происходило во время проверки и какие наблюдения были получены. Проблема в том, что эти три вопроса часто пытаются закрыть одним объектом, чаще всего списком commit.
Но Git-история, changelog и журнал эксперимента решают разные задачи. Если смешать их роли, возникает знакомая ситуация: код вроде бы зафиксирован, релиз отмечен, а объяснить условия проверки и последовательность событий всё равно трудно. Поэтому полезно сразу развести три слоя фиксации изменений: историю репозитория, описание существенных изменений релиза и журнал фактических событий эксперимента.
Git history, changelog и experiment log отвечают на разные вопросы
Эти три объекта связаны между собой, но не заменяют друг друга.
| Объект | На какой вопрос отвечает | Что обычно фиксирует | Чего от него не стоит ждать |
|---|---|---|---|
| Git history | Что изменилось в репозитории | Commit, автор, дата, diff, merge, tag | Понятного объяснения, почему изменение важно для релиза или проверки |
| Changelog | Что существенного вошло в версию или релиз | Добавления, исправления, изменения, удаление, breaking changes | Полной технической истории и условий инженерной проверки |
| Журнал эксперимента | Что произошло во время проверки, когда и в каких условиях | Состояния системы, событие изменения, окружение, время, наблюдения, артефакты | Замены Git-истории или release notes |
Практический смысл этого разделения простой. Git хорошо показывает изменение кода. Changelog помогает быстро понять содержание версии. Журнал эксперимента нужен, когда важно восстановить ход проверки и связать событие изменения с наблюдаемым результатом.
Git-история фиксирует изменение кода, а не историю всего эксперимента
Git создавался как распределённая система контроля версий. В репозитории сохраняются commit, ссылки между ними, ветки, теги и изменения файлов. Это делает Git удобным источником правды о состоянии кода и развитии проекта.
Но даже хорошая commit history не отвечает автоматически на вопросы инженерной проверки.
- Какое состояние системы было до начала сравнения.
- Какая конфигурация использовалась в момент запуска.
- Какая нагрузка подавалась на систему.
- Когда именно выполнялась проверка.
- Что произошло между запуском версии A и версии B кроме изменения кода.
Например, несколько commit могли войти в один релиз. Один commit мог быть засквошен. Изменение могло быть перенесено через cherry-pick. Наконец, код мог остаться тем же, а поведение системы изменилось из-за конфигурации, runtime или среды выполнения.
Поэтому Git-история отвечает на важный, но ограниченный вопрос: что изменилось в репозитории и как это изменение связано с другими версиями кода.
Чтобы это имело смысл для последующего сравнения, полезно заранее зафиксировать исходное состояние системы. Тогда commit или tag будет связан не с абстрактной версией кода, а с конкретным состоянием приложения.
Changelog нужен не для всех commit, а для значимых изменений версии
В changelog обычно попадает не вся история репозитория, а только изменения, которые важно сообщить команде, пользователю или интегратору. Это может быть новый функциональный блок, исправление ошибки, изменение поведения API, удаление устаревшей возможности или breaking change.
Поэтому changelog почти всегда короче и грубее, чем Git-история. Он жертвует полнотой ради понятности.
Подход Keep a Changelog прямо предлагает описывать изменения по категориям вроде Added, Changed, Fixed, Removed и указывать только то, что действительно полезно читать как историю версий. Аналогично semantic versioning помогает обозначить масштаб изменения версии, но не пытается подменить собой технический журнал.
У changelog другая аудитория и другая задача. Он нужен, чтобы быстро понять, что нового или важного появилось в версии, а не восстановить пошаговую картину проверки системы.
Журнал эксперимента фиксирует не только изменение, но и условия события
Если команда проверяет влияние изменения на систему, к commit и changelog добавляется ещё один объект — журнал эксперимента.
Он отвечает на вопрос:
«Что именно произошло во время проверки, когда это произошло и при каких условиях были получены наблюдения?»
В такой журнал обычно имеет смысл включать:
- проверяемый вопрос или гипотезу;
- ссылку на исходное состояние системы;
- идентификатор версии или build, который участвует в проверке;
- существенные параметры окружения и конфигурации;
- workload или сценарий проверки;
- время изменения и время измерений;
- наблюдения после изменения;
- ссылки на логи, отчёты, дашборды и другие артефакты;
- побочные события, которые могли повлиять на интерпретацию результата.
Ключевой момент здесь в том, что журнал эксперимента должен фиксировать не только факт изменения, но и контекст, в котором это изменение проверялось.
Именно поэтому одна строка вроде «commit abc123 улучшил производительность» слишком сильна. Commit может относиться к изменению кода, а утверждение об улучшении относится уже к наблюдаемому результату в конкретных условиях.
Почему списка commit почти всегда недостаточно
Иногда кажется, что достаточно сослаться на merge request, и вся история уже восстановима. На практике этого мало.
Merge request может хорошо объяснять намерение автора и показывать diff. Но он не обязан сохранять:
- точное состояние системы до запуска;
- отдельные параметры тестовой нагрузки;
- даты и время повторных измерений;
- побочные изменения среды;
- отрицательные или неоднозначные результаты.
Даже если часть этого содержится в обсуждении задачи, она часто распределена по разным местам: issue tracker, CI, дашборд, release note, мониторинг, заметка исследователя. Журнал эксперимента ценен именно тем, что связывает эти части в одну последовательность.
Что полезно включить в минимальный журнал эксперимента
Такой журнал не обязан быть большим документом. Для многих инженерных задач достаточно компактной карточки записи.
| Поле | Что стоит зафиксировать |
|---|---|
| Дата и время | Когда произошло изменение и когда были получены наблюдения |
| Вопрос проверки | Какое изменение и какое ожидаемое свойство проверяются |
| Исходное состояние | Ссылка на baseline или карточку состояния до изменения |
| Версия / build | Commit, tag, release или другой идентификатор проверяемой версии |
| Окружение | Существенные параметры среды, инфраструктуры и конфигурации |
| Workload | Какой сценарий, данные или нагрузка использовались |
| Наблюдение | Что фактически произошло после изменения |
| Артефакты | Логи, отчёты benchmark, дашборды, ссылки на CI и другие материалы |
| Сопутствующие события | Что ещё менялось в тот же период и может влиять на чтение результата |
Такая запись уже не подменяет Git и не дублирует changelog. Она фиксирует тот слой, который чаще всего теряется между кодом и интерпретацией результата.
Связь между тремя слоями лучше делать через идентификаторы
Чтобы Git-история, changelog и журнал эксперимента не жили отдельно, их удобно связывать явными идентификаторами.
На практике это обычно выглядит так:
- в Git существует commit, tag или build ID;
- в changelog эта версия описана как релиз или набор значимых изменений;
- в журнале эксперимента тот же идентификатор используется как ссылка на проверяемое состояние системы.
Тогда из записи эксперимента можно перейти к changelog и понять, что именно вошло в релиз. А из changelog или release tag можно дойти до точной истории изменений в репозитории.
Без этой связки начинает происходить типичная подмена. Команда помнит, что «проверяли релиз 2.4.0», но быстро выясняется, что в тестовую среду попала промежуточная сборка, а часть конфигурации относилась уже к следующему деплою.
Журнал эксперимента не должен притворяться выводом
Есть ещё одна важная граница. Журнал нужен для фиксации события, условий и наблюдения. Он не должен автоматически превращать последовательность событий в окончательное причинное объяснение.
Если в 10:00 была развернута новая версия, а в 10:30 изменилось время ответа, в журнале полезно записать оба факта и временную связь между ними. Но формула «версия X стала причиной улучшения» требует уже отдельной интерпретации.
Именно здесь начинается более широкий инженерный подход к эксперименту, где различаются событие, наблюдение, временная связь и причинное объяснение.
Где заканчивается Git и начинается инженерная проверка
Git помогает восстановить историю кода. Changelog делает видимыми значимые изменения версии. Журнал эксперимента связывает изменение с условиями проверки и наблюдаемыми результатами.
Если использовать только один из этих объектов, два других вопроса всё равно останутся без ответа. Поэтому полезно не выбирать между ними, а распределять роли правильно.
Для инженерной практики это означает простое правило: код, релиз и эксперимент лучше фиксировать как три разные, но связанные линии истории. Тогда через несколько недель после запуска можно восстановить не только то, что менялось, но и то, как именно это изменение проверялось.
Источники
Технические источники проверены 19 августа 2026 года. Использованы официальные материалы Git, Keep a Changelog, SemVer и Google SRE.