From fc81f42bc97df6ceafee5a6f815c3c4b250b0aad Mon Sep 17 00:00:00 2001 From: Victor Fernandez de Alba Date: Tue, 22 Oct 2024 23:01:37 +0200 Subject: [PATCH 1/6] Add deprecation notices to the Upgrade guide --- docs/source/upgrade-guide/index.md | 118 +++++++++++++++++++++++++++++ 1 file changed, 118 insertions(+) diff --git a/docs/source/upgrade-guide/index.md b/docs/source/upgrade-guide/index.md index 321510c672..7aafd2d27f 100644 --- a/docs/source/upgrade-guide/index.md +++ b/docs/source/upgrade-guide/index.md @@ -522,6 +522,124 @@ 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. +### Deprecation notices for Volto 18 + +#### `@plone/generator-volto` + +```{deprecated} Volto 18.0.0 +``` + +The Node.js-based Volto project boilerplate generator is deprecated from Volto 18 onwards. +Although you can still migrate your project to Volto 18 using this boilerplate, is recommended that you migrate to use [Cookieplone](https://github.com/plone/cookieplone). +After the release of Volto 18, it will be marked as deprecated, archived, and it won't receive any further updates. + +##### Alternative + +Migrate your project to use a [Cookieplone](https://github.com/plone/cookieplone) boilerplate. + +#### Volto project configurations + +```{deprecated} Volto 18.0.0 +``` + +It's been a while that you can configure Volto using an add-on. +The "project" way, so you configure Volto using `src/config.js` in your project is deprecated and will be removed in Volto 19. + +https://github.com/plone/volto/issues/6396 + +##### Alternative + +It's recommended and hevily encouraged that you do all your project configuration in a policy add-on. +You can move your project to use [Cookieplone](https://github.com/plone/cookieplone) which provide the necessary boilerplate for it. + +#### SemanticUI + +```{deprecated} Volto 18.0.0 +``` + +SemanticUI library is not maintained anymore and will be removed in Plone 7. +Any usage in add-ons and projects is discouraged and not recommended. + +Related PLIPs: + +- https://github.com/plone/volto/issues/6321 +- https://github.com/plone/volto/issues/6323 + +##### Alternatives + +Use any supported component framework of your choice for implementing new components, specially in the public theme side. +In the case that you create new widgets or components for use them in the CMSUI (non-public side) it is recommended that you use [`@plone/components`](https://github.com/plone/volto/tree/main/packages/components) library as an alternative, although it's still in development phase and has still to be finished in the next months. + +#### `lodash` library + +```{deprecated} Volto 18.0.0 +``` + +`lodash` has not received any updates since 2021 which makes it kind of concerning too in terms of future maintainability. +Lots of `lodash` utility helpers can be replaced nowadays by vanilla ES. It is decided that will be removed from Plone 7 since it has performance issues (bloated bundles) and it's not prepared for ESM. +Plone 7 will use the `lodash-es` library (ESM ready) instead and it will be replaced by modern vanilla ES alternatives whenever possible. + +##### Alternatives + +The usage of `lodash` is becoming not necessary, since over time vanilla JS/ES features has make them obsolete. +Take a look at this URL to check if you have better alternatives every time that you want to use `lodash`: + +https://github.com/you-dont-need/You-Dont-Need-Lodash-Underscore +https://javascript.plainenglish.io/you-dont-need-lodash-how-i-gave-up-lodash-693c8b96a07c + +If you still need some of its utilities you can use `lodash-es` instead. + +#### `@loadable/component` and Volto `Loadables` framework + +```{deprecated} Volto 18.0.0 +``` + +`@loadable/component` and Volto `Loadables` framework will be removed from Plone 7 because it's a Webpack only library and it does not have Vite plugin support. +Overall, from React 18 this library is not necessary since it has the initial implementation of the "concurrent mode". +React 19 will improve even add more the features around it. + +##### Alternatives + +The recommendation is to use plain React 18 lazy load features and its idiom for lazy load components. + +```jsx +const myLazyComponent = lazy(()=> import('@plone/volto/components/theme/MyLazyComponent/MyLazyComponent')) + +const RandomComponent = (props) => ( + + + +) +``` + +There's no support for pre-loading or lazy load entire libraries as in `@loadable/component` but there would not be really necessary anymore, once we get rid of all the barrel imports files (see next deprecation). + +#### Removal of all existing main barrel imports files (`src/components/index.js`, `src/helpers/index.js`, `src/actions/index.js`) + +```{deprecated} Volto 18.0.0 +``` + +Volto had this barrel imports (centralized files where other imports are re-exported in order to improve the developer user experience since the developer only has to remember to import from the re-exported place, not the full path). + +It became a bad practice, since bundlers rely on the import pathway in order to determine if bundle code together or not. +Since the barrel imports direct import all the code, a lot of imports ended up in the same main chunk of code. +Modern bundlers like Vite also use that technique, so it heavily relies on this. +We have to remove the barrel imports in order to increase the natural number of chunks that Volto divides on (specially on routes), and the code splitting is done the right and natural way. + +This will force us to rewrite all the imports everywhere (core, projects and add-ons) once we implement it. + +##### Alternative + +We can start implementing only direct imports in our code right away, preparing for the upcoming change, so we don't have to in the future. + +```diff +-import { BodyClass } from '@plone/volto/helpers'; ++import BodyClass from '@plone/volto/helpers/BodyClass/BodyClass'; +``` + +Once this is implemented, a codemod will be provided to fulfill a smooth migration. + + (volto-upgrade-guide-17.x.x)= ## Upgrading to Volto 17.x.x From 327d684635490668e814ee17b403cf7249ad82fa Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?V=C3=ADctor=20Fern=C3=A1ndez=20de=20Alba?= Date: Wed, 23 Oct 2024 08:47:39 +0200 Subject: [PATCH 2/6] Apply suggestions from code review Co-authored-by: Steve Piercy --- docs/source/upgrade-guide/index.md | 81 +++++++++++++++++++----------- 1 file changed, 51 insertions(+), 30 deletions(-) diff --git a/docs/source/upgrade-guide/index.md b/docs/source/upgrade-guide/index.md index 7aafd2d27f..6c978853b3 100644 --- a/docs/source/upgrade-guide/index.md +++ b/docs/source/upgrade-guide/index.md @@ -530,7 +530,7 @@ Adding the missing `key` property whenever the violation is reported will fix it ``` The Node.js-based Volto project boilerplate generator is deprecated from Volto 18 onwards. -Although you can still migrate your project to Volto 18 using this boilerplate, is recommended that you migrate to use [Cookieplone](https://github.com/plone/cookieplone). +Although you can still migrate your project to Volto 18 using this boilerplate, you should migrate to using [Cookieplone](https://github.com/plone/cookieplone). After the release of Volto 18, it will be marked as deprecated, archived, and it won't receive any further updates. ##### Alternative @@ -543,64 +543,77 @@ Migrate your project to use a [Cookieplone](https://github.com/plone/cookieplone ``` It's been a while that you can configure Volto using an add-on. -The "project" way, so you configure Volto using `src/config.js` in your project is deprecated and will be removed in Volto 19. +The "project" way, where you configure Volto using {file}`src/config.js` in your project, is deprecated in Volto 18, and will be removed in Volto 19. -https://github.com/plone/volto/issues/6396 +```{seealso} +See https://github.com/plone/volto/issues/6396 for details. +``` ##### Alternative -It's recommended and hevily encouraged that you do all your project configuration in a policy add-on. -You can move your project to use [Cookieplone](https://github.com/plone/cookieplone) which provide the necessary boilerplate for it. +You should configure your projects in a policy add-on. +You can move your project to use [Cookieplone](https://github.com/plone/cookieplone) which provides the necessary boilerplate for it. -#### SemanticUI +#### Semantic UI ```{deprecated} Volto 18.0.0 ``` -SemanticUI library is not maintained anymore and will be removed in Plone 7. -Any usage in add-ons and projects is discouraged and not recommended. +The Semantic UI library is not maintained anymore, and will be removed in Plone 7. +You should no longer use Semantic UI in add-ons and projects. +```{seealso} Related PLIPs: - https://github.com/plone/volto/issues/6321 - https://github.com/plone/volto/issues/6323 +``` + ##### Alternatives -Use any supported component framework of your choice for implementing new components, specially in the public theme side. -In the case that you create new widgets or components for use them in the CMSUI (non-public side) it is recommended that you use [`@plone/components`](https://github.com/plone/volto/tree/main/packages/components) library as an alternative, although it's still in development phase and has still to be finished in the next months. +You can use any supported component framework of your choice for implementing new components, especially in the public theme side. +If you create new widgets or components for the CMSUI—in other words, the non-public side—you should use the [`@plone/components`](https://github.com/plone/volto/tree/main/packages/components) library as an alternative. +Even though it's still in the development phase, it will be completed in the next few months, and will be supported in the future. #### `lodash` library ```{deprecated} Volto 18.0.0 ``` -`lodash` has not received any updates since 2021 which makes it kind of concerning too in terms of future maintainability. -Lots of `lodash` utility helpers can be replaced nowadays by vanilla ES. It is decided that will be removed from Plone 7 since it has performance issues (bloated bundles) and it's not prepared for ESM. -Plone 7 will use the `lodash-es` library (ESM ready) instead and it will be replaced by modern vanilla ES alternatives whenever possible. +`lodash` is deprecated in Volto 18, and will be removed in Plone 7. + +`lodash` has not received any updates since 2021. +It has performance issues from bloated bundles and it's not prepared for ESM. +Lots of `lodash` utility helpers can be replaced with vanilla ES. +These issues cause concern about its future maintainability. + +In place of `lodash`, Plone 7 will use both the `lodash-es` library, which is ESM ready, and modern vanilla ES alternatives whenever possible. ##### Alternatives -The usage of `lodash` is becoming not necessary, since over time vanilla JS/ES features has make them obsolete. -Take a look at this URL to check if you have better alternatives every time that you want to use `lodash`: +```{seealso} +The following links suggest alternatives to `lodash`. -https://github.com/you-dont-need/You-Dont-Need-Lodash-Underscore -https://javascript.plainenglish.io/you-dont-need-lodash-how-i-gave-up-lodash-693c8b96a07c +- https://github.com/you-dont-need/You-Dont-Need-Lodash-Underscore +- https://javascript.plainenglish.io/you-dont-need-lodash-how-i-gave-up-lodash-693c8b96a07c -If you still need some of its utilities you can use `lodash-es` instead. +If you still need some of the utilities in `lodash` and cannot use vanilla ES, you can use `lodash-es` instead. +``` #### `@loadable/component` and Volto `Loadables` framework ```{deprecated} Volto 18.0.0 ``` -`@loadable/component` and Volto `Loadables` framework will be removed from Plone 7 because it's a Webpack only library and it does not have Vite plugin support. -Overall, from React 18 this library is not necessary since it has the initial implementation of the "concurrent mode". -React 19 will improve even add more the features around it. +`@loadable/component` and the Volto `Loadables` framework is deprecated in Volto 18, and will be removed from Plone 7. +It's a Webpack-only library, and it does not have Vite plugin support. +Since React 18, this library is no longer necessary, as it has the initial implementation of the "concurrent mode". +React 19 will further improve it and add more features around it. ##### Alternatives -The recommendation is to use plain React 18 lazy load features and its idiom for lazy load components. +Use plain React 18 lazy load features and its idioms for lazy load components. ```jsx const myLazyComponent = lazy(()=> import('@plone/volto/components/theme/MyLazyComponent/MyLazyComponent')) @@ -612,32 +625,40 @@ const RandomComponent = (props) => ( ) ``` -There's no support for pre-loading or lazy load entire libraries as in `@loadable/component` but there would not be really necessary anymore, once we get rid of all the barrel imports files (see next deprecation). +There's no support for pre-loading or lazy loading entire libraries as in `@loadable/component`. +With the removal of barrel imports files, as described in the next deprecation notice, it is now unnecessary. -#### Removal of all existing main barrel imports files (`src/components/index.js`, `src/helpers/index.js`, `src/actions/index.js`) +#### Removal of barrel import files ```{deprecated} Volto 18.0.0 ``` -Volto had this barrel imports (centralized files where other imports are re-exported in order to improve the developer user experience since the developer only has to remember to import from the re-exported place, not the full path). +Volto previously used barrel imports, which are centralized files where other imports are re-exported, to improve the developer user experience. +With barrel imports, a developer only needs to remember to import from the re-exported place, not the full path. -It became a bad practice, since bundlers rely on the import pathway in order to determine if bundle code together or not. +It became a bad practice, because bundlers rely upon the import path to determine whether to bundle code together or not. Since the barrel imports direct import all the code, a lot of imports ended up in the same main chunk of code. Modern bundlers like Vite also use that technique, so it heavily relies on this. -We have to remove the barrel imports in order to increase the natural number of chunks that Volto divides on (specially on routes), and the code splitting is done the right and natural way. +The barrel imports must be removed to increase the natural number of chunks that Volto divides on—especially on routes—resulting in code splitting done the right and natural way. + +This forces us to rewrite all the imports everywhere—including core, projects, and add-ons—once we implement it. + +The barrel imports files include the following. -This will force us to rewrite all the imports everywhere (core, projects and add-ons) once we implement it. +- {file}`src/components/index.js` +- {file}`src/helpers/index.js` +- {file}`src/actions/index.js` ##### Alternative -We can start implementing only direct imports in our code right away, preparing for the upcoming change, so we don't have to in the future. +Implement only direct imports in code, preparing now for the upcoming change. ```diff -import { BodyClass } from '@plone/volto/helpers'; +import BodyClass from '@plone/volto/helpers/BodyClass/BodyClass'; ``` -Once this is implemented, a codemod will be provided to fulfill a smooth migration. +Once this is implemented, a code modification will be provided for a smooth migration. (volto-upgrade-guide-17.x.x)= From 21dcec172c1b72dbf3298b13b3ab142a31e1d274 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?V=C3=ADctor=20Fern=C3=A1ndez=20de=20Alba?= Date: Fri, 25 Oct 2024 09:27:09 +0200 Subject: [PATCH 3/6] Apply suggestions from code review Co-authored-by: David Glick --- docs/source/upgrade-guide/index.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/source/upgrade-guide/index.md b/docs/source/upgrade-guide/index.md index 6c978853b3..8070cb8d2b 100644 --- a/docs/source/upgrade-guide/index.md +++ b/docs/source/upgrade-guide/index.md @@ -530,8 +530,8 @@ Adding the missing `key` property whenever the violation is reported will fix it ``` The Node.js-based Volto project boilerplate generator is deprecated from Volto 18 onwards. -Although you can still migrate your project to Volto 18 using this boilerplate, you should migrate to using [Cookieplone](https://github.com/plone/cookieplone). After the release of Volto 18, it will be marked as deprecated, archived, and it won't receive any further updates. +Although you can still migrate your project to Volto 18 using this boilerplate, you should migrate to using [Cookieplone](https://github.com/plone/cookieplone). ##### Alternative @@ -542,8 +542,7 @@ Migrate your project to use a [Cookieplone](https://github.com/plone/cookieplone ```{deprecated} Volto 18.0.0 ``` -It's been a while that you can configure Volto using an add-on. -The "project" way, where you configure Volto using {file}`src/config.js` in your project, is deprecated in Volto 18, and will be removed in Volto 19. +Configuring Volto using {file}`src/config.js` at the project level is deprecated in Volto 18, and will be removed in Volto 19. ```{seealso} See https://github.com/plone/volto/issues/6396 for details. From 08ac48d351e9c8b9e5378284263a3ef60a656468 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sat, 26 Oct 2024 03:00:12 -0700 Subject: [PATCH 4/6] Apply suggestions from code review --- docs/source/upgrade-guide/index.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/source/upgrade-guide/index.md b/docs/source/upgrade-guide/index.md index 8070cb8d2b..1dd69b4daa 100644 --- a/docs/source/upgrade-guide/index.md +++ b/docs/source/upgrade-guide/index.md @@ -566,7 +566,6 @@ Related PLIPs: - https://github.com/plone/volto/issues/6321 - https://github.com/plone/volto/issues/6323 - ``` ##### Alternatives @@ -635,9 +634,10 @@ With the removal of barrel imports files, as described in the next deprecation n Volto previously used barrel imports, which are centralized files where other imports are re-exported, to improve the developer user experience. With barrel imports, a developer only needs to remember to import from the re-exported place, not the full path. -It became a bad practice, because bundlers rely upon the import path to determine whether to bundle code together or not. -Since the barrel imports direct import all the code, a lot of imports ended up in the same main chunk of code. -Modern bundlers like Vite also use that technique, so it heavily relies on this. +Since the barrel imports directly import all the code, a lot of imports ended up in the same main chunk of code. +It became a bad practice. +Modern bundlers, such as Vite, rely upon the import path to determine whether to bundle code together or not, reducing the bundle size. + The barrel imports must be removed to increase the natural number of chunks that Volto divides on—especially on routes—resulting in code splitting done the right and natural way. This forces us to rewrite all the imports everywhere—including core, projects, and add-ons—once we implement it. From ab80c306c2cf0497f42f544ffb8588e605da3f84 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sat, 26 Oct 2024 03:02:00 -0700 Subject: [PATCH 5/6] Apply suggestions from code review --- docs/source/upgrade-guide/index.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/source/upgrade-guide/index.md b/docs/source/upgrade-guide/index.md index 1dd69b4daa..f1773a54ab 100644 --- a/docs/source/upgrade-guide/index.md +++ b/docs/source/upgrade-guide/index.md @@ -639,9 +639,7 @@ It became a bad practice. Modern bundlers, such as Vite, rely upon the import path to determine whether to bundle code together or not, reducing the bundle size. The barrel imports must be removed to increase the natural number of chunks that Volto divides on—especially on routes—resulting in code splitting done the right and natural way. - This forces us to rewrite all the imports everywhere—including core, projects, and add-ons—once we implement it. - The barrel imports files include the following. - {file}`src/components/index.js` From 5b84981c0daf799c304f07956c96fbe8d09e956b Mon Sep 17 00:00:00 2001 From: Victor Fernandez de Alba Date: Sat, 26 Oct 2024 12:27:43 +0200 Subject: [PATCH 6/6] Changelog --- packages/volto/news/6426.documentation | 1 + 1 file changed, 1 insertion(+) create mode 100644 packages/volto/news/6426.documentation diff --git a/packages/volto/news/6426.documentation b/packages/volto/news/6426.documentation new file mode 100644 index 0000000000..dc5079729a --- /dev/null +++ b/packages/volto/news/6426.documentation @@ -0,0 +1 @@ +Added deprecation notices to the upgrade guide for Volto 18. @sneridagh