Skip to content

armgit / spree

Public Imported from GitHub
0

Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.

19.1 KB
Raw Blame

Spree 6.0 Beta Release

Status: Released — 6.0.0 (stable) prepared 2026-10-27 Target: Spree 6.0 Depends on: 5.6-project-layout-and-dashboard.md (dashboard packaging, embedded starter) Author: Damian Last updated: 2026-10-27 Tracking: Linear — · GitHub —

Summary

Ship the first public beta of Spree 6.0: prerelease Ruby gems on RubyGems, the TypeScript packages on npm, and create-spree-app / spree add scaffolding a 6.0 project by default. The npm side is the delicate half — @spree/[email protected] currently sits on latest and is the 5.x Store API, and every storefront (both branches) depends on ^1.2.1. A 6.0 SDK published as 1.x would silently upgrade every 5.x storefront onto an API that no longer exists. The release is therefore built around one rule: the beta is reachable by opt-in tag or explicit range, and latest keeps meaning 5.x until 6.0 is final.

Key Decisions (do not deviate without discussion)

  1. Gems ship as 6.0.0.beta1. RubyGems treats it as a prerelease, so gem install spree and an unpinned gem 'spree' keep resolving to 5.x — only --pre or an explicit 6.0.0.beta1 pin reaches it. The version string lives in one place (spree/core/lib/spree/core/version.rb), and rake gem:release reads it for all nine gems. Use beta1, not beta.1: both are valid prereleases and both sort correctly, and beta1 matches the existing 5.6.0.rc1 convention.

  2. @spree/sdk goes to 2.0.0-beta.1, published under the beta tag. (Superseded from the release candidate after rc6 by Decision 3: the SDK moves to the Spree version. The reasoning about tags still holds.) This is the load-bearing decision. The major bump states the Store API break, and the prerelease + non-latest tag means ^1.2.1 in both storefront branches cannot resolve to it — semver ranges exclude prereleases unless the range itself is a prerelease. latest stays on 1.2.1 for 5.x users. The release-sdk job must gain the tag logic the admin-sdk job already has — today it runs a bare npm publish, which would push the beta straight to latest and break every 5.x storefront. This is the single highest-risk item in the release.

  3. The packages that talk to the Spree API carry the Spree version. (Revised 2026-10-26; the beta and the first six release candidates shipped them as 1.0.0-rc.x, and @spree/sdk as 2.0.0-rc.x.) @spree/sdk, @spree/admin-sdk, @spree/seller-sdk, @spree/core, the dashboard trio and @spree/seller-dashboard are one Changesets fixed group, versioned from Spree::VERSION: gems 6.0.0.rc7 ship as 6.0.0-rc.7, and 6.0.0 is 6.0.0 everywhere. Their types come from the serializers and their request shapes from the OpenAPI files, so a version number that maps to nothing on the backend only made people consult a compatibility table nobody maintained, and the numbering had already drifted (the seller panel at rc.7, everything else at rc.6). @spree/cli and create-spree-app keep their own versions: they manage Docker and scaffolding, not the API, and need patch releases of their own.

    • Released by pnpm version:packages (scripts/version-packages.mjs), which runs changeset version and then moves the group to the Spree version. Changesets still writes the changelogs, but for the group a changeset's bump type only decides the changelog heading. A Spree release with no TypeScript changes still publishes the group with an entry saying so, as the nine gems already do.
    • The cost accepted: a breaking change in the TypeScript code alone waits for the next Spree major, the same promise the Store API makes.
    • Switched at the release candidate after rc6, not at GA. Every existing range misses the jump wherever it happens, so the question is only whether the migration path first runs on release day. GA stays a plain promotion of the last candidate.
    • Existing projects are moved by spree upgrade, which rewrites any range for a package in the group that is still on an older line (^1.0.0-rc.7, >=0.13.1 <2.0.0) to the Spree version before updating. The CLI only knows the group from its build, so a project updates @spree/cli first, then upgrades. Until the group shares one version, the CLI rewrites nothing. The storefront stays the merchant's: the CLI names the exact @spree/sdk range to move to.
    • Never publish a stable 1.0.0 or 2.0.0 of a package in the group: either would satisfy the old ranges and look like a supported line. Deprecate the old lines on npm after the first aligned release (npm deprecate "@spree/[email protected]" "Moved to 6.x with Spree. Run: spree upgrade", likewise @spree/[email protected]).
    • Peer ranges inside the group are literal, from the release to the end of its major (>=6.0.1-rc.1 <7.0.0-0), set by the script on every release. The floor is the full version: a patch release candidate does not satisfy >=6.0.0-0.
    • Released from tags, in one workflow (2026-10-26). release.yml publishes the gems and the group on the Spree tag (v6.0.0.rc7), and each tool on its own tag (@spree/[email protected], [email protected]), after checking the tag against the versions in the repository. packages.yml only runs checks. The templates the CLI embeds (the dashboard and seller starters, the plugin peers) accept the whole major (^6.0.0-0), so a CLI tag pushed before the Spree tag never points at packages not yet on npm.

    Use rc.7, never rc7, on npm: semver compares dot-separated prerelease identifiers numerically but bare strings alphabetically, so 1.0.0-beta9 sorts ABOVE 1.0.0-beta10 and a release would ship backwards. The gems keep 6.0.0.rc7; the script converts.

    Accepted break: the dashboard trio currently publishes to next at 0.13.1. At 1.0.0-beta.1 the release jobs route it to beta instead (any version containing -), so anyone installing @spree/dashboard@next stops receiving updates and must move to @beta. Call this out in the release notes — the Developer Preview audience is small and reachable.

  4. 6-0-dev merges into main on both scaffolding repos before the release. create-spree-app clones spree/spree-starter and spree/storefront with no --branch, so it follows whatever main holds — which is why merging is what makes 6.0 the default for new projects. No --branch flag is added here, and nothing needs revising again at GA. The merge lands after the gems and SDK are published, because the branches being merged must pin released versions — and the moment main moves, every new project gets it. So the order is: publish → pin → merge. See Migration Path.

  5. The starter must pin released gems, not a git branch — and this is a merge blocker. starter/6-0-dev pins github: 'spree/spree', branch: 'main'. That is right for development and wrong the instant it becomes main: every new project would build against whatever landed that morning, with no reproducible version in a bug report, and bundle install would clone this whole monorepo. Flip it to '6.0.0.beta1' and regenerate the committed Gemfile.lock (currently resolved against 6.0.0.alpha from the git source) as part of the merge, not after it.

  6. Every gem in the monorepo publishes from the 6.0 line — providers and opentelemetry included. All nine gemspecs already read Spree.version, so they version in lockstep; the only gap was spree_stripe, absent from SPREE_PROVIDER_GEMS in spree/Rakefile (fixed — see Migration Path step 0). That gap was a hard release blocker: the starter's Gemfile requires spree_stripe, so bundle install would have fallen back to the standalone 1.8.1 line, which targets 5.x. spree_opentelemetry already ships via SPREE_OPTIONAL_GEMS and needs no change. The published set is now: spree, spree_core, spree_api, spree_emails, spree_dashboard, spree_opentelemetry, spree_easypost, spree_meilisearch, spree_stripe.

    Jumping spree_stripe from its standalone 1.8.1 to 6.0.0.beta1 is safe: the beta is a prerelease, so gem 'spree_stripe' and ~> 1.8 on 5.x keep resolving to the 1.x line. A provider gem's version continuity is deliberately subordinate to the monorepo's — that is what Spree.version in every gemspec already encodes.

  7. Clear the changeset backlog in one release train. 30 unreleased changesets have accumulated since ~July. Run pnpm changeset version (not version:preview) so @spree/sdk is included — this is the release where it must be.

