Release‑процесс — версии, заметки, миграции SDK/спек, feature flags, rollback

1. Почему release‑процесс для ChatGPT App сложнее обычного деплоя

В прошлой части модуля мы говорили, как наблюдать за качеством и стабильностью App (логи, метрики, SLO). Теперь разберёмся, как устроить сам release‑процесс так, чтобы эти метрики не рушились при каждом деплое.

В обычном веб‑приложении всё более‑менее просто: вы задеплоили новую версию бэкенда и фронтенда — пользователь обновил страницу и живёт на новой версии. Если что‑то сломалось, часто можно просто откатить деплой.

В ChatGPT App стек хитрее. У вас есть как минимум четыре слоя, которые живут разными жизнями:

• Манифест и схема инструментов (MCP tools / OpenAPI);
• Инфраструктура: Next.js‑приложение и MCP/Agents/ACP сервер;
• System‑prompt и прочие промпты;
• Данные: product feed, настройки, конфиги.

Проблема в том, что модель живёт в своём «умственном мире». Контекст чата может тянуться часами и днями. Манифест и описания tools подгружаются и кэшируются со стороны OpenAI и не обновляются мгновенно во всех существующих диалогах. Если вы взяли и поменяли сигнатуру инструмента (например, удалили поле из input‑schema), то в старых диалогах модель продолжит слать старый payload, а ваш новый backend будет его отвергать. В итоге — ошибки 400, странные ответы в чате и очень грустные пользователи.

Поэтому в мире ChatGPT App «релиз» — это не просто «задеплоить новый Docker». Это координированное изменение нескольких слоёв, с аккуратным управлением версиями, фича‑флагами и возможностью откатиться.

2. Матрица версий: что вообще версионировать

Полезно смотреть не просто на «версию App 1.3», а сразу на матрицу версий по слоям. Для GiftGenius это примерно так.

giftgenius-app 1.4.2

tools-schema v1.7

prompt v3.1

feed v2, acp v1.3

Заметьте, это разные оси. Вы можете выпустить версию 1.4.2 приложения, в которой schema tools останется v1.7, а prompt перейдёт на v3.2. В логах это должно быть видно; так потом легче разбираться, почему после prompt v3.2 вдруг упала конверсия checkout.

Для кода удобно использовать семантическое версионирование (SemVer): MAJOR.MINOR.PATCH. MAJOR — ломающее изменение, MINOR — новые фичи без поломок, PATCH — багфиксы. Для интерфейсных версий (schema, prompts) логика похожая: MAJOR сигнализирует breaking‑change.

Отдельно стоит выделить версию интерфейса tools. Для LLM это критически важно: если вы меняете контракт инструмента, а модель «думает», что контракт старый, начинается веселье. Поэтому политика обычно такая: в MINOR‑релизах мы только добавляем новые опциональные поля и не переименовываем/не удаляем старые; breaking‑изменения — только через новый инструмент, например suggest_gifts_v2.

Теперь, когда мы разделили слои по версиям, давайте посмотрим, как эти версии вообще «живут» в релиз‑цикле — от dev до prod.

3. Базовый release‑flow для GiftGenius

Сначала давайте договоримся об этапах. Скорее всего у вас уже есть окружения (из модуля про deploy), но теперь посмотрим на них сквозь призму релизов.

Обычно выделяют:

• dev — локальная разработка, Dev Mode в ChatGPT, туннели;
• staging — максимально похоже на прод: тот же тип базы, тот же тип MCP/ACP, но тестовые данные и платежи в sandbox;
• prod — боевое окружение, то, куда подключён продовый ChatGPT App / Store‑листинг.

Процесс может выглядеть так:

