From 5662db5a540508c93143dfd771b8aec34dcce957 Mon Sep 17 00:00:00 2001 From: somethings Date: Fri, 21 Aug 2026 15:18:58 +0200 Subject: [PATCH 1/7] docs: document Shopware CLI Administration migrations --- .../administration/index.md | 2 + .../tools/cli/administration-migrations.md | 77 +++++++++++++++++++ products/tools/cli/automatic-refactoring.md | 2 + 3 files changed, 81 insertions(+) create mode 100644 products/tools/cli/administration-migrations.md diff --git a/guides/upgrades-migrations/administration/index.md b/guides/upgrades-migrations/administration/index.md index 8e5c34f289..4768a1a087 100644 --- a/guides/upgrades-migrations/administration/index.md +++ b/guides/upgrades-migrations/administration/index.md @@ -15,3 +15,5 @@ These guides cover architectural changes and migration paths affecting Administr * [Vite migration](./vite) * [Vue migration build removal](./vue-migration-build) * [Native Vue implementation](./vue-native) + +For automated detection and fixing of supported Administration migration patterns, see the [Shopware CLI Administration migrations](../../../products/tools/cli/administration-migrations.md) reference. diff --git a/products/tools/cli/administration-migrations.md b/products/tools/cli/administration-migrations.md new file mode 100644 index 0000000000..9c6009874d --- /dev/null +++ b/products/tools/cli/administration-migrations.md @@ -0,0 +1,77 @@ +--- +nav: + title: Administration migrations + position: 5003 + +--- + +# Administration migrations + +Shopware CLI includes built-in checks and fixes for known Shopware Administration migration patterns. + +These rules help identify source changes that are required when upgrading Administration extensions between supported Shopware versions. The rules are intentionally limited to patterns that can be identified deterministically. + +## Check Administration code for migration issues + +Run the project fixer to apply supported migration fixes automatically: + +```shell +shopware-cli project fix /path/to/your/project +``` + +For a single extension: + +```shell +shopware-cli extension fix /path/to/your/extension +``` + +The fixer includes custom rules for Administration Twig files in addition to the PHP and JavaScript tooling described in [Automatic refactoring](./automatic-refactoring.md). + +::: warning +`project fix` and `extension fix` modify files in place. Run them on a Git branch or a copy of your project so that you can review the changes before committing them. +::: + +## Administration Twig migrations + +Shopware CLI contains a set of known Administration Twig migration rules. + +The rules are intended for cases where the old pattern and its replacement are known and can be detected without ambiguity. They are not a general-purpose Administration migration engine and do not guarantee that an extension is fully compatible with a target Shopware version. + +Supported rules may cover changes such as: + +- Administration component migrations +- Component property or event changes +- Other deterministic Twig patterns with a known replacement + +The exact set of rules is maintained by Shopware CLI and can change as new Shopware versions introduce additional migration requirements. + +## When to use the fixer + +Use the Administration migration rules as part of an upgrade workflow: + +1. Update the Shopware version constraint in your project. +2. Run `shopware-cli project fix` or `shopware-cli extension fix`. +3. Review the generated changes. +4. Run your normal validation and tests. +5. Check any Administration code that was not covered by a deterministic fixer rule manually. + +For extension validation, see [Validation](./validation.md). + +## Limitations + +The Administration migration rules are deliberately bounded. + +The CLI does not attempt to: + +- comprehensively analyse Administration compatibility +- modify arbitrary JavaScript or Vue code +- validate browser behaviour +- automatically resolve ambiguous migration patterns + +Manual review is still required for Administration changes that are not covered by a deterministic rule. + +## Related documentation + +- [Automatic refactoring](./automatic-refactoring.md) +- [Validation](./validation.md) +- [Administration migrations](../../../guides/upgrades-migrations/administration/index.md) diff --git a/products/tools/cli/automatic-refactoring.md b/products/tools/cli/automatic-refactoring.md index e2f508c062..f69cf9b61d 100644 --- a/products/tools/cli/automatic-refactoring.md +++ b/products/tools/cli/automatic-refactoring.md @@ -21,6 +21,8 @@ The tool uses: - [ESLint](https://eslint.org/) for JavaScript - Custom rules for Admin Twig files +For the supported Administration migration rules, see [Administration migrations](./administration-migrations.md). + The refactoring command runs PHP and Node.js tooling under the hood. The Docker examples are recommended because the image already contains the required runtime dependencies. If PHP and Node.js are available locally, you can run the `shopware-cli` commands directly instead. ## Refactoring an extension From 7edd1d7bae1bbcaf0b3c86391939fdfe37dc1396 Mon Sep 17 00:00:00 2001 From: somethings Date: Fri, 21 Aug 2026 15:21:57 +0200 Subject: [PATCH 2/7] Update administration-migrations.md --- products/tools/cli/administration-migrations.md | 7 +------ 1 file changed, 1 insertion(+), 6 deletions(-) diff --git a/products/tools/cli/administration-migrations.md b/products/tools/cli/administration-migrations.md index 9c6009874d..fedac41fbe 100644 --- a/products/tools/cli/administration-migrations.md +++ b/products/tools/cli/administration-migrations.md @@ -59,7 +59,7 @@ For extension validation, see [Validation](./validation.md). ## Limitations -The Administration migration rules are deliberately bounded. +The [Administration migration](../../../guides/upgrades-migrations/administration/index.md) rules are deliberately bounded. The CLI does not attempt to: @@ -70,8 +70,3 @@ The CLI does not attempt to: Manual review is still required for Administration changes that are not covered by a deterministic rule. -## Related documentation - -- [Automatic refactoring](./automatic-refactoring.md) -- [Validation](./validation.md) -- [Administration migrations](../../../guides/upgrades-migrations/administration/index.md) From 9341e9fdebe94ecf1eb27b58b1660d227f7985ae Mon Sep 17 00:00:00 2001 From: somethings Date: Fri, 21 Aug 2026 15:22:13 +0200 Subject: [PATCH 3/7] Update administration-migrations.md --- products/tools/cli/administration-migrations.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/products/tools/cli/administration-migrations.md b/products/tools/cli/administration-migrations.md index fedac41fbe..74b9988a87 100644 --- a/products/tools/cli/administration-migrations.md +++ b/products/tools/cli/administration-migrations.md @@ -1,11 +1,11 @@ --- nav: - title: Administration migrations + title: Administration Migrations position: 5003 --- -# Administration migrations +# Administration Migrations Shopware CLI includes built-in checks and fixes for known Shopware Administration migration patterns. From 5405ac64833c4177015004ca3d7fac0b9e9ca560 Mon Sep 17 00:00:00 2001 From: somethings Date: Fri, 21 Aug 2026 15:23:11 +0200 Subject: [PATCH 4/7] Update automatic-refactoring.md --- products/tools/cli/automatic-refactoring.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/products/tools/cli/automatic-refactoring.md b/products/tools/cli/automatic-refactoring.md index f69cf9b61d..8a1a6f1fb6 100644 --- a/products/tools/cli/automatic-refactoring.md +++ b/products/tools/cli/automatic-refactoring.md @@ -21,7 +21,7 @@ The tool uses: - [ESLint](https://eslint.org/) for JavaScript - Custom rules for Admin Twig files -For the supported Administration migration rules, see [Administration migrations](./administration-migrations.md). +For the supported Administration migration rules, see [Administration Migrations](./administration-migrations.md). The refactoring command runs PHP and Node.js tooling under the hood. The Docker examples are recommended because the image already contains the required runtime dependencies. If PHP and Node.js are available locally, you can run the `shopware-cli` commands directly instead. From 2e11775b39239a756cfb93ada7a04b4a73ad574b Mon Sep 17 00:00:00 2001 From: somethings Date: Fri, 21 Aug 2026 15:24:51 +0200 Subject: [PATCH 5/7] Update administration-migrations.md --- products/tools/cli/administration-migrations.md | 1 - 1 file changed, 1 deletion(-) diff --git a/products/tools/cli/administration-migrations.md b/products/tools/cli/administration-migrations.md index 74b9988a87..bc1fccd200 100644 --- a/products/tools/cli/administration-migrations.md +++ b/products/tools/cli/administration-migrations.md @@ -69,4 +69,3 @@ The CLI does not attempt to: - automatically resolve ambiguous migration patterns Manual review is still required for Administration changes that are not covered by a deterministic rule. - From cf13e58d4b91e5761a0dc276f2ebbaaed169adfd Mon Sep 17 00:00:00 2001 From: somethings Date: Fri, 21 Aug 2026 15:29:30 +0200 Subject: [PATCH 6/7] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- products/tools/cli/administration-migrations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/products/tools/cli/administration-migrations.md b/products/tools/cli/administration-migrations.md index bc1fccd200..0f5ed68180 100644 --- a/products/tools/cli/administration-migrations.md +++ b/products/tools/cli/administration-migrations.md @@ -59,7 +59,7 @@ For extension validation, see [Validation](./validation.md). ## Limitations -The [Administration migration](../../../guides/upgrades-migrations/administration/index.md) rules are deliberately bounded. +The Administration migration rules are deliberately bounded. For background and manual migration guidance, see the [Administration migration guide](../../../guides/upgrades-migrations/administration/index.md). The CLI does not attempt to: From 473193696aa9c47101970a2f74a895ef8099ea76 Mon Sep 17 00:00:00 2001 From: somethings Date: Mon, 24 Aug 2026 12:04:37 +0200 Subject: [PATCH 7/7] docs: consolidate Administration migration guidance --- .../administration/index.md | 2 +- .../tools/cli/administration-migrations.md | 71 ------------------- products/tools/cli/automatic-refactoring.md | 10 ++- 3 files changed, 9 insertions(+), 74 deletions(-) delete mode 100644 products/tools/cli/administration-migrations.md diff --git a/guides/upgrades-migrations/administration/index.md b/guides/upgrades-migrations/administration/index.md index 4768a1a087..2d01354dc4 100644 --- a/guides/upgrades-migrations/administration/index.md +++ b/guides/upgrades-migrations/administration/index.md @@ -16,4 +16,4 @@ These guides cover architectural changes and migration paths affecting Administr * [Vue migration build removal](./vue-migration-build) * [Native Vue implementation](./vue-native) -For automated detection and fixing of supported Administration migration patterns, see the [Shopware CLI Administration migrations](../../../products/tools/cli/administration-migrations.md) reference. +For automated detection and fixing of supported Administration migration patterns, see the [Shopware CLI automatic refactoring](../../../products/tools/cli/automatic-refactoring.md) guide. diff --git a/products/tools/cli/administration-migrations.md b/products/tools/cli/administration-migrations.md deleted file mode 100644 index 0f5ed68180..0000000000 --- a/products/tools/cli/administration-migrations.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -nav: - title: Administration Migrations - position: 5003 - ---- - -# Administration Migrations - -Shopware CLI includes built-in checks and fixes for known Shopware Administration migration patterns. - -These rules help identify source changes that are required when upgrading Administration extensions between supported Shopware versions. The rules are intentionally limited to patterns that can be identified deterministically. - -## Check Administration code for migration issues - -Run the project fixer to apply supported migration fixes automatically: - -```shell -shopware-cli project fix /path/to/your/project -``` - -For a single extension: - -```shell -shopware-cli extension fix /path/to/your/extension -``` - -The fixer includes custom rules for Administration Twig files in addition to the PHP and JavaScript tooling described in [Automatic refactoring](./automatic-refactoring.md). - -::: warning -`project fix` and `extension fix` modify files in place. Run them on a Git branch or a copy of your project so that you can review the changes before committing them. -::: - -## Administration Twig migrations - -Shopware CLI contains a set of known Administration Twig migration rules. - -The rules are intended for cases where the old pattern and its replacement are known and can be detected without ambiguity. They are not a general-purpose Administration migration engine and do not guarantee that an extension is fully compatible with a target Shopware version. - -Supported rules may cover changes such as: - -- Administration component migrations -- Component property or event changes -- Other deterministic Twig patterns with a known replacement - -The exact set of rules is maintained by Shopware CLI and can change as new Shopware versions introduce additional migration requirements. - -## When to use the fixer - -Use the Administration migration rules as part of an upgrade workflow: - -1. Update the Shopware version constraint in your project. -2. Run `shopware-cli project fix` or `shopware-cli extension fix`. -3. Review the generated changes. -4. Run your normal validation and tests. -5. Check any Administration code that was not covered by a deterministic fixer rule manually. - -For extension validation, see [Validation](./validation.md). - -## Limitations - -The Administration migration rules are deliberately bounded. For background and manual migration guidance, see the [Administration migration guide](../../../guides/upgrades-migrations/administration/index.md). - -The CLI does not attempt to: - -- comprehensively analyse Administration compatibility -- modify arbitrary JavaScript or Vue code -- validate browser behaviour -- automatically resolve ambiguous migration patterns - -Manual review is still required for Administration changes that are not covered by a deterministic rule. diff --git a/products/tools/cli/automatic-refactoring.md b/products/tools/cli/automatic-refactoring.md index 8a1a6f1fb6..157dc976d4 100644 --- a/products/tools/cli/automatic-refactoring.md +++ b/products/tools/cli/automatic-refactoring.md @@ -21,8 +21,6 @@ The tool uses: - [ESLint](https://eslint.org/) for JavaScript - Custom rules for Admin Twig files -For the supported Administration migration rules, see [Administration Migrations](./administration-migrations.md). - The refactoring command runs PHP and Node.js tooling under the hood. The Docker examples are recommended because the image already contains the required runtime dependencies. If PHP and Node.js are available locally, you can run the `shopware-cli` commands directly instead. ## Refactoring an extension @@ -104,6 +102,14 @@ shopware-cli project fix /path/to/your/project --allow-non-git By default, `project fix` requires a Git repository to safely track changes. +### Administration migration rules + +The fixer also includes deterministic rules for known Administration migration patterns, including Administration Twig component migrations and component property or event changes. These rules apply when running `project fix` or `extension fix` as described above. + +The rules only cover cases where the old pattern and its replacement can be identified without ambiguity. They are not a general-purpose Administration migration engine and do not guarantee full compatibility with a target Shopware version. Manual review is still required for changes that are not covered by a deterministic rule. + +For manual migration guidance, see the [Administration migration guide](../../../guides/upgrades-migrations/administration/index.md). + ## After running refactoring Use Git or your diff tool to review the changes.