Design Details

Current state

Package Local npm latest npm next Consumers to protect
gems 6.0.0.alpha 5.6.x — unpinned gem 'spree'
@spree/sdk 1.2.1 1.2.1 — storefront ^1.2.1, both branches
@spree/admin-sdk 0.8.1 0.1.0 0.8.1 none
@spree/dashboard{,-core,-ui} 0.13.1 0.2.1 0.13.1 none
@spree/cli 2.4.9 2.4.9 — 5.x users running spree
create-spree-app 1.2.1 1.2.1 — new projects

Why the SDK needs a major, not a 0.x or a 1.3.0

The storefront depends on @spree/sdk: "^1.2.1". Under that range:

  • 1.3.0 → resolves. Every 5.x storefront silently moves to the 6.0 SDK on its next pnpm install. Unacceptable.
  • 2.0.0 → does not resolve, but occupies latest and becomes the default for anyone running npm install @spree/sdk. Premature for a beta.
  • 2.0.0-beta.1 under the beta tag → does not resolve into ^1.2.1, does not touch latest, and is reachable as @spree/sdk@beta or by exact pin. This is the choice.

Verified: semver.satisfies("2.0.0-beta.1", "^1.2.1") === false, and likewise for the embedded-template range below.

The CLI / create-spree-app pairing

