docs: add agent bootstrap and contract read router
This commit is contained in:
Mikhail Chusavitin
61
rules/patterns/module-versioning/README.md
Normal file
61
rules/patterns/module-versioning/README.md
Normal file
@@ -0,0 +1,61 @@
|
||||
# Module Versioning Pattern Notes
|
||||
|
||||
This file keeps examples and the decision tree. The normative rules live in `contract.md`.
|
||||
|
||||
## Version Format
|
||||
|
||||
```text
|
||||
N.M
|
||||
```
|
||||
|
||||
Examples:
|
||||
|
||||
- `1.0`
|
||||
- `2.0`
|
||||
- `2.1`
|
||||
- `2.3`
|
||||
|
||||
## Canonical Storage Options
|
||||
|
||||
Go constant:
|
||||
|
||||
```go
|
||||
const Version = "2.1"
|
||||
```
|
||||
|
||||
Document header:
|
||||
|
||||
```text
|
||||
Version: 2.1
|
||||
```
|
||||
|
||||
Config field:
|
||||
|
||||
```json
|
||||
{ "version": "2.1" }
|
||||
```
|
||||
|
||||
## Tag Format
|
||||
|
||||
```text
|
||||
<module-name>/v<N.M>
|
||||
```
|
||||
|
||||
Examples:
|
||||
|
||||
- `parser/v2.0`
|
||||
- `api-client/v1.3`
|
||||
|
||||
## Decision Tree
|
||||
|
||||
```text
|
||||
Module changed?
|
||||
-> no: version unchanged
|
||||
-> yes: behavior or interface changed?
|
||||
-> yes: N+1, reset minor to 0
|
||||
-> no: narrow bugfix only -> N+0.1
|
||||
```
|
||||
|
||||
## Commit Reminder
|
||||
|
||||
If a commit changes a module, the same commit should update the module version.
|
||||
@@ -9,114 +9,15 @@ Version: 1.0
|
||||
|
||||
Модули — это логические слои внутри одного репозитория, не отдельные пакеты.
|
||||
|
||||
---
|
||||
See `README.md` for examples and the decision tree.
|
||||
|
||||
## Формат версии
|
||||
## Rules
|
||||
|
||||
```
|
||||
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
|
||||
│
|
||||
└── Нет изменений в модуле → версия не меняется
|
||||
```
|
||||
- Module version format is `N.M`.
|
||||
- New modules start at `1.0`. `0.x` is not used.
|
||||
- Any functional change bumps the major version and resets minor to `0`.
|
||||
- A narrow bugfix that does not change behavior or interface bumps minor by `0.1`.
|
||||
- Store the version in one canonical place only: code constant, module document header, or config field.
|
||||
- If the module is tagged separately, use `<module-name>/v<N.M>`.
|
||||
- Do not create a tag without updating the module's canonical version first.
|
||||
- When a commit changes a module, update that module's version in the same commit.
|
||||
|
||||
Reference in New Issue
Block a user