From 1915783c6f6ae16d86a520979235059c96deafb7 Mon Sep 17 00:00:00 2001 From: Victor Fernandez de Alba Date: Tue, 21 Jan 2025 17:04:31 +0100 Subject: [PATCH 1/5] Enhancements of the upgrade guide for 18, since we detected some inconsistencies. --- docs/source/upgrade-guide/index.md | 180 ++++++++++++++--------------- 1 file changed, 85 insertions(+), 95 deletions(-) diff --git a/docs/source/upgrade-guide/index.md b/docs/source/upgrade-guide/index.md index 23e2903a18..6d9c2546c4 100644 --- a/docs/source/upgrade-guide/index.md +++ b/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. From 9244d3bf1311aef74c5adcfc9201312633f35ecc Mon Sep 17 00:00:00 2001 From: Victor Fernandez de Alba Date: Tue, 21 Jan 2025 17:06:29 +0100 Subject: [PATCH 2/5] Changelog --- packages/volto/news/6609.documentation | 1 + 1 file changed, 1 insertion(+) create mode 100644 packages/volto/news/6609.documentation diff --git a/packages/volto/news/6609.documentation b/packages/volto/news/6609.documentation new file mode 100644 index 0000000000..969d5c68aa --- /dev/null +++ b/packages/volto/news/6609.documentation @@ -0,0 +1 @@ +Enhancements of the upgrade guide for 18, since we detected some inconsistencies. @sneridagh From 6612ba77e063584bcea7c0d5a8338c367c0a08bb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?V=C3=ADctor=20Fern=C3=A1ndez=20de=20Alba?= Date: Wed, 22 Jan 2025 10:55:16 +0100 Subject: [PATCH 3/5] Apply suggestions from code review Co-authored-by: Steve Piercy Co-authored-by: David Glick --- docs/source/upgrade-guide/index.md | 23 +++++++++++++---------- packages/volto/news/6609.documentation | 2 +- 2 files changed, 14 insertions(+), 11 deletions(-) diff --git a/docs/source/upgrade-guide/index.md b/docs/source/upgrade-guide/index.md index 6d9c2546c4..2d0f490fb2 100644 --- a/docs/source/upgrade-guide/index.md +++ b/docs/source/upgrade-guide/index.md @@ -16,11 +16,11 @@ Volto uses Semantic Versioning. For more information see {doc}`../contributing/version-policy`. ```{note} -[Cookieplone](https://github.com/plone/cookieplone) is the official boilerplate generator for Plone projects. +[Cookieplone](https://github.com/plone/cookieplone) is the official project generator for Plone. 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. +If you do so, when 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 your add-ons to the new project. +It is usually better and quicker to move your items into new locations and copy your dependencies than dealing with following the upgrade steps, regardless of whether you have modified the boilerplate. ``` (volto-upgrade-guide-18.x.x)= @@ -34,20 +34,20 @@ Even if you have modified the boilerplate, moving things around and copying over ```{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](https://github.com/plone/cookieplone) is now the recommended way to develop Volto projects, using it as a boilerplate project 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. +For developers that won't migrate their projects 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. +The recommended way of generating a boilerplate project 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 @@ -66,7 +66,8 @@ 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. +This step is only valid for projects that continue to use the `yarn`-based generator and haven't updated to Cookieplone `pnpm`-based setups. +See {ref}`upgrade-18-cookieplone-label` for details. ``` Volto internal `dependencies` and `devDependencies` have been correctly sorted out. @@ -92,7 +93,8 @@ 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. +This step is only valid for projects that continue to use the `yarn`-based generator and haven't updated to Cookieplone `pnpm`-based setups. +See {ref}`upgrade-18-cookieplone-label` for details. ``` ```{versionadded} Volto 18.0.0-alpha.21 @@ -188,7 +190,8 @@ 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. +As always, when something changes in the boilerplate project generator, you may generate a new project with Cookieplone and move your code into it, instead of manually editing multiple files. +See {ref}`upgrade-18-cookieplone-label` for details. ``` For example, in your project's {file}`.eslintrc.js`: diff --git a/packages/volto/news/6609.documentation b/packages/volto/news/6609.documentation index 969d5c68aa..92d9888694 100644 --- a/packages/volto/news/6609.documentation +++ b/packages/volto/news/6609.documentation @@ -1 +1 @@ -Enhancements of the upgrade guide for 18, since we detected some inconsistencies. @sneridagh +Enhancements of the upgrade guide for Volto 18, since we detected some inconsistencies. @sneridagh From 29275146f1f3d7ae5bba82b2adee57722120fe72 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?V=C3=ADctor=20Fern=C3=A1ndez=20de=20Alba?= Date: Wed, 22 Jan 2025 12:02:54 +0100 Subject: [PATCH 4/5] Update docs/source/upgrade-guide/index.md Co-authored-by: Steve Piercy --- docs/source/upgrade-guide/index.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/source/upgrade-guide/index.md b/docs/source/upgrade-guide/index.md index 2d0f490fb2..95211bce3b 100644 --- a/docs/source/upgrade-guide/index.md +++ b/docs/source/upgrade-guide/index.md @@ -18,7 +18,8 @@ For more information see {doc}`../contributing/version-policy`. ```{note} [Cookieplone](https://github.com/plone/cookieplone) is the official project generator for Plone. 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). + +To make it easier for you to maintain your projects, you should keep all your code inside your project add-ons. If you do so, when 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 your add-ons to the new project. It is usually better and quicker to move your items into new locations and copy your dependencies than dealing with following the upgrade steps, regardless of whether you have modified the boilerplate. ``` From fa23dcfd8bfb3957cb204420e7034fc769dde606 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Wed, 22 Jan 2025 03:28:30 -0800 Subject: [PATCH 5/5] There's no directive `info`, so use `note` instead. --- packages/registry/docs/how-to-guides/register-routes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/registry/docs/how-to-guides/register-routes.md b/packages/registry/docs/how-to-guides/register-routes.md index 41b79656c0..77c26c7c49 100644 --- a/packages/registry/docs/how-to-guides/register-routes.md +++ b/packages/registry/docs/how-to-guides/register-routes.md @@ -32,7 +32,7 @@ The `type`, `path`, and `file` are mandatory. The `type` key specifies the route type to create, specifically one of `route`, `index`, `layout`, or `prefix`. The type `route` can contain nested routes. -```{info} +```{note} The routes registered with this method must be compliant with React Router 7 routes. They are loaded by a helper provided by `@plone/react-router` in an existing React Router 7 app. Check the official [React Router 7 documentation](https://reactrouter.com/start/framework/routing) for more information on how to define React Router 7 routes.