CartistoDocs
⌕

Versioning & releases

How theme versions pin installs so an update never breaks a live store.

A theme carries two versions in theme.json, and they mean different things:

  • sdk — the contract your theme targets (the data-cartisto grammar, events, seeds). See Platform versioning.
  • version — your theme’s own release version (semver MAJOR.MINOR.PATCH). This is what a merchant install pins to.

Pins resolve by minor line

Each install records the version it’s on. What renders depends on how the current version differs from the pin:

  • PATCH = evergreen. A same-minor change (1.0.0 → 1.0.1) renders live for every install on that minor line. Use a patch for anything backward-compatible: copy, CSS, a non-structural fix. A bugfix reaches the whole fleet at once — something install-frozen models can’t do.
  • MINOR / MAJOR = frozen. Before a change that could disrupt a customized store (markup/structure, a removed section), you cut a release snapshot of the line you’re leaving, then bump. Installs on the older line keep rendering the snapshot until the merchant clicks Apply update.

Views and the compiled code assets (assets/css, assets/js) are pinned together — a minor/major bump changes markup, and theme.css is compiled against that markup, so a pinned install serves the snapshot’s stylesheet and its pinned views as one set. Images and locales stay evergreen — they aren’t markup-coupled, so a new placeholder or a translation fix is fleet-safe, exactly like a patch.

Cutting a release

Note

This is a platform (marketplace) theme workflow Release snapshots and the theme:release tool apply to platform themes built on disk in the platform repository. A custom theme (a merchant’s CLI fork) doesn’t cut releases — it tracks the starter version it was forked from and surfaces a “starter update available” signal instead. See Custom themes.

# freeze the current minor line, then bump theme.json in one step
npm run theme:release -- my-theme --next 1.1.0

This snapshots the current views and code assets into themes/my-theme/releases/1.0/ and sets theme.json to 1.1.0. Then make your breaking edits against the now-1.1 views. Releases are immutable — re-cutting an existing line needs --force.

What the gate checks

The Release pinning gate (Tier 1) verifies your snapshots are trustworthy:

  • every releases/<dir> is a MAJOR.MINOR folder and a well-formed theme (has a layout and its compiled assets/css/theme.css);
  • its snapshot version sits on that minor line;
  • it archives a past minor line — you can’t archive the current line (bump first) or a future one.

Choosing a bump

Change Bump Cut a release?
Fix a typo, tweak spacing, adjust a color PATCH No
Add an optional section or setting MINOR Yes (frozen so existing stores opt in)
Restructure a template, remove a section MAJOR Yes
Tip

When in doubt, freeze If a merchant has customized around your markup, treat the change as breaking: bump the minor and cut a release. The cost is one snapshot; the benefit is that no merchant wakes up to a rearranged storefront they didn’t ask for.