Versioning policy

Cartisto exposes several long-lived contracts. Each is versioned independently, because they evolve at different speeds — coupling them would force needless migrations.

The surfaces

Surface	Version lives in	Consumed by
Theme SDK (window.cartisto)	the SDK bundle + cartisto.d.ts	theme JS
Theme Contract (data-cartisto, seeds, events, layout tags)	theme.json → "sdk"	theme markup
REST API	the /api/v1 path prefix	integrations
Theme CLI	the CLI package version	the CLI
A theme’s own release	theme.json → "version"	merchant installs

The compatibility promise

• Within a major, changes are additive. New settings, new events, new endpoints — never a breaking change to an existing one.
• A breaking change ships a new major, and the old one keeps working. A theme opts into a new SDK/contract major by bumping its declared "sdk"; the API ships /api/v2 while /api/v1 continues.
• Deprecate, never silently remove. A deprecated surface keeps working until the next major; the Quality Gate warns on deprecated usage, and Deprecations lists timelines.

Theme releases pin merchant installs

A theme’s own "version" is separate from the contract it targets. Installs pin to it, and pins resolve by minor line:

• Patch = evergreen — a same-minor change reaches every install at once (fleet-wide bugfixes).
• Minor/major = frozen — a release snapshot is cut, and installs on the older line keep rendering it until the merchant applies the update.

This is the honest-pinning model: a “pinned” install actually renders frozen content for breaking changes, while still receiving safe fixes. Full detail in Theme versioning.

Contract stability status

The theme contract is pre-launch: identifiers can still change, and old surfaces are deleted rather than shimmed. At launch it freezes as v1 — the data-cartisto grammar, event names, seed globals, cartisto.state/.ui, and the bundle URL scheme all become stable, and everything above kicks in.