docs: document project upgrade wizard

[somethings (lasomethingsomething)]

What changed?

• adds a canonical Shopware CLI guide for shopware-cli project upgrade
• documents readiness checks, the Composer-managed extension prerequisite, target selection, Composer resolution, rollback behavior, reports, and headless/dry-run usage
• links the wizard from Upgrades & Migrations and the operational update guides
• keeps the manual Composer workflow as a fallback/reference path
• adds a screenshot of the last-step upgrade report

Implementation source

Documents the local-first upgrade work from:

• Implement local Shopware upgrade wizard flow shopware-cli#1167
• feat: local-first project upgrade wizard (project upgrade) shopware-cli#1237
• follow-up compatibility behavior from fix(project): let a successful composer resolve overrule stale extension blockers shopware-cli#1346
• report/changelog behavior from feat: enhance extension changelog handling with Store links shopware-cli#1366

Placement

The canonical feature reference lives under products/tools/cli/project-commands/upgrade.md.

The PR also updates:

• guides/upgrades-migrations/upgrade-shopware.md
• guides/upgrades-migrations/index.md
• guides/hosting/installation-updates/performing-updates.md

This 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 upgrade is merged on the Shopware CLI next branch, while the current stable CLI release is still 0.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.

[shopware-dev-docs-connector]

Developer Docs healthcheck

Status: Completed with success.
Repository: shopware/docs
Commit: b9212ac
Preview: https://developer-documentation-iqlyd9h9d-shopware-frontends.vercel.app
Workflow run: #4985

[Copilot]

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.

[somethings (lasomethingsomething)]

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.

[github-actions]

📢 Developer Announcement Recommendation

Recommendation: ❌ No Announcement Recommended

No developer announcement signals were detected.

This PR does not appear to introduce developer-facing changes that require a community announcement.

[Micha Hobert (Isengo1989)]

Heya Micha Hobert (Micha Hobert (@Isengo1989)) and Bojan Rajh (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.

Was on sick leave last Friday, checking now, not sure if too late 👋

[Micha Hobert (Isengo1989)]

Thanks for the PR somethings (@lasomethingsomething) 👍

Just left one comment, pls check ☑️

[somethings (lasomethingsomething)]

Micha Hobert (@Isengo1989) Good catch, thanks so much. I committed your suggestion.

[Soner (shyim)]

Micha Hobert (@Isengo1989) resolved that thread. we can merge this than

[somethings (lasomethingsomething)]

Soner (@shyim) can you switch this to an approve so that merging will be unblocked?

[somethings (lasomethingsomething)]

Heya Micha Hobert (@Isengo1989) , this just needs a merge now as Soner gave it the ol' green checkmark

[Micha Hobert (Isengo1989)]

Heya Micha Niskin (Micha Niskin (@micha)), this just needs a merge now as Soner gave it the ol' green checkmark

I think you meant me 😄 - so "done" 🙂