@spree/cli and create-spree-app are the user-facing front door and are not prerelease-tagged, because a user running the documented npx create-spree-app must land on 6.0 once we flip the default. Two options, and the choice determines how loud the beta is:

  • (a) Ship them as normal latest releases once the starter branches flip. New projects get 6.0 beta; existing 5.x projects are unaffected (the CLI operates on an already-generated project). This is the "6.0 is the default for new projects" outcome you asked for.
  • (b) Ship them as beta-tagged prereleases (3.0.0-beta.1), so 6.0 is opt-in via npx create-spree-app@beta. Safer, but then 6.0 is not the default and the goal isn't met.

Recommend (a), gated on the starter branches being flipped and a scaffold smoke test passing — the release chain (admin-sdk → dashboard → cli → create-spree-app) already encodes the ordering, and the embedded-template range >=0.13.1 <2.0.0 floats scaffolds onto future dashboard releases without a CLI republish.

What already works and needs no change

  • rake gem:release builds and pushes all nine gems from the single VERSION constant; the Release workflow fires on any v* tag with Trusted Publishing. Tagging v6.0.0.beta1 is the whole gem release.
  • The npm release chain is correctly ordered and gated (admin-sdk → dashboard → cli → create-spree-app), each job idempotent via a published-version check, so a re-run is safe.
  • sync-dashboard-starter.mjs floors the embedded template at the released dashboard version with >=x.y.z <2.0.0, which correctly excludes prereleases — scaffolds will not accidentally pick up a 1.0.0-beta.

Migration Path

Ordered; each step is independently verifiable. Steps 0-1 are repo hygiene that must land before any version bump, because both change what a publish does.

  1. Publish every gem. Add spree_stripe to SPREE_PROVIDER_GEMS in spree/Rakefile (done). Verify the full set builds — all nine gemspecs read Spree.version, and spree_stripe, spree_easypost, spree_meilisearch and spree_opentelemetry were each confirmed to build cleanly.

  2. Fix the SDK release job. Add the Determine npm tag step to release-sdk in .github/workflows/packages.yml, copied from release-admin-sdk, extended so a version containing - publishes under beta. Do this before any version bump lands on main — otherwise the first push after the bump publishes the 6.0 SDK to latest and every 5.x storefront breaks on its next install. Single highest-risk item.

  3. Prepare spree-starter for the merge. On 6-0-dev, replace the github: 'spree/spree', branch: 'main' block with '6.0.0.beta1' for all six required gems, and regenerate Gemfile.lock (committed, currently resolved against 6.0.0.alpha from the git source). Leave the SPREE_PATH development branch untouched — worktrees depend on it. This cannot be done before step 3 publishes the gems, so the sequence is: publish gems → pin → merge.

  4. Bump and release the gems. Set VERSION = '6.0.0.beta1' in spree/core/lib/spree/core/version.rb, tag v6.0.0.beta1, and let the Release workflow push all nine gems. Confirm each appears on RubyGems before proceeding — the starter's pin depends on every one of them.

  5. Refresh the Developer-Preview notes in the package READMEs. @spree/dashboard and @spree/dashboard-ui both say APIs "may change between 0.x releases", which stops being true at 1.0.0-beta.1; the seller packages' notes already name the beta tag. Reword them to the beta line (published under beta, promoted to latest at GA) in the same change as the version bump, so npm never shows install instructions that contradict the published tag.

  6. Version and publish the npm packages. Clear the changeset backlog with pnpm changeset version (plain — not version:preview, which carries --ignore @spree/sdk), then set the versions by hand: 1.0.0-beta.1 for @spree/admin-sdk, the dashboard trio, @spree/seller-sdk and @spree/seller-dashboard; 2.0.0-beta.1 for @spree/sdk. Changesets has no first-class prerelease-major path that plays well with these exceptions, so the edit is deliberate and reviewed. Merge to main and let the release chain publish — admin-sdk and seller run in parallel, both gating release-cli, which gates create-spree-app.

  7. Merge 6-0-dev into main on spree/spree-starter and spree/storefront. With steps 2-4 done, main on both repos resolves released gems and a published SDK the moment it becomes the default, so create-spree-app — which clones without --branch — scaffolds 6.0 with no change to this repo. Point the storefront's @spree/sdk dependency at the published 2.0.0-beta.1 in the same merge.

  8. Seller panel distribution (done): sync-dashboard-starter.mjs is generalized to sync-starter.mjs <target> [starter-package] and the CLI build renders both templates; spree add gained a seller-dashboard component (addDashboard → app-parameterized addApp, with the unit battery now running against both apps); create-spree-app scaffolds apps/dashboard and apps/seller-dashboard; the starter's Dockerfile gained a mirrored seller-dashboard build stage (custom apps/seller-dashboard/ when present, stock template otherwise) that builds with VITE_BASE_PATH=/sellers/ and sets SPREE_SELLER_PANEL_DIST_PATH; and packages.yml gained a release-seller job publishing @spree/seller-sdk then @spree/seller-dashboard, with release-cli gated on it. The Dockerfile change lives in the starter repo and rides the same merge as step 2.

  9. Smoke test the real path — npx create-spree-app@<candidate> into a temp dir, boot it, confirm the dashboard loads and the storefront talks to the API. The scaffold is the only test that exercises gem pins, npm ranges and branch defaults together, and it is the first thing a beta user runs.

  10. Announce as beta, naming the install commands explicitly: gems need --pre or an exact pin, @spree/sdk needs @beta.

