Политика версий и совместимости

Эта страница даёт короткий публичный ответ на взрослый командный вопрос:

• какие версии задают текущий baseline и какие обещания совместимости реально достаточно сильны, чтобы сделать их стандартом

Выбор за 60 секунд

• читайте эту страницу, когда команде нужен один компактный policy doc про релизы, wrappers, SDK, runtimes и обещания поддержки
• читайте Границу поддержки, когда нужен самый короткий summary текущего состояния
• читайте Релизы, когда нужна история изменений в конкретном релизе

Публичный baseline

Про версии здесь полезно думать в трёх слоях:

• release line, которую вы стандартизируете между repo
• support level пути внутри этой release line
• install или delivery mechanism вокруг этого пути

Эти слои связаны, но это не одно и то же.

Что именно покрывает versioning

Когда plugin-kit-ai говорит про совместимость, самое сильное публичное обещание относится к:

• заявленному публичному CLI contract
• рекомендованному пути через Go SDK
• стабильному локальному Python и Node subset на поддерживаемых runtime targets
• задокументированному поведению public-stable generated outputs

Совместимость здесь не означает, что каждый target, каждый wrapper и каждый convenience path движутся с одинаковой силой обещаний.

Stable baseline и moving edges

Держите в голове простое правило:

• public-stable можно считать нормальным кандидатом для продакшена
• public-beta можно использовать, но нельзя считать замороженным
• install wrappers нужно воспринимать как каналы доставки CLI, а не как runtime или SDK contract

Именно поэтому релиз может быть зрелым и production-worthy даже тогда, когда часть путей всё ещё остаётся beta.

Wrappers, SDK и runtime APIs

Одна из самых частых ошибок — смешивать эти категории.

• Homebrew, npm, PyPI и verified script — это install channels для CLI
• Go SDK — это публичная SDK surface
• runtime APIs привязаны к своим объявленным поддерживаемым runtime lanes

Если воспринимать install wrappers так, как будто они несут то же обещание совместимости, что и SDK, команда в итоге стандартизирует не тот слой.

Что командам стоит стандартизировать

Здоровые команды обычно стандартизируют:

• одну явную release baseline
• один основной путь с понятной историей поддержки
• один validation gate перед handoff и rollout
• одно общее понимание stable, beta и experimental

Здоровые команды не стандартизируют:

• wrapper package так, как будто это и есть продуктовый контракт
• beta convenience path так, как будто это самый сильный baseline
• один особенный repo так, как будто он задаёт default для всех остальных

Как безопасно читать release notes

Используйте release notes как источник guidance по изменениям, а не как единственное место, где живёт policy команды.

Безопасный порядок такой:

1. Держите одну baseline policy для команды.
2. Читайте release notes, чтобы понять, что изменилось относительно этого baseline.
3. Меняйте baseline только после того, как новый путь действительно соответствует вашим ожиданиям по поддержке.

Так команда не превращает каждую свежую деталь релиза в случайный новый стандарт.

С чего лучше продолжить

• Прочитайте Границу поддержки, если нужен самый короткий current contract framing.
• Прочитайте Модель стабильности, если нужно точное значение stable, beta и experimental.
• Прочитайте Каналы установки, если путаница на самом деле про wrapper installs и публичные API.
• Прочитайте v1.0.6, если нужен актуальный пользовательский baseline в этом наборе docs.

Финальное правило

Стандартизируйте только ту release line и тот путь, чьё публичное обещание ваша команда действительно готова защищать через CI, handoff и rollout.