Release process guide for Shopify's Hydrogen framework. Covers the full release flow (standard, back-fix, snapshot), manual vs automatic steps, changelog.json updates, h2 upgrade enablement, and release failure recovery. Use when performing or debugging a Hydrogen release. Also activates when someone mentions "release", "release process", "back-fix", "snapit", "changelog.json", "h2 upgrade enablement", "release failure", "version PR", "release PR", or "hydrogen release".
Hydrogen uses an automated release system built on Changesets, GitHub Actions (release.yml), and npm workspaces. For changeset rules that apply to every PR, see CLAUDE.md. For versioning semantics (CalVer, API versions), see the hydrogen-versioning skill.
Developer creates PR with changes
packages/*/src/** or packages/*/package.json, a changeset is requiredpnpm run changeset add to create a changeset file (MANUAL)On merge to main, TWO parallel processes occur:
a) Next Release (immediate) (AUTOMATIC)
next-release job in release.yml0.0.0-next-{SHA}-{timestamp}next tagb) Version PR Creation (if changesets exist) (AUTOMATIC)
release job in release.yml runs[ci] release {latestVersion} (where latestVersion is the computed next version — see below)Production Release — Batched (manual step)
release.yml publishes to npm with latest tag (AUTOMATIC)dist branch (AUTOMATIC)Post-Release: Enabling Upgrades (manual step)
docs/changelog.json must be updated (MANUAL)h2 upgrade command to detect the new versiondocs/changelog.json with release information (MANUAL)How h2 upgrade works:
main branch in the Hydrogen repo).hydrogen/ directoryKey Point: Not every merged PR triggers a release!
Example Timeline:
@shopify/hydrogen and @shopify/cli-hydrogen
/snapit)/snapit on any PR2025-01) triggers the backfix-release job in release.ymlDeveloper Actions
pnpm run changeset add for any PR with code changesskeleton, @shopify/cli-hydrogen, AND @shopify/create-hydrogen — see changeset rules in CLAUDE.md/snapit on PR to test changesMaintainer Actions — Regular Releases
h2 upgrade commandMaintainer Actions — CLI Releases
@shopify/cli and trigger a second cli-hydrogen release depends on the nature of the cli-hydrogen changes — see the circular dependency section in CLAUDE.mdMaintainer Actions — Major Version Changes
latestBranch detection: latestBranch is computed dynamically by calver-shared.js + get-calver-version-branch.js in release.yml. No manual editing of latestBranch is needed for standard releases.on.push.branches array in .github/workflows/release.yml. Never add the current CalVer branch.On Every Push to Main
next0.0.0-next-{SHA}-{timestamp}When Changesets Exist on Main
[ci] release {latestVersion}When Version PR is Merged
latest tagdist branchWhen /snapit is Commented
snapit.yml workflow runsOn Push to Calver Branches
backfix-release job in release.yml runs2025.7.2 — a patch bump) but the description incorrectly says a different version (e.g., 2025.10.0). Do not trust one without checking the other.It is expected that for ~1 hr after doing a new release, scaffolding new Hydrogen projects may continue to be scaffolded using the stale version due to npm caching.
Sometimes you need to release a patch/minor for a version that is not the latest major, or main already has unreleased code for a future version. In these cases, use a back-fix branch.
If this is your first back-fix, pair with an experienced team member. The process involves branch naming conventions and force-push scenarios that can silently break things if done wrong.
[!CAUTION] Branch naming: The back-fix branch must be named to match the major version, e.g.,
2024-10. Do NOT use arbitrary branch names¹. The dev docs automation for updating API documentation depends on this exact naming pattern. If the branch name is wrong, docs will not update and there will be no error — it fails silently.
¹This dev docs automation (at time of writing - Mar. 17, 2026) currently only applies to @shopify/hydrogen and @shopify/hydrogen-react. It is extremely rare that you would want to back-fix a different package in this monorepo, though you could, and in that case the specific branch name can be whatever you want, you just need to make sure that you have the SAME branch name as what you put in .github/workflows/release.yml. Also note that in this situation (after back-fixing a non @shopify/hydrogen or @shopify/hydrogen-react dependency in this repo), you probably don't need to release a new Hydrogen version, and instead you can just add a new entry to docs/changelog.json with the new back-fixed version of the dependency. Example: we released a new version of the Shopify CLI that we wanted people to upgrade to, so we just added a second entry in docs/changelog.json for Hydrogen version 2025.4.1, as it would be unnecessary to do another release of Hydrogen with just the CLI bump.
Step-by-step workflow:
Create the back-fix branch:
git checkout -b 2024-10 @shopify/[email protected]
on.push.branches array in .github/workflows/release.yml. This change is only made on back-fix branches, never on main.git push origin 2024-10
[!WARNING] Why should I always create a NEW back-fix branch and (force) push, even if one already exists on remote?
- While we can update
.github/workflows/release.ymlto automatically create a back-fix branch for each release upon release, we've decided not to. Sometimes changes can accidentally get pushed to or merged into the back-fix branch but not released, so if you were to then add onto it you also have some arbitrary changes present that shouldn't be there. Also, even if a back-fix branch is automatically created after each Hydrogen release, others can still force push to it or make changes to it such that you cannot and should not trust the existing back-fix branch (if it exists) as the source of truth. The existing back-fix branch could theoretically be named "2025-10" but actually contain code from Hydrogen version "2025-01" if someone pushed faulty code to it in the past.
Do the code changes that you want present in the back-fixed version:
git checkout -b 2024-10-my-changes 2024-10
2024-10-my-changes branch, with the base branch being 2024-10 (obviously adjust specific branch names to your specific case)If this is your first release failure, pair with an experienced team member before attempting recovery. DO NOT JUST YOLO THIS WITH LLMs!!!!!
#help-eng-infrastructure (Slack ID: C01MXHNTT4Z)git branch backup-2024-10 (so you can restore if needed)WARNING: The force-push recovery path requires advanced git confidence. If you are not extremely comfortable with git rebase and git push --force, do not attempt this alone. Verify you are not deleting other commits before force pushing.
CLAUDE.md — Changeset rules (apply to every PR), skeleton/CLI bundling chain, circular dependencyhydrogen-versioning — CalVer formats, version support policies, release cadencehydrogen-dev-workflow — Day-to-day development workflow, testing, recipes, PR conventions