Stable release (6.0.0)

Decided 2026-10-27, when the release was prepared from rc7:

  • Promotion of the last candidate. Spree::VERSION moves to 6.0.0 and pnpm version:packages moves the group to 6.0.0, which distTag publishes under latest. The peer ranges inside the group become >=6.0.0 <7.0.0-0.
  • doorkeeper stays pinned at ~> 6.0.0.rc2. No final 6.0.0 is on RubyGems yet, and the pin already accepts it when it lands, so no Spree release is needed then. gem build warns about the pre-release dependency; Bundler installs it without one.
  • backend/ layout support stays in the CLI for now. Removing it is a breaking CLI change and goes out later, after a warning release.
  • The Admin and Seller APIs now deprecate instead of removing — the same procedure as the Store API (see CLAUDE.md).
  • After the tag: spree-starter moves from '>= 6.0.0.beta1' to '~> 6.0' (the open range would accept Spree 7), the storefront moves to @spree/sdk ^6.0.0, and the old npm lines are deprecated as Decision 3 describes.

Constraints on Current Work

  • Never publish @spree/sdk to latest until 6.0 is final. Any 6.0-line SDK release is 2.x prerelease under the beta tag. The 5.x storefront depends on ^1.2.1 and latest is what an unpinned install resolves to.
  • Don't use pnpm version:preview for this release — it carries --ignore @spree/sdk, which is exactly the package that must move.
  • Gem version changes go in spree/core/lib/spree/core/version.rb only; every gem and the release task read it.
  • Don't hand-edit packages/*/package.json versions — Changesets owns them. The single exception is the SDK prerelease string in step 3, which should be a deliberate, reviewed edit.
  • A dashboard release without a CLI release still reaches users (the embedded template floats >=x.y.z <2.0.0); don't add a CLI republish "to pick it up".
  • A new gem in the monorepo must be added to spree/Rakefile in the same change that adds its gemspec. A gemspec reading Spree.version looks released but is invisible to rake gem:release — exactly how spree_stripe came to be missing. Provider gems go in SPREE_PROVIDER_GEMS with an explicit path; everything else in SPREE_CORE_GEMS/SPREE_OPTIONAL_GEMS.
  • Don't "restore version continuity" for a provider gem by giving it a version of its own. All nine gemspecs read Spree.version deliberately; a provider jumping from a standalone 1.x to the monorepo line is expected.

Open Questions

  • CLI and create-spree-app: latest (option a, 6.0 becomes the default) or beta-tagged (option b, opt-in)? Recommend (a); it's the stated goal.

References

  • .github/workflows/release.yml — every release, from its tag
  • scripts/publish-packages.mjs — npm publishing, in dependency order
  • scripts/sync-starter.mjs — embedded template version flooring
  • docs/plans/5.6-project-layout-and-dashboard.md — dashboard packaging