Merge pull request #2063 from ga-devfront/feat/8.x/add-recommended-documentation-for-autoup

[UPDATE] Autoupgrade documentation for 8.x

Author: kpodemski

basics/keeping-up-to-date/update/img/update-assistant-version-choice-page.png

@@ -54,13 +54,25 @@ main steps: Version choice > Update options > Backup > Update > Post-update.
 
 ### Version choice
 
-The step “Version choice”, shows you the updates available for your store. Two update channels are listed at this stage:
-
-- The official “online” update for your store, detected by PrestaShop APIs (major, minor or patch versions). This update
-  corresponds to the most recent version of PrestaShop compatible with the PHP version of your server.
-- The “local” update, which displays customized updates detected in your `/your-admin-directory/autoupgrade/download`
+The step "Version choice", shows you the updates available for your store. Up to three update channels can be listed at this stage:
+
+- The official **"recommended"** update for your store, detected by PrestaShop APIs (major, minor or patch versions). This update
+  corresponds to the most stable and well-tested version of PrestaShop compatible with the PHP version of your server. The recommended
+  version is identified by a "Recommended" badge displayed next to the version type badge (major, minor, or patch).
+- The **"latest"** update available for your store, which corresponds to the most recent version of PrestaShop compatible with the
+  PHP version of your server. This version may be shown separately from the recommended version when they differ.
+- The **"local"** update, which displays customized updates detected in your `/your-admin-directory/autoupgrade/download`
   folder on your server.
 
+#### Understanding recommended versions
+
+The recommended version is the version that has been thoroughly tested and validated for stability. It may not always be the latest
+release, but it represents the safest upgrade path for your store. Depending on the current state of PrestaShop releases, you may see:
+
+- Both a **recommended version** and a **latest version** displayed as separate options (when they differ).
+- Only one version displayed with a "Recommended" badge (when the recommended version is also the latest).
+- Only the latest version without a "Recommended" badge (when no specific version is marked as recommended).
+
 These views are thus adapted to the version of PrestaShop used in your store, to the PHP version of your server, and
 therefore reflect possible updates for your store.
 
@@ -224,4 +236,4 @@ You will then be able to log in to access the previous, restored version of your
 [1]: {{< relref "/8/basics/keeping-up-to-date/update/update-from-the-cli" >}}
 [2]: {{< relref "/8/basics/keeping-up-to-date/update/post-update-checklist" >}}
 [3]: {{< relref "/8/basics/keeping-up-to-date/update/post-restore-checklist" >}}
-[prestashop-releases]: https://github.com/PrestaShop/PrestaShop/releases
+[prestashop-releases]: https://github.com/PrestaShop/PrestaShop/releases

basics/keeping-up-to-date/update/update-from-the-back-office.md

@@ -295,18 +295,34 @@ Example of the `update:check-new-version` command execution:
 
 ```text
 $ php bin/console update:check-new-version admin123
------------+----------+-------+---------------------------------------------------------------------------+
-| Version  | Channel  | Type  | Information                                                               |
-+----------+----------+-------+---------------------------------------------------------------------------+
-| 8.2.0    | online   | minor | https://build.prestashop-project.org/news/2024/prestashop-8-2-0-available/|
-| 9.0.0    | local    | major | Zip: 2024-10-17-develop-prestashop_9_0_0.zip                              |
-|          |          |       | Xml: prestashop_9.0.0.xml                                                 |
-| 8.1.0    | local    | patch | Zip: 8_1_0.zip                                                            |
-|          |          |       | Xml: 8.1.0-2.xml, 8.1.0.xml                                               |
++---------+--------------------+-------+--------------------------------------------------------------------------------------+
+| Version | Channel            | Type  | Information                                                                          |
++---------+--------------------+-------+--------------------------------------------------------------------------------------+
+| 8.2.3   | online_recommended | minor | https://build.prestashop-project.org/news/2025/prestashop-8-2-3-security-release/    |
+| 9.0.1   | online             | major | https://build.prestashop-project.org/news/2025/prestashop-9-0-1-maintenance-release/ |
+| 9.0.0   | local              | major | Zip: 2024-10-17-develop-prestashop_9_0_0.zip                                         |
+|         |                    |       | Xml: prestashop_9.0.0.xml                                                            |
+| 8.1.1   | local              | patch | Zip: 8_1_1.zip                                                                       |
+|         |                    |       | Xml: 8.1.1-2.xml, 8.1.1.xml                                                          |
++---------+--------------------+-------+--------------------------------------------------------------------------------------+
 ```
 
-- The official “online” update for your store, detected by PrestaShop APIs (major, minor or patch versions). This update corresponds to the most recent version of PrestaShop compatible with the PHP version of your server.
-- The “local” update, which displays customized updates detected in your `/your-admin-directory/autoupgrade/download` folder on your server.
+#### Understanding the Channel column
+
+The **Channel** column indicates the source and type of the available update:
+
+- **`online_recommended`**: The recommended update for your store, detected by PrestaShop APIs (major, minor or patch versions). This update corresponds to the most stable and well-tested version of PrestaShop compatible with the PHP version of your server. The recommended version represents the safest upgrade path for your store.
+- **`online`**: The latest update available for your store, which corresponds to the most recent version of PrestaShop compatible with the PHP version of your server. This version may differ from the recommended version.
+- **`local`**: Customized updates detected in your `/your-admin-directory/autoupgrade/download` folder on your server.
+
+#### Update scenarios
+
+Depending on the current state of PrestaShop releases, the command output may show:
+
+- Both a **recommended version** (channel `online_recommended`) and a **latest version** (channel `online`) when they differ.
+- Only one online version (channel `online_recommended`) when the recommended version is also the latest.
+- Only the latest version (channel `online`) when no specific version is marked as recommended.
+- Local versions (channel `local`) in addition to online versions, if custom update files are detected on your server.
 
 ### update:check-requirements command