# Version Support Policy

Zuplo runs production traffic for its customers, so backward compatibility is a
design constraint rather than an aspiration. This document describes how Zuplo
versions each part of the platform, what counts as a breaking change, and what
support window applies.

## At a glance

| Surface                                            | What controls compatibility                   | Support window                                           |
| -------------------------------------------------- | --------------------------------------------- | -------------------------------------------------------- |
| Gateway runtime                                    | The `compatibilityDate` in your `zuplo.jsonc` | Indefinite. Existing compatibility dates keep working.   |
| Specification-based features (MCP, OAuth, OpenAPI) | The upstream specification's own lifecycle    | Tracks the specification. Old revisions eventually drop. |
| Developer Portal                                   | The `zudoku` package version in your project  | Current version only. Fixes aren't backported.           |

## Gateway runtime

### Runtime versions don't change behavior

The version of the Zuplo runtime a project builds against doesn't determine how
that project behaves. Zuplo ships runtime updates continuously, and every
release runs against an extensive automated test suite covering the request
lifecycle, policies, handlers, and the programmable API. A newer runtime brings
fixes, performance improvements, and new APIs. It doesn't change how existing
routes, policies, and handlers behave.

Behavior changes are gated by compatibility dates instead.

### Compatibility dates

A compatibility date locks in the behavior of the runtime as of a specific day.
When a change would alter existing behavior, Zuplo puts that change behind a new
compatibility date. Projects keep the previous behavior until they opt in by
raising the date in `zuplo.jsonc`:

```jsonc
{
  "version": 1,
  "compatibilityDate": "2026-03-01",
}
```

New projects default to a recent compatibility date. Existing projects stay on
the date they set until someone changes it, and Zuplo doesn't retire old
compatibility dates on a schedule.

Every compatibility date and the behavior it changes is documented in
[Compatibility Dates](../programmable-api/compatibility-dates.mdx). Each entry
describes the old behavior, the new behavior, and the migration required.

:::tip

Raising a compatibility date is a code change like any other. Deploy it to a
[preview environment](./branch-based-deployments.mdx), run your tests against
that deployment, and merge once it passes.

:::

### Security exceptions

Security is the exception to the compatibility promise. To close a vulnerability
or protect customer traffic, Zuplo may change runtime behavior without gating
the change behind a compatibility date, including in ways that break existing
projects.

Zuplo scopes these changes as narrowly as the vulnerability allows and
communicates them as directly as responsible disclosure permits. For Zuplo's
security practices and how to report a vulnerability, see
[Security](./security.mdx).

## Changes take effect when you deploy

Zuplo doesn't rebuild or redeploy a running gateway on your behalf. A new
runtime, a raised compatibility date, or an updated dependency reaches an
environment only when you deploy to it — by pushing to the branch that
environment tracks, or by running [`zuplo deploy`](../cli/deploy.mdx).

Two things follow from this:

- **Timing is yours.** Nothing changes underneath a production environment
  between deployments.
- **Every upgrade is testable first.** Preview environments deploy from a
  branch, so a runtime or compatibility date change runs on real infrastructure
  before it reaches production.

Because deployments are the moment behavior can change, Zuplo strongly
recommends a comprehensive test suite that gates every deployment. The
[`zuplo test`](../cli/test.mdx) command runs the same tests locally, against
preview environments, and in CI/CD. See [Testing Your API](./testing.mdx) for
the recommended setup.

## Specification-based features

Some parts of the gateway implement specifications Zuplo doesn't control — most
visibly the Model Context Protocol (MCP), along with OAuth, OpenAPI, and related
standards. These features follow the lifecycle of the specification rather than
Zuplo's own compatibility policy.

Two consequences:

- When a specification deprecates or removes a revision, Zuplo eventually ends
  support for that revision in line with the specification's deprecation policy.
- When a specification changes such that remaining backward compatible would
  mean falling out of compliance, Zuplo implements the breaking change. A
  non-compliant implementation breaks interoperability with the clients and
  servers customers need to work with, which is the larger break.

MCP moves fastest here. The [MCP Gateway](../mcp-gateway/introduction.mdx) and
[MCP Server](../mcp-server/introduction.mdx) track protocol revisions as the
specification publishes them, and support for older revisions ends on the
specification's schedule.

Where a spec-driven change can be gated, Zuplo gates it. The MCP Gateway, for
example, requires a compatibility date of `2026-03-01` or later — see
[MCP Gateway compatibility dates](../mcp-gateway/code-config/compatibility-dates.mdx).

## Developer Portal

The Developer Portal is a web application built on [Zudoku](https://zudoku.dev),
and it evolves rapidly. Zuplo minimizes breaking changes where practical, but
the UI, components, and configuration surface change over time. There's no
long-term support release for the Developer Portal.

The supported version is the current version:

- **Fixes ship in new versions.** Bug fixes and security fixes are released in a
  new version of the `zudoku` package.
- **Nothing is backported.** Fixes aren't applied to older versions, including
  security fixes.
- **Upgrading is how you pick up a fix.** A project pinned to an old version
  stays on the behavior — and the bugs — of that version.

:::caution

Security fixes for the Developer Portal aren't backported. A project pinned to
an older `zudoku` version doesn't receive them.

:::

Stay on a recent version and upgrade in small, frequent increments rather than
large jumps. Run `npm install zudoku@latest` in your project's `/docs` directory
and test locally before deploying. See
[Updating Versions](../dev-portal/updating.mdx) for the full process, and the
[Zudoku release notes](https://github.com/zuplo/zudoku/releases) for updates
that need more than a dependency bump.

## Breaking changes and notice

When Zuplo introduces a breaking change:

- **Notice comes first.** Zuplo publishes breaking changes in advance through
  the [changelog](https://zuplo.com/changelog) and documentation, and contacts
  affected customers directly where the impact is identifiable.
- **Compatibility dates carry the change where possible.** Gating a runtime
  change behind a compatibility date leaves the timing of adoption to you.
- **The upgrade path is documented.** Compatibility date entries and migration
  guides describe what changes and what to do about it.
- **Enterprise customers get dedicated assistance.** Customers on an enterprise
  plan work directly with the Zuplo team on upgrade planning, testing, and
  rollout. See [Support](./support.mdx).

Security changes are the exception and may ship with short notice, or none, when
advance disclosure would put customers at risk.

## Related resources

- [Compatibility Dates](../programmable-api/compatibility-dates.mdx) — every
  runtime behavior change and the date that gates it
- [Project Configuration (`zuplo.jsonc`)](../programmable-api/zuplo-json.mdx) —
  where the compatibility date is set
- [Testing Your API](./testing.mdx) — local, preview, and CI/CD testing
- [Branch-Based Deployments](./branch-based-deployments.mdx) — how branches map
  to environments
- [Updating Versions](../dev-portal/updating.mdx) — upgrading the Developer
  Portal
- [Security](./security.mdx) — security practices and vulnerability reporting
- [Support](./support.mdx) — support plans, contact methods, and response times