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:
Code
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. Each entry describes the old behavior, the new behavior, and the migration required.
Raising a compatibility date is a code change like any other. Deploy it to a preview environment, 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.
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.
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 command runs the same tests locally, against
preview environments, and in CI/CD. See Testing Your API 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 and MCP Server 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.
Developer Portal
The Developer Portal is a web application built on Zudoku, 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
zudokupackage. - 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.
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 for the full process, and the
Zudoku release notes 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 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.
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 — every runtime behavior change and the date that gates it
- Project Configuration (
zuplo.jsonc) — where the compatibility date is set - Testing Your API — local, preview, and CI/CD testing
- Branch-Based Deployments — how branches map to environments
- Updating Versions — upgrading the Developer Portal
- Security — security practices and vulnerability reporting
- Support — support plans, contact methods, and response times