# Contract: Module Versioning

Version: 1.0

## Purpose

Единое правило версионирования внутренних слоёв приложения:
плагины, парсеры, API-клиенты, адаптеры и прочие условные модули.

Модули — это логические слои внутри одного репозитория, не отдельные пакеты.

---

## Формат версии

```
N.M
```

- `N` — мажорная версия (целое число, начинается с 1)
- `M` — минорная версия (кратна 0.1, начинается с 0)

Примеры: `1.0`, `2.0`, `2.1`, `2.3`

---

## Правила инкремента

### N+1 — любая функциональная правка

Поднимаем мажор при **любом изменении функциональности**:

- добавление новой функции, метода, поля
- изменение существующего поведения
- удаление функциональности
- рефакторинг, меняющий структуру модуля
- изменение интерфейса взаимодействия с другими слоями

При инкременте мажора минор **сбрасывается в 0**: `2.3 → 3.0`

### N+0.1 — исправление бага

Поднимаем минор при **коротком точечном багфиксе**:

- исправление некорректного поведения без изменения интерфейса
- правка крайнего случая (edge case)
- исправление опечатки в логике

Функциональность при этом **не меняется**.

---

## Где хранить версию

Версия фиксируется в одном месте внутри модуля. Выбрать один из вариантов:

**Go** — константа в пакете:
```go
const Version = "2.1"
```

**Файл** — заголовок contract.md или README модуля:
```
Version: 2.1
```

**JSON/YAML конфиг** — поле `version`:
```json
{ "version": "2.1" }
```

Не дублировать версию в нескольких местах одного модуля.

---

## Git-тег (опционально)

Если модуль выпускается как отдельная поставка, тег ставится в формате:

```
<module-name>/v<N.M>
```

Примеры: `parser/v2.0`, `api-client/v1.3`

Тег ставится только на коммит, в котором обновлена версия внутри модуля.
Тег без обновления версии в коде — ошибка.

---

## Стартовая версия

Новый модуль начинается с `1.0`.
Версия `0.x` не используется.

---

## Инструкция для агентов (Codex, Claude)

**Обязательно при каждом коммите:**

1. Определи, к какому модулю относятся изменения.
2. Прочитай текущую версию модуля из канонического места (константа, заголовок, конфиг).
3. Выбери инкремент по правилу:
   - Изменяется поведение, добавляется или удаляется функциональность → **N+1**, минор сбросить в 0
   - Только исправление бага, поведение не меняется → **N+0.1**
4. Обнови версию в коде до коммита.
5. Включи новую версию в сообщение коммита: `feat(parser): add csv dialect — v2.0`

**Агент не должен делать коммит без обновления версии затронутого модуля.**

### Дерево решений

```
Изменения в модуле?
│
├── Да — это багфикс (логика была неверной, интерфейс не менялся)?
│   ├── Да → N+0.1
│   └── Нет → N+1, сброс минора в 0
│
└── Нет изменений в модуле → версия не меняется
```