fix(docs): correct post-CLI-release action guidance in CLAUDE.md#3387
Closed
fix(docs): correct post-CLI-release action guidance in CLAUDE.md#3387
Conversation
Contributor
|
Oxygen deployed a preview of your
Learn more about Hydrogen's GitHub integration. |
qwe0806asd-rgb
approved these changes
Jan 18, 2026
Contributor
|
duplicate of #3525 |
The old guidance incorrectly stated that bumping the CLI version after a cli-hydrogen release is 'unnecessary' and that Dependabot handles @shopify/cli version updates (it does not — .github/dependabot.yaml only covers github-actions). Replace with a precise two-scenario decision model: if cli-hydrogen had actual code changes, manually update skeleton's @shopify/cli and trigger another release cycle; if changes were only a changeset to re-bundle the skeleton, no further action is needed. Apply the same logic consistently to the shopify-cli-update.md runbook.
kdaviduik
changed the title
5 tasks
The old guidance used the vague heuristic 'will someone scaffolding tomorrow need this?' which implied bumping create-hydrogen for any non-init CLI change. This was wrong for two reasons: 1. create-hydrogen only bundles (a) the init code path and (b) the full dist/assets directory -- not other commands like dev/build/check. Bumping it for non-init command fixes is a no-op. 2. The old text omitted the assets dimension entirely: changes to files in packages/cli/assets/ (virtual routes, tailwind configs, etc.) DO require a create-hydrogen bump even if the init command code is untouched. Replace with a precise two-part decision: does the change affect the init command OR any CLI assets? If yes, bump both. If no, just bump cli-hydrogen.
Contributor
Author
|
Closing in favour of #3555 |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
WHY are these changes introduced?
The
CLAUDE.mdguidance for the skeleton/CLI release process contained several inaccuracies that would mislead maintainers:Incorrect skeleton changeset requirement — the old docs said to include only
@shopify/cli-hydrogenwhen changing the skeleton. The correct requirement is all three packages:skeleton,@shopify/cli-hydrogen, AND@shopify/create-hydrogen. Without all three,npm create @shopify/hydrogen@latestwon't get the updated template.Wrong description of how scaffolding works — the old docs described template fetching from GitHub at runtime via the GitHub API. The actual behavior is that the skeleton is pre-bundled inside
@shopify/create-hydrogenat build time. No network fetch happens for the default template.Vague post-CLI-release guidance — the old docs said the second cli-hydrogen release is "often required" and that Dependabot handles
@shopify/cliversion bumps (it does not —.github/dependabot.yamlonly coversgithub-actions). Whether action is needed depends on what the cli-hydrogen changes actually contained.WHAT is this pull request doing?
Skeleton changeset requirement (Developer Actions section): Corrects the required packages from
@shopify/cli-hydrogenonly → all three (skeleton+@shopify/cli-hydrogen+@shopify/create-hydrogen), with a cross-reference to the new Quick Reference section.How Project Scaffolding Works: Replaces the incorrect runtime-fetch description with the correct pre-bundling explanation, including a collapsible bundling chain diagram.
New "Quick Reference: Contributing to Skeleton or CLI" section: Step-by-step guidance for the two most common contribution scenarios — updating the skeleton template vs. updating cli-hydrogen only — including the correct changeset requirements for each, with a canonical example PR.
Understanding the Circular Dependency (replaces "CLI Release Coordination"): Replaces the old "always two releases required" narrative (with the Day 1–4 example timeline) with a precise two-scenario decision model:
@shopify/cliand trigger another release cycleMaintainer Actions - CLI Releases: Collapses two vague bullets into one that cross-references the new decision model section.
shopify-cli-updaterunbook (.claude/commands/shopify-cli-update.md): Applies the same decision criteria inline, replacing the vague "may require" statement.Checklist