Enhancements of the upgrade guide for 18, since we detected some inconsistencies

docs/source/upgrade-guide/index.md

@@ -16,18 +16,40 @@ Volto uses Semantic Versioning.
 For more information see {doc}`../contributing/version-policy`.
 
 ```{note}
-There are times when updating the Volto boilerplate (the one generated by `@plone/generator-volto`) is enough to fulfill all the changes.
-If you have not heavily modified it, moving things around and copying over your dependencies might do when dealing with upgrades.
-We keep the generator up to date and in sync with the current Volto release.
-When it runs, the generator will tell you whether it is outdated.
-The generator will also "update" your project with the latest changes, and propose to merge the changes.
-Thus it is safe to run it on top of your project and answer the prompts.
+[Cookieplone](https://github.com/plone/cookieplone) is the official boilerplate generator for Plone projects.
+We keep Cookieplone up to date and in sync with the current Volto release.
+We encourage you to keep all your code inside your project add-on(s).
+If you do so, once you want to upgrade your project, you can generate a new project using Cookieplone with the same name as your old one, and copy over the add-ons to the new boilerplate.
+Even if you have modified the boilerplate, moving things around and copying over your dependencies is better and quicker than dealing with following the upgrade steps.
 ```
 
 (volto-upgrade-guide-18.x.x)=
 
 ## Upgrading to Volto 18.x.x
 
