feat: improve performing updates docs

guides/hosting/installation-updates/performing-updates.md

@@ -9,67 +9,172 @@
 
 ## When to update
 
-Shopware releases updates every month. It's not necessary to update every month, but you should always install the latest security patches through the [Security Plugin](https://store.shopware.com/en/swag136939272659f/shopware-6-security-plugin.html) or update Shopware itself to the latest version. To check if your Shopware version still gets security updates, you can check the [Shopware Release Cycle](https://developer.shopware.com/release-notes/). But generally speaking, the maintenance effort is the same when you wait a long period or update more regularly. So our recommendation would be to update from every major version to the next major version, and stay on a minor version for a longer period of time, if you don't need any new features or encounter issues with the used version.
+Shopware releases updates every month. It's not necessary to update every month, but you should always install the latest security patches through the [Security Plugin](https://store.shopware.com/en/swag136939272659f/shopware-6-security-plugin.html) or update Shopware itself to the latest version. To check if your Shopware version still gets security updates, you can check the [Shopware Release Cycle](https://developer.shopware.com/release-notes/).
+
+Generally speaking, the maintenance effort is the same whether you wait a long period or update more regularly. Our recommendation is to update from every major version to the next major version, and stay on a minor version for a longer period of time if you don't need any new features or encounter issues with the used version.
+
+## Update types
+
+There are two Shopware update types:
+
+- **Minor/Patch updates**: These updates contain new features, bug fixes and security patches. They are released every month for the active supported versions. They don't require special attention if your extensions are not using internal/experimental APIs. You can find the Backwards Compatibility Promise [here](../../../resources/guidelines/code/backward-compatibility.md).
+- **Major updates**: These updates clean up the codebase and introduce breaking changes. They are released once a year. They require special attention, as extensions, themes or system configurations might not be compatible with the new version.
 
 ## Preparations
 
-Before any update, check if the installed extensions are compatible with the new version. The easiest way to check this is to open the Update Manager in the Administration. It lists all installed extensions and their compatibility with the new version. If an extension is not compatible, you should check with the extension developer if an update is available.
+### Check extension compatibility
 
-::: info
-If you can't see the info in the admin, please check if [auto_update](../installation-updates/cluster-setup#disable-auto-update) is set to false.
-:::
+Before any update, check if the installed extensions are compatible with the new version. Run the upgrade check command to analyze your project for compatibility issues:
+
+```bash
+shopware-cli project upgrade-check
+```
+
+This command checks your installed extensions against the target Shopware version. If an extension is not compatible, check with the extension developer if an update is available. If you don't have shopware-cli installed, see the [installation guide](../../../products/cli/installation.md).
+
+Managing all extensions through Composer is the best way to ensure compatibility. It simplifies the update process as Composer automatically resolves the correct versions of the extensions.
 
-The next step is to check when the update should be performed. You should always perform updates in a maintenance window to avoid any issues with customers. If you are using a staging environment, you can perform the update there first and then apply it to the production environment.
+### Create backups
 
-Before doing the actual update, you should create a backup of your database and files. This is important to ensure that you can restore your Shopware installation in case something goes wrong during the update process.
+Before doing the actual update, create a backup of your database and files. This ensures you can restore your Shopware installation if something goes wrong during the update process.
 
 ::: info
 If blue-green deployment is enabled, you can rollback to the previous version without restoring the database backup. This is only recommended when you **only updated** Shopware and not any extensions together with it.
 :::
 
-Before you start the update process, you should also make sure that you have set the Sales Channels into maintenance mode. This can be done using the Administration or with `bin/console sales-channel:maintenance:enable --all` in the terminal.
+### Enable maintenance mode
 
-### Use Composer to manage all extensions
+Before you start the update process, set the Sales Channels into maintenance mode. This can be done using the Administration or with the terminal:
 
-Managing all extensions through Composer is the best way to ensure that they are compatible with the new version. It simplifies the update process as Composer automatically resolves the correct versions of the extensions.
+```bash
+bin/console sales-channel:maintenance:enable --all
+```
 
-### Use Twig Block Versioning
+### Additional steps for major updates
 