flowchart TD
  A[Dev: ветка feature/*] --> B[PR → main]
  B --> C[CI: unit + contract + lint]
  C --> D[Deploy to Staging]
  D --> E[Smoke/E2E + ручная проверка]
  E --> F[Deploy to Prod]
  F --> G[Наблюдение по метрикам и логам]

На каждом шаге мы добавляем «предохранители». В dev‑окружении разработчик может творить что угодно, но каждое слияние в main триггерит CI, который запускает unit/contract‑тесты. Если всё ок — автоматически выкатываем на staging. На staging запускаем короткий набор E2E/смоук‑сценариев: например, один полный флоу подбора подарка и «фейковый» checkout в тестовой платёжке.

И только после этого нажимаем кнопку deploy в prod. Желательно — с пометкой версии и ссылкой на CHANGELOG. Уже в проде продолжаем смотреть на p95, error‑rate и бизнес‑метрики (конверсия из рекомендации в checkout). Если после релиза что‑то падает — у нас должен быть понятный rollback‑план, о котором поговорим ниже.

4. Release notes и changelog: что именно записывать

Если у вас нет релиз‑заметок, через месяц вы будете смотреть на график: «а почему 3 недели назад у нас p95 checkout вырос в 2 раза?» и отвечать себе «понятия не имею, но у нас был большой релиз». Не лучшая стратегия.

Обычно есть как минимум два вида заметок.

Внутренний changelog — технический. Он нужен разработчикам, SRE и всем, кто ковыряется в коде. Там пишут, какие фичи появились, какие баги пофиксили, были ли breaking changes. Формат можно взять по канону Keep a Changelog: секции Added, Changed, Fixed, Removed.

Внешние release notes — человекочитаемые заметки для пользователей и для Store. Там не нужно писать «migrate MCP SDK 0.4 → 0.5»; лучше написать «Добавили рекомендации для праздника Thanksgiving», «Исправили редкий баг, из‑за которого некоторые подарки не добавлялись в корзину».

Пример кусочка CHANGELOG.md для GiftGenius:

## [1.4.0] - 2025-11-20
### Added
- Новый tool `suggest_gifts_v2` с поддержкой тэгов интересов.
- A/B-тест нового system-prompt (flag: GG_PROMPT_V3).

### Changed
- Улучшена обработка ошибок ACP checkout (более дружелюбные сообщения).

### Fixed
- Исправлен баг, из-за которого товары без картинки скрывались из рекомендаций.

Полезно где‑то рядом хранить и версию промпта: даже просто коммит‑хеш файла с system‑prompt, который потом можно вспомнить: «ага, после промпта b3f9c2d пользователи стали реже нажимать “Купить”».

5. Миграции SDK и спецификаций: как жить в быстро меняющейся экосистеме

Экосистема вокруг Apps SDK, MCP и Agents развивается быстро: новые версии SDK, изменения протокола MCP, обновления ACP и т.д. Это хорошо (появляются возможности), но и болезненно: сломаться тоже может быстро.

Pinning версий и «не обновляемся в день релиза»

Первая простая рекомендация: фиксируйте версии зависимостей. Не ^0.4.0, а 0.4.0. Для SDK, которые часто ломают API (MCP/Agents/Apps SDK), это особенно критично. Я изучал исследования по этой теме, и в них отдельно отмечали феномен «SDK fatigue» — усталость от постоянных несовместимых апдейтов, которую особенно чувствуют те, кто оставил зависимости с плавающими версиями (типа ^0.4.0) и однажды внезапно поймал кучу ошибок после npm install.

Мини‑пример:

// package.json (фрагмент)
{
  "dependencies": {
    "@modelcontextprotocol/sdk": "0.4.2",
    "@openai/applications-sdk": "0.3.1"
  }
}

Вторая рекомендация: не тянуть в один и тот же релиз и бизнес‑фичи, и крупные миграции SDK. Если вам нужно обновить MCP SDK с 0.3.x до 0.4.x, лучше сделать отдельный технический релиз: сначала обновление SDK, тесты и стабилизация, а уже затем — новый checkout‑флоу.

Стратегия миграции SDK

Обычно разумный план выглядит так:

В dev‑окружении создаёте отдельную ветку upgrade/mcp-sdk-0.4. Обновляете зависимость, правите код, гоняете все unit/contract‑тесты, локально прогоняете основной флоу GiftGenius через Dev Mode.

Затем деплоите эту ветку на отдельный staging‑URL и гоняете по нему E2E/смоук‑тесты. Можно даже сделать небольшой нагрузочный тест: 50–100 вызовов suggest_gifts подряд.

Если всё ок — мержите в main, деплоите на основной staging, ещё раз прогоняете смоук, и только потом — в прод.

Если нет — у вас есть очевидный rollback: просто не мержить эту ветку или откатить её. В этом и смысл разнесения SDK‑миграций и продуктовых релизов.

Миграции схем tools и API

Самая неприятная часть — это интерфейсные изменения: модель про них узнаёт не мгновенно. Исследования по этой теме особенно выделяют важное правило: «Расширяй, но не ломай» (additive‑only). Если вам нужно добавить в suggest_gifts новый аргумент interests: string[], делайте его опциональным, а не обязательным; старые сценарии продолжат работать.

Пример эволюции Zod‑схемы для входных данных:

// v1
const suggestGiftsInputV1 = z.object({
  recipientName: z.string(),
  budget: z.number()
});

// v1.1 (добавили опциональные поля)
const suggestGiftsInputV1_1 = suggestGiftsInputV1.extend({
  interests: z.array(z.string()).optional(),
  occasion: z.string().optional()
});

Обратите внимание: мы не трогаем существующие поля, только расширяем.

Если же нужно реально сломать контракт (например, заменить budget на minBudget + maxBudget), лучше сделать новый инструмент suggest_gifts_v2 и указать в описании, что это улучшенная версия. Старое API можно оставить как deprecated и постепенно его выключить, когда убедитесь, что модель и пользователи переехали.

Миграции данных: product feed и ACP

Мы уже поговорили про миграции SDK и схем tools. Product feed — это тоже контракт. Если вы меняете формат SKU, валют, локализаций, это нужно делать координировано: обновить и схему фида, и обработку в MCP/ACP, и любые предобработчики. В документации по commerce для ChatGPT App отмечают, что ошибки в фиде (битые поля, дубликаты, странные цены) могут убить качество рекомендаций даже при идеальном коде.

Типичный подход:

1. Сначала добавляете новые поля в схему фида как опциональные и учите GiftGenius их использовать, если они есть.
2. Потом обновляете пайплайн, который строит feed, чтобы он начал заполнять эти поля.
3. Запускаете валидатор фида (contract‑тесты на данные) и только после этого начинаете зависеть от этих полей в логике.

6. Feature flags: отделяем deploy от release

Фича‑флаги (feature flags) — один из главных инструментов выживания в мире ChatGPT App. Основная идея проста: вы деплоите код, но не обязательно сразу включаете новую функциональность. Сначала она живёт «под флагом» — включена только для разработчиков, или для 1% пользователей, или вообще выключена.

Это особенно важно, когда:

• вы выкатываете новый алгоритм рекомендаций;
• вы меняете system‑prompt (а это может радикально поменять поведение модели);
• вы подключаете дорогой или медленный инструмент;
• вы экспериментируете с новым checkout‑флоу.

Простой флаг через env‑переменные

На минималках фича‑флаг можно сделать через переменную окружения:

// lib/features.ts
export const isNewRecoEnabled =
  process.env.NEXT_PUBLIC_GG_NEW_RECO === "1";

Дальше в коде MCP‑инструмента вы можете использовать это так:

if (isNewRecoEnabled) {
  return runNewRecoAlgorithm(input);
}
return runOldRecoAlgorithm(input);

Плюс такого подхода — простота. Минус — переключать флаги в рантайме сложнее: нужно деплоить новое окружение или хотя бы переинициализировать.

Централизованный helper с контекстом

Чуть более взрослый подход — иметь централизованный хелпер, который учитывает не только глобальные флаги, но и контекст пользователя (тенант, сегмент, A/B‑группа).

// lib/featureFlags.ts
type Feature = "new-reco" | "checkout-v2";

type Context = { userId: string; tenantId?: string };

export function isFeatureEnabled(
  feature: Feature,
  ctx: Context
): boolean {
  // здесь может быть логика: env, БД, внешний флаг-сервис
  if (feature === "new-reco") {
    return process.env.GG_NEW_RECO === "1";
  }
  return false;
}

В MCP‑handler:

const enabled = isFeatureEnabled("new-reco", { userId });
const result = enabled
  ? await runNewReco(input)
  : await runOldReco(input);

Если вы когда‑нибудь подключите внешний сервис флагов (LaunchDarkly, Statsig и т.д.), достаточно будет поменять реализацию isFeatureEnabled, а не весь код.

Примеры сценариев для GiftGenius

A/B‑тест system‑prompt. Вы создаёте PROMPT_V2 и включаете его только для 10% пользователей с tenantId в определённом списке. При этом MCP‑инструменты и виджет не меняются, а вы сравниваете конверсию.

Kill‑switch для дорогого инструмента. Допустим, вы сделали инструмент, который делает сложный внешний запрос (например, к какой‑нибудь ML‑модели рекомендаций, которая стоит дорого). Если этот внешний сервис начнёт падать или резко подорожает, вы хотите в одну секунду отключить его, не останавливая GiftGenius целиком. Фича‑флаг — самый простой способ.

Постепенный rollout нового checkout‑флоу. Checkout v2 вы сначала включаете только для сотрудников компании и пары доверенных клиентов. Если метрики ок — расширяете аудиторию, пока не включите для всех.

7. Rollback: как быстро откатываться, когда всё горит

Даже при идеальных тестах и флагах что‑то да сломается. Важно, чтобы у вас была понятная стратегия: что вы делаете в первые 5–15 минут после того, как увидели всплеск ошибок или просадку метрик.

Быстрый rollback кода

Если проблема в чисто технической баге (NPE, не та переменная, неверный URL внешнего сервиса), обычно достаточно откатить деплой к предыдущей версии. Например, на Vercel есть моментальный rollback на предыдущий deployment.

Ваша задача — всегда знать, какой deployment соответствует какой версии и как его откатить. В идеале это описано в README для on‑call: «если после релиза 1.4.0 всё горит, откатиться на deployment X».

Второй быстрый рычаг — фича‑флаги. Если упала только новая фича (checkout-v2), вам проще выключить её флагом, чем сразу откатывать весь релиз.

Опасные изменения: манифесты и схемы

С манифестами и схемами сложнее. Если вы залили в Store новый манифест с неправильной схемой tools, и его уже одобрил OpenAI, откат может занять дни. Причина простая: каждое изменение манифеста тоже проходит через ревью OpenAI. В аналитике по различным Store прямо говорится, что изменения манифеста и схем — «опасные» релизы, которые нужно готовить и тестировать особенно аккуратно.

Поэтому лучше разделять:

• безопасные релизы: изменения кода MCP/Next.js, правки промптов, новые фичи, спрятанные за флагами;
• опасные релизы: изменения в списке tools, input/output‑схемах, ACP‑контрактах.

«Опасные» релизы стоит раскатывать отдельно, с дополнительными проверками и, возможно, сначала только через Dev Mode и staging‑App (без публикации в Store).

Rollback данных и feed’а

С данными ситуация ещё сложнее (и больнее). Если вы мигрировали product feed на новую схему и при этом удалили старые поля, вернуть всё назад не всегда тривиально. Поэтому миграции данных должны быть идемпотентными и обратимыми: либо вы сохраняете старую копию, либо делаете миграцию в два шага (сначала дублируете данные, потом переключаете чтение).

Простой подход — хранить старые и новые поля какое‑то время параллельно и дать себе возможность переключаться между ними через фичу‑флаг. Если что‑то падает — вы просто возвращаетесь к старому чтению.

8. Мини‑дизайн release‑процесса для GiftGenius

Давайте соберём всё, о чём говорили выше (версии, SDK‑миграции, feature flags, rollback), в один практический сценарий.

Представим, что вы пилите релиз 1.4.0, в котором:

• добавляете новый инструмент suggest_gifts_v2 c расширенным input;
• включаете новый system‑prompt для части пользователей;
• обновляете MCP SDK с 0.3 → 0.4;
• меняете формат product feed (добавляете поле tags).

Разумный план выглядел бы так.

Сначала отдельный технический релиз 1.3.1: обновление MCP SDK + минимальные правки кода, без изменений схем и фич. Гоняете CI, staging, смоук‑тесты. Если всё стабильно — живёте с этим пару дней.

Затем ветка feature/reco-v2. Там вы добавляете suggest_gifts_v2 как новый инструмент (старый suggest_gifts остаётся). Его input‑схема расширяется только в сторону добавления новых опциональных полей. Подготавливаете новый system‑prompt, но оборачиваете его в флаг GG_PROMPT_V3. В ACP/фиде добавляете новое поле tags как необязательное, а чтение делаете так, чтобы при его отсутствии всё продолжало работать.

В CI добавляете несколько новых contract‑тестов: что suggest_gifts_v2 принимает старый и новый payload, что feed с tags валиден, но старые записи без tags тоже не ломают сервер.

После merge в main:

• CI гоняет unit/contract;
• на staging запускаются 1–2 E2E‑сценария через новый tool;
• включаете новый prompt и tool только для тестового tenant’а через фича‑флаг.

Смотрите на метрики: p95 инструмента, error‑rate, конверсию в checkout. Если всё ок — расширяете флаг на большее количество пользователей. И только потом, когда убедились в стабильности, обновляете манифест для Store (если нужно) и промо‑описание приложения.

Если где‑то по пути всё ломается — вы знаете, как откатиться: либо руками выключаете флаг, либо откатываете deployment, либо, в крайних случаях, катите назад версию манифеста (но это тот случай, который лучше вообще не допускать).

9. Типичные ошибки в release‑процессе ChatGPT App

Ошибка №1: одна абстрактная «версия App» вместо матрицы версий.
Когда у вас только «GiftGenius v1.4», но нигде не зафиксированы версии tools‑схемы, промптов и product feed, вы не сможете потом ответить на вопрос: «после какого именно изменения у нас упал checkout?» Разносите версии по слоям и логируйте их в структурированных логах.

Ошибка №2: breaking‑изменения в tools без нового имени/версии.
Самая болезненная штука: взяли и переименовали поле в input‑схеме или удалили его, не меняя имя инструмента. В старых чатах модель продолжает слать старый payload, backend возвращает 400, GPT начинает «галлюцинировать» в ответ, пользователи ничего не понимают. Любое ломающее изменение делайте через новый инструмент (foo_v2) или через новую версию API, а старый интерфейс оставляйте на переходный период.

Ошибка №3: обновление SDK «по дороге» к фиче.
Классика: вы добавляете новую бизнес‑фичу и по пути обновляете @modelcontextprotocol/sdk с 0.3 до 0.5 «ну, чтобы всё было свеженькое». В итоге, если что‑то ломается, непонятно, виноват ли новый код, новая схема или новый SDK. Миграции SDK лучше делать отдельными тех‑релизами, с чётким планом тестов и возможностью откатиться.

Ошибка №4: отсутствие фича‑флагов и instant kill‑switch’ей.
Выкатить новый алгоритм рекомендаций сразу на 100% пользователей — это весело, пока он не начнёт давать странные результаты или не положит внешний сервис. Без фича‑флага ваш единственный рычаг — полный rollback релиза, который может задеть не только новую фичу, но и десяток безобидных улучшений. Делайте хотя бы простые флаги через env или небольшой конфиг.

Ошибка №5: надежда на «моментальный» апдейт манифеста.
Распространённое заблуждение — думать, что как только вы поменяли tools или openapi.yaml, модель тут же узнает о новой схеме. На практике манифест и описания tools кэшируются, а в уже открытых чатах могут жить долго. Игнорирование этого факта ведёт к неочевидным багам: в новых чатах всё работает, в старых — падает. Планируйте изменения схем с учётом этого поведения и тестируйте их через Dev Mode и staging перед выкатыванием в Store.

Ошибка №6: отсутствие понятного плана rollback и документации по релизам.
Если в вашей команде никто не может ответить на вопросы «как откатить релиз за 5 минут?», «какую версию мы откатим?», «как вернуться к старой схеме feed’а?» — считайте, что rollback у вас отсутствует. У on‑call должен быть короткий, но конкретный сценарий: какие кнопки нажимать, какие переменные менять и где смотреть, что откат сработал.

Ошибка №7: «немые» релизы без release notes и связки с метриками.
Выкатывать релизы без хоть какого‑то changelog’а — значит через пару месяцев жить в режиме гаданий. Когда p95 внезапно вырос, а конверсия упала, вы будете гадать: «а что вообще менялось тогда?» Привычка писать хотя бы минимальные release‑заметки и связывать их с датами деплоя и версиями облегчает не только аудит качества, но и жизнь всей команды.

1

Задача

ChatGPT Apps, 17 уровень, 3 лекция

Недоступна

Release Guard — скрипт для release-notes и pinned-зависимостей

Release Guard — скрипт для release-notes и pinned-зависимостей

Открыть