Уроборос
Мать Учения«Мы делаем реально крутые вещи» — Зак Новеда
Войти

Версии и CHANGELOG

Схема версий проекта, что и когда пишем в CHANGELOG.md, как работают NEXT.md и package.json. Версия отражает зрелость продукта, а не API-контракт — bumping в конце каждой сессии.

Схема версий

Полу-семвер a.b.c:

  • c (patch) — счётчик чатов разработки. Каждый завершённый чат = +1 к c. Автоматически отражает темп работы.
  • b (minor) — новая пользовательская фича или раздел (задеплоена спека). Сбрасывает c в 0 при необходимости обозначить вехи.
  • a (major) — большой пивот или смена концепции продукта. На практике встречается редко.

Текущая версия в package.json: "version": "1.0.0" — это a=1, b=0, c=0.

Значение чисел прочитывается из CHANGELOG.md: там видно, что 0.9.0 — это появление /docs-раздела (май 2026), 0.4.25 — закрытие серии 009–015 (бухгалтерия).

CHANGELOG.md

CHANGELOG.md — user-facing хронология. Пишется в конце сессии, если был заметный прогресс (задеплоена спека, изменился UX, что-то сломано и починено).

Что пишем:

  • Новые фичи и экраны, заметные игроку или DM.
  • Изменения поведения, которые могут удивить (approval flow теперь pending).
  • Удалённые или переработанные части UI.

Что не пишем:

  • Рефакторинги без эффекта для пользователя.
  • Миграции, если не меняют поведение.
  • Инфра-работу (spec-023–028 — появились в CHANGELOG кратко, как «self-hosted Hetzner»).
  • Мета-работу: chatlog, документация, AGENTS.md.

Формат: заголовок ## a.b.c — месяц год, затем подзаголовки по фичам с пулл-листом. Язык — русский, ориентирован на игроков и DM, не на разработчиков.

NEXT.md и его секции

NEXT.md — не changelog, а текущее состояние. Читается ботом (bash scripts/dev/status.sh) и Claude в начале каждого чата. Ключевые секции:

  • ## Прод — URL, деплой-схема, staging, бэкапы, доступы к боксу.
  • ## Дедлайны — только активные дедлайны с датами. status.sh подсвечивает просроченные.
  • ## Активная работа — что именно сейчас делается, со ссылкой на tasks.md.
  • ## В проде — таблица закрытых спек одной строкой.
  • ## Правила — ссылки на AGENTS.md и meta/claude-project-instructions.md.

Лимит файла: 150 строк / 10 KB. История уходит в CHANGELOG.md и chatlog/, не накапливается здесь.

Когда делать bump

Bump происходит в конце сессии, вместе с обновлением NEXT.md и CHANGELOG.md.

СобытиеТип bump
Очередной чат, нет задеплоенной фичи+1 к c (в package.json и NEXT.md)
Задеплоена спека / новый раздел в UIminor: b+1, c=0
Крупный пивот (новая модель данных, смена концепции)major: a+1, b=0, c=0

Bump делается в mat-ucheniya/package.json ("version"). Число чата видно в шапке NEXT.md строкой Last updated: YYYY-MM-DD (chat NN — …).

Синхронизация package.json

package.json в mat-ucheniya/ — единственный машиночитаемый источник версии. scripts/dev/status.sh читает его через grep '"version"' и печатает в первой строке вывода. Если package.json и NEXT.md расходятся — статус-скрипт не кричит, но NEXT.md Last updated — это источник истины для номера чата.

См. также: README.md, chatlog-and-memory.md.