-Twig Block Versioning is a [PHPStorm Plugin](https://plugins.jetbrains.com/plugin/17632-shopware-6-toolbox) only feature. Twig Block Versioning is a feature that allows versioning of the overwritten blocks in your theme. This helps you to show which blocks after a Shopware Update maybe have to be changed. It's recommended to enable "Shopware versioning block comment is missing" in the inspection settings. This will show you a warning if a block is missing the versioning comment. For more information, check the [Twig Block Versioning blog post](https://www.shopware.com/en/news/twig-block-versioning-in-shopware-phpstorm-plugin/).
+For major updates, consider the following additional preparations:
 
-### Use existing tools to automatically upgrade your extensions
+- **Update PHP version**: Update the PHP version to the minimum required version for the new Shopware version *before* updating Shopware. Shopware versions always support an overlapping PHP version, so this is safe to do beforehand. You can find the minimum required PHP version in the [System Requirements](../../installation/requirements.md).
+- **Check the UPGRADE.md**: Review the [UPGRADE.md](https://github.com/search?q=repo%3Ashopware%2Fshopware+UPGRADE-6+language%3AMarkdown+NOT+path%3A%2F%5Eadr%5C%2F%2F+NOT+path%3A%2F%5Echangelog%5C%2F%2F&type=code&l=Markdown) for all breaking changes and migration instructions.
+- **Update extensions first**: Update all extensions to their latest versions before updating Shopware to ensure a smooth transition. After updating Shopware, update all extensions again to get versions compatible with the new Shopware version.
 
-There are tools like [Rector](https://github.com/FriendsOfShopware/shopware-rector) for PHP and [Codemods](https://github.com/shopware/shopware/blob/trunk/src/Administration/Resources/app/administration/code-mods.js) for Administration JavaScript which can help you to automatically upgrade your extensions. Both tools do the most repeating tasks for you, but you still have to check the results and adapt your code if necessary. It's recommended to use these tools, as they save you a lot of time. Make sure that your code-base is versioned with Git, so you can easily rollback the changes if necessary.
+## Performing the update via CLI (recommended)
 
-## Update types
+The recommended way to update Shopware is via the command line. The update process consists of two phases: preparing the update locally and deploying it to the server.
 
-There are two Shopware update types:
+### Local development environment
+
+Perform the following steps in your local development environment:
+
+#### 1. Update the Shopware version constraint
+
+Edit your `composer.json` and update the `shopware/core` version constraint to the target version:
+
+```json
+{
+    "require": {
+        "shopware/core": "6.7.0.0"
+    }
+}
+```
+
+#### 2. Run Composer update
+
+Run the update command with `--no-scripts` to prevent the automatic execution of scripts during the update:
+
+```bash
+composer update --no-scripts
+```
+
+#### 3. Update Symfony Flex recipes
+
+Update the Symfony Flex recipes to apply any configuration changes:
 
-- **Minor/Patch updates**: These are updates that only contain new features, bug fixes and security patches. They are released every month for the active supported versions.
-- **Major updates**: These updates are intended to clean up the codebase and introduce breaking changes. They are released once a year.
+```bash
+composer recipes:update
+```
 
-### Minor/Patch updates
+This command shows available recipe updates and allows you to apply them interactively. Review the changes carefully before applying them.
 
-Minor and patch updates are non-breaking updates. They don't require special attention if your extensions are not using internal/experimental APIs. You can find the Backwards Compatibility Promise [here](../../../resources/guidelines/code/backward-compatibility.md). Of course, there can be unexpected issues, so we recommend to test the update in a staging environment before applying it to your production environment and [reporting](https://github.com/shopware/shopware/issues) any issues you encounter.
+#### 4. Commit and deploy
 
-### Major updates
+Commit the changes to your Git repository:
 
-Major updates are breaking updates. They require special attention, as extensions, themes or system configurations might not be compatible with the new version.
+```bash
+git add composer.json composer.lock
+git commit -m "Update Shopware to 6.7.0"
+```
 
-First, you should check that all extensions obtained from Shopware Store are compatible with the next version. You can find the compatibility information in the Update Manager in the Administration. Generally speaking, it's recommended to update all extensions before updating Shopware itself to their latest versions, to ensure a smooth transition. After updating Shopware, you should update all extensions again to ensure that you are using the latest versions to the new Shopware version.
+Review any other changed files (e.g., from recipe updates) and commit them as well. Then deploy the changes to your server using your deployment process.
 
-For the Hosting environment, it makes sense to update the PHP version to the minimum required version for the new Shopware version before updating Shopware itself. Shopware versions always support an overlapping PHP version, so you can update the PHP version before updating Shopware itself. You can find the minimum required PHP version in the [System Requirements](../../installation/requirements.md).
+### Production server
 
-For customizations, you should check the [UPGRADE.md](https://github.com/search?q=repo%3Ashopware%2Fshopware+UPGRADE-6+language%3AMarkdown+NOT+path%3A%2F%5Eadr%5C%2F%2F+NOT+path%3A%2F%5Echangelog%5C%2F%2F&type=code&l=Markdown), it contains all breaking changes and migration instructions. Most of the time, it's easier to update to the latest version in a local environment and take a look at what is not working anymore.
+After deploying the updated code to your server, run the following commands:
 
-## Final Steps
+#### 1. Enable maintenance mode
 
-Before you remove the maintenance mode, it is recommended to check the following:
+```bash
+bin/console sales-channel:maintenance:enable --all
+```
+
+#### 2. Prepare the update
+
+```bash
+bin/console system:update:prepare
+```
+
+This command triggers events that allow extensions to prepare for the update.
+
+#### 3. Finish the update
+
+Run the Shopware update scripts to execute database migrations and other necessary update tasks:
+
+```bash
+bin/console system:update:finish
+```
+
+#### 4. Disable maintenance mode
+
+```bash
+bin/console sales-channel:maintenance:disable --all
+```
+
+::: warning
+Only run these commands on the production server after the updated code has been deployed. The migrations must match the deployed code version.
+:::
+
+## Performing the update via Administration
+
+Shopware also provides a web-based updater in the Administration panel. This method handles the entire update process through the browser.
+
+::: warning
+The web updater is only recommended for small instances. Since the update runs in the browser, you may encounter timeout problems, memory limits, or other resource issues on larger shops. For production environments, use the CLI method described above.
+:::
+
+To use the web updater:
+
+1. Log in to the Administration
+2. Navigate to **Settings** > **System** > **Shopware Update**
+3. Follow the on-screen instructions to complete the update
+
+The web updater will automatically enable maintenance mode, download the update, run migrations, and disable maintenance mode when complete.
+
+## Final steps
+
+Before you remove the maintenance mode, verify the update was successful:
 
 - **Check the Administration**: Make sure the administration is working correctly.
-- **Check the Storefront / Sales Channels**: Make sure your main processes are working correctly (e.g., adding products to the cart, checkout, etc.).
+- **Check the Storefront**: Make sure your main processes are working correctly (e.g., adding products to the cart, checkout, etc.).
 - **Check the Extensions**: Make sure that all extensions are working correctly.
 - **Check the Performance**: Make sure that there is no major performance degradation.
 - **Check the Logs**: Check your error logs for any issues.
 
-After you have checked everything, you can disable the maintenance mode with `bin/console sales-channel:maintenance:disable --all`.
+## Tools for extension developers
+
+If you maintain custom extensions, these tools can help with upgrades:
+
+- **[Rector for Shopware](https://github.com/FriendsOfShopware/shopware-rector)**: Automatically upgrades PHP code for Shopware compatibility.
+- **[Codemods](https://github.com/shopware/shopware/blob/trunk/src/Administration/Resources/app/administration/code-mods.js)**: Helps upgrade Administration JavaScript code.
+- **[Twig Block Versioning](https://www.shopware.com/en/news/twig-block-versioning-in-shopware-phpstorm-plugin/)**: A [PHPStorm Plugin](https://plugins.jetbrains.com/plugin/17632-shopware-6-toolbox) feature that tracks which Twig blocks you've overwritten and alerts you when they may need updates.
+
+These tools handle repetitive tasks but always review the results. Make sure your code is versioned with Git so you can rollback changes if necessary.

guides/installation/template.md

@@ -103,11 +103,9 @@
 
 ## Update Shopware
 
-There are two ways to update Shopware:
+For detailed instructions on performing Shopware updates, including preparation steps, the update process, and post-update verification, refer to the dedicated guide:
 
-* Initially run `bin/console system:update:prepare` to enable the maintenance mode and then update all Composer packages using `composer update --no-scripts`. The `--no-scripts` flag instructs composer to not run any scripts that may reference Shopware CLI commands. They will only be functional after updating the recipes. To disable the maintenance mode, run `bin/console system:update:finish`.
-
-* To force-update all config files, run `composer recipes:update`.
+<PageRef page="../hosting/installation-updates/performing-updates" title="Performing Shopware Updates" />
 
 ## Migrate from the old zip installation to a new project template