Среды и версионирование

Два контура

Контур	Ветка	Где работает	Назначение
prod	main	Прод-хост, по ночному расписанию	Стабильный; всякое изменение приезжает осознанным промоушеном
dev	dev	Локальный dev-стек (Docker: Postgres, Redis, API, web)	Интеграция; вся повседневная работа сначала попадает сюда

Поток однонаправленный: фиче-ветки мержатся в dev мелкими PR; промоушен в main — отдельный, явно одобряемый шаг; деплой на прод-хост — отдельный скрипт после него. Хотфикс, вынужденно попавший в main напрямую, в той же сессии переносится в dev — main всегда подмножество dev.

Где это работает

Прод — один self-hosted Linux-сервер за reverse-proxy Caddy, доступный по имени динамического DNS на нестандартном порту (entherium.duckdns.org:8443). Это базовый URL во всех примерах портала, и он настоящий — управляемого API-шлюза и «красивого» домена перед ним пока нет. Флот сайтов назначения живёт на отдельных хостах. Для платформы на этой стадии сервер и есть прод: ночные прогоны, API, MCP-сервер и доска задач отвечают с него, а его доступность сторожит внешний dead-man’s switch.

Сама документация отдаётся из двух мест одной и той же сборкой: с API-хоста под /developers/ и с зеркала на Cloudflare Pages. Зеркало — каноническая копия (на неё указывают canonical и og:url каждой страницы), и оно живёт, даже если сервер лёг. Обе копии собираются из одного коммита одними скриптами; если они расходятся, новее зеркало.

Версионирование — две независимые оси

Ось A: модули платформы. Каждый модуль (platform, webui, contracts, сервисы, этот портал) версионируется по SemVer независимо, версии выводятся автоматически из истории коммитов — руками их не бампают. Зонтичная версия платформы отслеживает целое.

Ось B: версии пайплайнов. Collect, Generate и Localize версионируются отдельно в каталоге пайплайнов — с неизменяемыми директориями кода и пинами на контракт. Эта ось движется своим темпом: пайплайн может уйти на несколько версий вперёд внутри одного релиза платформы, и наоборот. См. Жизненный цикл версий.

Оси расцеплены сознательно: деплой платформы не меняет, какую версию пайплайна исполняет флот, а промоушен версии пайплайна не требует релиза платформы.

Что здесь значит «релиз»

• Смержено в dev — интегрировано, прошло гейт (линт, типы, тесты — локальный прогон как гейт мержа), пользователю ещё не видно.
• Промоушен в main + деплой — работает на прод-хосте.
• Включено — жёсткое правило платформы: фича считается задеплоенной, только когда она включена и её эффект наблюдаем (метрика, страница, число). Код за выключенным флагом в отчётах и документации — явно не «задеплоено».