Перейти к основному содержимому

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

Релизы 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 — в продакшене или где угодно ещё — должно быть уверено, что этот тег никогда не изменится незаметно.