docs: document project upgrade wizard - #2442
docs: document project upgrade wizard#2442somethings (lasomethingsomething) wants to merge 12 commits into
Conversation
Developer Docs healthcheckStatus: Completed with |
There was a problem hiding this comment.
Pull request overview
This PR adds canonical documentation for the shopware-cli project upgrade wizard (local-first Shopware project upgrades) and makes it discoverable from the existing upgrade and operational update guides.
Changes:
- Add a new CLI guide describing the upgrade wizard phases, prerequisites, rollback behavior, dry-run/preflight mode, and report output.
- Update upgrade and update guides to recommend the wizard workflow and link to the canonical CLI documentation.
- Extend the spellcheck wordlist to include “preflight”.
Reviewed changes
Copilot reviewed 5 out of 6 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| products/tools/cli/project-commands/upgrade.md | New canonical documentation for the Shopware CLI project upgrade wizard, including phases, non-interactive preflight, rollback, and reporting. |
| guides/upgrades-migrations/upgrade-shopware.md | Reframes the guide to recommend the CLI wizard for local upgrade preparation, while keeping the manual Composer workflow as fallback. |
| guides/upgrades-migrations/index.md | Adds an entry-point callout and integrates the CLI preflight into the typical upgrade workflow and next steps. |
| guides/hosting/installation-updates/performing-updates.md | Updates operational update guidance to use the wizard (dry-run and interactive) for compatibility checks and local preparation steps. |
| .wordlist.txt | Adds “preflight” to the spelling allowlist. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
|
|
||
| ## Before you start | ||
|
|
||
| Run the upgrade on a Git branch or a disposable copy of the project. The wizard checks these prerequisites before continuing: |
There was a problem hiding this comment.
we have an flag --disable-git. may makes sense to mention here 👀
There was a problem hiding this comment.
Soner (@shyim) Made that addition. If that works for you, then I guess you can release your block for the dev docs team to take over. :)
|
Heya Micha Hobert (@Isengo1989) and Bojan Rajh (@bojanrajh): I'm sorry, I thought I hit the green button on this yesterday but did not. This is another feature (along with local proxy, documented here #2444) that we're going live with as part of the next CLI release, and have a blog post on this specific upgrade wizard teed up with DevRel for Monday, Aug. 17 publication. If you are able to review this docs PR in time for Monday, that would be greatly appreciated. If you are not, I think we will be fine if these upgrade wizard docs land a few days later, because the point of the feature is to make reliance on devdocs as minimal as possible. Just let me know what works best for you. |
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
📢 Developer Announcement RecommendationRecommendation: ❌ No Announcement Recommended No developer announcement signals were detected.
|
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
What changed?
shopware-cli project upgradeImplementation source
Documents the local-first upgrade work from:
Placement
The canonical feature reference lives under
products/tools/cli/project-commands/upgrade.md.The PR also updates:
guides/upgrades-migrations/upgrade-shopware.mdguides/upgrades-migrations/index.mdguides/hosting/installation-updates/performing-updates.mdThis keeps the detailed command behavior in the CLI docs while making the wizard discoverable from the places developers already go when planning an upgrade.
Rollout
This is intentionally a draft.
project upgradeis merged on the Shopware CLInextbranch, while the current stable CLI release is still0.16.10. The docs should land with or after the release containing the upgrade wizard.Notes
The guide treats Composer resolution as the authoritative dependency gate and Store/repository metadata as an early compatibility signal, matching the current implementation. It also makes the local-first boundary explicit: the wizard upgrades the local project, then the developer tests, commits, and deploys through the normal process.