voidea/template/docs/04-versioning.md

Версионирование

Формат: SemVer

MAJOR.MINOR.PATCH

• MAJOR: несовместимые изменения API
• MINOR: новая функциональность (обратно совместимо)
• PATCH: исправления багов

CHANGELOG

Где хранить: CHANGELOG/

Правила:

• Каждая MAJOR версия → новый файл: CHANGELOG/v1.0.md
• Каждая MINOR версия → новый файл: CHANGELOG/v1.1.md
• PATCH дописывается в существующий файл

CHANGELOG/
├── v1.0.md   # 1.0.0 → 1.0.5
├── v1.1.md   # 1.1.0 → 1.1.3
└── v2.0.md   # 2.0.0 → ...

Conventional Commits

Каждый коммит должен соответствовать формату:

<тип>[optional scope]: <описание>

[optional body]
[optional footer]

Тип	Действие	Влияние на версию
feat	Новая функция	MINOR
fix	Исправление	PATCH
BREAKING	В теле или ! после типа	MAJOR
docs	Документация	—
refactor	Рефакторинг	—
test	Тесты	—
chore	Обслуживание	—

Agent Versioning (если используются агенты)

Каждый агент версионируется независимо от проекта по A.B.C.

Правила бампа

Компонент	Когда меняется	Кто меняет
A (major)	Breaking change в публичном интерфейсе	EvolutionAgent
B (minor)	Новая capability (метод, роль, prompt)	EvolutionAgent
C (patch)	Внутренние правки, без изменения поведения	Сам агент (авто)

Механика

1. Агент запускается → вычисляет SHA256 checksum своего __file__
2. Сравнивает с хранимым checksum (в БД или в changelog файле)
3. Не совпал → авто-бамп patch → запись в changelog → обновление checksum
4. EvolutionAgent управляет minor/major бампами

Хранение

CHANGELOG/agents/<agent_name>.md

Формат:

# audit_agent Changelog
<!-- checksum: sha256hash -->

## 1.0.2 (2026-05-10)
- Fixed: описание исправления

## 1.0.1 (2026-05-09)
- Fixed: ещё одно исправление

## 1.0.0 (2026-05-08)
- Initial version

Разделение ответственности

Аспект	Владелец	Где хранится
Версия проекта	SpecAgent (или человек)	project.yaml, CHANGELOG/v*.md
Версия агента	EvolutionAgent	AgentConfig.version (БД)
Changelog проекта	SpecAgent (или человек)	CHANGELOG/v*.md
Changelog агента	EvolutionAgent	CHANGELOG/agents/<name>.md