Версионирование и совместимость

Релизы Planeon версионируются единым номером vMAJOR.MINOR.PATCH (например, v1.4.2), который связывает воедино git-тег, шесть публикуемых образов контейнеров и контракт OpenAPI для этого релиза. Эта страница — политика, по которой живут эти номера: что меняется на каждом уровне, как ведут себя теги образов и как API и схема базы данных остаются совместимыми при обновлении.

Семантическое версионирование

• MAJOR повышается для breaking-изменений — всего, что обновление не может поглотить без осознанного шага с вашей стороны (удалённое поле API, переменная конфигурации, которая больше не работает так, как раньше).
• MINOR повышается для обратно совместимых новых возможностей.
• PATCH повышается для обратно совместимых исправлений ошибок.

Предварительные релизы добавляют суффикс через дефис, например v1.0.0-rc1 — см. Предварительные релизы ниже.

Теги образов контейнеров

Каждый релиз с тегом публикует шесть мультиархитектурных (linux/amd64 + linux/arm64) образов в Docker Hub под организацией planeon — api, worker, web, gateway, migrate, guacd. Каждый образ получает один или несколько тегов — в зависимости от того, является ли релиз предварительным:

Тег	Публикуется для	Поведение
vX.Y.Z	каждого релиза с тегом, включая предварительные	Неизменяемый. Всегда указывает на точную сборку этой версии; никогда не перезаписывается.
vX	только полноценных релизов, не предварительных	Плавающий. Переставляется на новейший релиз внутри мажорной версии X при каждом новом minor- или patch-релизе.
latest	только полноценных релизов, не предварительных	Плавающий. Переставляется на новейший релиз в целом.

Предварительные релизы

Тег версии, содержащий дефис (v1.0.0-rc1, v2.1.0-beta2, …), — предварительный релиз. Предварительные релизы публикуют только точный тег образа vX.Y.Z — они никогда не переставляют vX или latest, поэтому ничто, отслеживающее плавающий тег, не может неожиданно оказаться на release candidate. Соответствующий GitHub Release также помечается как prerelease.

Что должен закреплять production

Продакшен-развёртывания закрепляют точный тег vX.Y.Z — именно так делает deployments/production/compose.yaml через переменную PLANEON_VERSION — а не отслеживают vX или latest. Обновление должно быть тем, что вы выбираете и тестируете сами, а не тем, что происходит само собой при следующем перезапуске контейнера, скачавшего плавающий тег заново.

Совместимость API

Контракт OpenAPI (api/openapi/openapi.yaml) остаётся обратно совместимым на протяжении всего жизненного цикла мажорной версии. Внутри v1.x:

• существующие эндпоинты, поля и значения enum сохраняют свой смысл;
• могут добавляться новые эндпоинты, поля и значения enum;
• ничто уже опубликованное не удаляется и не переименовывается.

Удаление или переименование полей и эндпоинтов ждёт следующей мажорной версии. Клиент, написанный под контракт v1.0.0, продолжает работать без изменений с любым более поздним релизом v1.x.

Миграции базы данных

Миграции применяются только на добавление и только вперёд: как только файл миграции попадает в релиз, он больше никогда не редактируется и не удаляется, и отката (down-миграции) не существует. CI следит за этим на каждом pull request — изменение или удаление уже выпущенного файла миграции в migrations/ проваливает сборку.

Миграции также никогда не применяются автоматически процессами api или worker при старте. Обновление применяет ожидающие миграции отдельным явным шагом (docker compose run --rm migrate), который проходит гейт до раскатки образов сервисов. См. Обновление — полную последовательность бэкап → миграция → гейт → раскатка, и её раздел Откат о том, как отменить обновление — восстановлением резервной копии, снятой перед обновлением, поскольку отката миграции не существует.

Никогда не переназначайте тег релиза

Опубликованный vX.Y.Z — и git-тег, и соответствующие теги образов — неизменны навсегда. Если релиз вышел с ошибкой, исправьте её и опубликуйте новую patch-версию; никогда не делайте force-push git-тега и не пересобирайте и не перепубликовывайте тот же тег образа с другим содержимым. Всё, что закреплено на vX.Y.Z — в продакшене или где угодно ещё — должно быть уверено, что этот тег никогда не изменится незаметно.