+(upgrade-18-cookieplone-label)=
+
+### Cookieplone is now the recommended project and add-on generator for Volto 18
+
+```{versionadded} Volto 18.0.0-alpha.43
+```
+
+[Cookieplone](https://github.com/plone/cookieplone) is now the recommended way to develop Volto projects, using it as a boilerplate generator.
+Cookieplone uses the frontend code installed using `pnpm` instead of `yarn`.
+This affects the way that the Plone Release Team generates the Sponsored OSS Docker images, since they must be compatible with the `pnpm` setup.
+
+Since Volto `18.0.0-alpha.43`, the Docker image [`plone-frontend`](https://hub.docker.com/r/plone/plone-frontend) uses `pnpm`.
+
+For developers that won't migrate their boilerplate and code to the new setup with `pnpm` instead of `yarn`, the Release Team will generate a new Docker image named `plone-frontend:18-yarn` for the Volto 18 series of alpha releases.
+
+Support for `yarn` will be dropped in Volto 19.
+
+```{deprecated} Volto 18.0.0-alpha.43
+The `yarn`-based generator [`@plone/generator-volto`](https://www.npmjs.com/package/@plone/generator-volto) package and project boilerplates generated from it are deprecated and will not receive any further updates.
+The recommended way of generating a project boilerplate is [Cookieplone](https://github.com/plone/cookieplone).
+Please update your code to use the `pnpm` based setup.
+```
+
 ### Node.js version support: adding 22, dropping 18
 
 Added support for Node.js 22.
@@ -43,6 +65,10 @@ Version 22 is recommended, as the latest LTS version of Node.js.
 
 ### Volto's internal `dependencies` and `devDependencies` are now properly sorted out
 
+```{deprecated} Volto 18.0.0-alpha.43
+This step is only valid for projects that choose to continue using `yarn`-based generator and they haven't updated to Cookieplone `pnpm`-based setups.
+```
+
 Volto internal `dependencies` and `devDependencies` have been correctly sorted out.
 This means that Volto no longer will force `devDependencies` as `dependencies` just to make sure that they get installed in Volto projects.
 This provoked undesired hoisting problems, and forced the build to not behave correctly in some situations.
@@ -65,6 +91,10 @@ This setting is no longer necessary.
 
 ### New dependencies synchronizer
 
+```{deprecated} Volto 18.0.0-alpha.43
+This step is only valid for projects that choose to continue using `yarn`-based generator and they haven't updated to Cookieplone `pnpm`-based setups.
+```
+
 ```{versionadded} Volto 18.0.0-alpha.21
 ```
 
@@ -147,23 +177,48 @@ As a last resort, you can install `react-portal` as a dependency of your project
 However, this is discouraged, because the React 18 rendering could have unexpected side effects.
 It is recommended that you use the React API instead.
 
-### ESlint project configuration update
+### `@plone/registry` moved to ESM
 
 `@plone/registry` and [other packages on which Volto depends](https://github.com/plone/volto/tree/main/packages) are now stand-alone releases in the monorepo structure released in 18.0.0-alpha.4.
 
-You must update the configuration file {file}`.eslintrc.js` in your projects, according to the following `git diff` patch.
+Also, the `@plone/registry` package has been moved to ESM.
+The add-on registry scripts have also been refactored to TypeScript.
+For maximum compatibility with CommonJS builds, the default exports have been moved to named exports.
+The modules affected are now built, and the import paths have changed, too.
+These changes force some import path changes that you should patch in your Plone project or add-on boilerplates.
+
+```{note}
+As always, when something changes in the boilerplate, you may regenerate one from Cookieplone and move your code into it, instead of fiddling with it.
+```
+
+For example, in your project's {file}`.eslintrc.js`:
 
 ```diff
-@@ -18,9 +19,6 @@ if (configFile) {
+ const fs = require('fs');
+ const projectRootPath = __dirname;
+-const AddonConfigurationRegistry = require('@plone/registry/src/addon-registry');
++const { AddonRegistry } = require('@plone/registry/addon-registry');
+
+ let voltoPath = './node_modules/@plone/volto';
+
+@@ -17,15 +17,15 @@ if (configFile) {
      voltoPath = `./${jsConfig.baseUrl}/${pathsConfig['@plone/volto'][0]}`;
  }
 
--const AddonConfigurationRegistry = require(
--  `${voltoPath}/packages/registry/addon-registry.js`,
--);
-const AddonConfigurationRegistry = require('@plone/registry/src/addon-registry');
+-const reg = new AddonConfigurationRegistry(__dirname);
++const { registry } = AddonRegistry.init(__dirname);
+
+ // Extends ESlint configuration for adding the aliases to `src` directories in Volto addons
+-const addonAliases = Object.keys(reg.packages).map((o) => [
++const addonAliases = Object.keys(registry.packages).map((o) => [
+   o,
+-  reg.packages[o].modulePath,
++  registry.packages[o].modulePath,
+ ]);
+
+-const addonExtenders = reg.getEslintExtenders().map((m) => require(m));
++const addonExtenders = registry.getEslintExtenders().map((m) => require(m));
 
-@@ -38,9 +36,7 @@ const defaultConfig = {
        alias: {
          map: [
            ['@plone/volto', '@plone/volto/src'],
@@ -175,6 +230,22 @@ const AddonConfigurationRegistry = require('@plone/registry/src/addon-registry')
            ['@package', `${__dirname}/src`],
 ```
 
+Also in the Storybook configuration {file}`.storybook/main.js`.
+
+```diff
+-    const AddonConfigurationRegistry = require('@plone/registry/src/addon-registry');
++    const { AddonRegistry } = require('@plone/registry/addon-registry');
+
+-    const registry = new AddonConfigurationRegistry(projectRootPath);
++    const { registry } = AddonRegistry.init(projectRootPath);
+```
+
+```{versionadded} Volto 18.0.0-alpha.47
+```
+
+```{versionadded} @plone/registry 3.0.0-alpha.0
+```
+
 ### Upgraded Slate libraries
 
 The support libraries for Slate integration have been upgraded, mainly for bug fixes.
@@ -463,30 +534,6 @@ schema: {
 The `Tags` component has been moved to the `belowContent` slot.
 It now receives the `content` property instead of the `tags` property.
 
-
-(upgrade-18-cookieplone-label)=
-
-### Cookieplone is now the recommended project and add-on generator for Volto 18
-
-```{versionadded} Volto 18.0.0-alpha.43
-```
-
-[Cookieplone](https://github.com/plone/cookieplone) is now the recommended way to develop Volto projects, using it as a boilerplate generator.
-Cookieplone uses the frontend code installed using `pnpm` instead of `yarn`.
-This affects the way that the Plone Release Team generates the Sponsored OSS Docker images, since they must be compatible with the `pnpm` setup.
-
-Since Volto `18.0.0-alpha.43`, the Docker image [`plone-frontend`](https://hub.docker.com/r/plone/plone-frontend) uses `pnpm`.
-
-For developers that won't migrate their boilerplate and code to the new setup with `pnpm` instead of `yarn`, the Release Team will generate a new Docker image named `plone-frontend:18-yarn` for the Volto 18 series of alpha releases.
-
-Support for `yarn` will be dropped in Volto 19.
-
-```{deprecated} Volto 18.0.0-alpha.43
-The `yarn`-based generator [`@plone/generator-volto`](https://www.npmjs.com/package/@plone/generator-volto) package and project boilerplates generated from it are deprecated and will not receive any further updates.
-The recommended way of generating a project boilerplate is [Cookieplone](https://github.com/plone/cookieplone).
-Please update your code to use the `pnpm` based setup.
-```
-
 ### Table of Contents block markup change
 
 The `View` component for the Table of Contents block was updated to use a `nav` element instead of a `div`.
@@ -527,63 +574,6 @@ The `react/jsx-key` rule has been enabled in ESlint for catching missing `key` i
 You might catch some violations in your project or add-on code after running ESlint.
 Adding the missing `key` property whenever the violation is reported will fix it.
 
-### `@plone/registry` moved to ESM
-
-The `@plone/registry` package has been moved to ESM.
-The add-on registry scripts have also been refactored to TypeScript.
-For maximum compatibility with CommonJS builds, the default exports have been moved to named exports.
-The modules affected are now built, and the import paths have changed, too.
-These changes force some import path changes that you should patch in your Plone project or add-on boilerplates.
-
-```{note}
-As always, when something changes in the boilerplate, you may regenerate one from Cookieplone and move your code into it, instead of fiddling with it.
-```
-
-For example, in your project's {file}`.eslintrc.js`:
-
-```diff
- const fs = require('fs');
- const projectRootPath = __dirname;
--const AddonConfigurationRegistry = require('@plone/registry/src/addon-registry');
-+const { AddonRegistry } = require('@plone/registry/addon-registry');
-
- let voltoPath = './node_modules/@plone/volto';
-
-@@ -17,15 +17,15 @@ if (configFile) {
-     voltoPath = `./${jsConfig.baseUrl}/${pathsConfig['@plone/volto'][0]}`;
- }
-
--const reg = new AddonConfigurationRegistry(__dirname);
-+const { registry } = AddonRegistry.init(__dirname);
-
- // Extends ESlint configuration for adding the aliases to `src` directories in Volto addons
--const addonAliases = Object.keys(reg.packages).map((o) => [
-+const addonAliases = Object.keys(registry.packages).map((o) => [
-   o,
--  reg.packages[o].modulePath,
-+  registry.packages[o].modulePath,
- ]);
-
--const addonExtenders = reg.getEslintExtenders().map((m) => require(m));
-+const addonExtenders = registry.getEslintExtenders().map((m) => require(m));
-```
-
-Also in the Storybook configuration {file}`.storybook/main.js`.
-
-```diff
--    const AddonConfigurationRegistry = require('@plone/registry/src/addon-registry');
-+    const { AddonRegistry } = require('@plone/registry/addon-registry');
-
--    const registry = new AddonConfigurationRegistry(projectRootPath);
-+    const { registry } = AddonRegistry.init(projectRootPath);
-```
-
-```{versionadded} Volto 18.0.0-alpha.47
-```
-
-```{versionadded} @plone/registry 3.0.0-alpha.0
-```
-
 ### Add missing overrides to projects in `package.json`
 
 This will fix some issues with Hot Module Reload in projects.

packages/volto/news/6609.documentation

@@ -0,0 +1 @@
+Enhancements of the upgrade guide for 18, since we detected some inconsistencies. @sneridagh