Amend version policy docs #6541
Conversation
✅ Deploy Preview for plone-components canceled.
|
There was a problem hiding this comment.
We need to remove the copy of this file from the documentation repo, and refer to this include instead, in a separate PR.
There was a problem hiding this comment.
Can we do that, from another repo?
There was a problem hiding this comment.
Example. Adjust relative paths as needed.
In Volto docs.
```{include} ../_inc/_install-operating-system.md
```
In documentation.
```{include} ../../volto/_inc/_install-operating-system.md
```
IOW, when you use the include in Volto, then you can refer to it in documentation, after it gets merged in a PR, of course. You cannot go the reverse direction.
There was a problem hiding this comment.
Done. Removed the local inc.
There was a problem hiding this comment.
That's not what I meant. Please read my original statement. The separate PR would be in Documentation.
There was a problem hiding this comment.
but the original is in docs already.
There was a problem hiding this comment.
We need to remove the copy of this file from the documentation repo
The docs in Volto have no idea that plone/documentation exists with regard to includes. Please restore the file /_inc/_install-operating-system.md here, restore the include directive, and we will delete the original from plone/documentation.
You can verify this by trying to build docs locally.
Co-authored-by: Steve Piercy <[email protected]>
| Any new feature will be merged into the `main` branch, and only backported to and released in older versions, if the Volto Team approves it. | ||
|
|
||
| `17.x.x` | ||
| : `17.x.x` is no longer supported and became legacy when Volto 18 was released. |
There was a problem hiding this comment.
I wonder if we should say something more for 17.x.x? For example, let's say I have a project with Plone 6.0 and Volto 17. What should I do? Should I upgrade both Plone to 6.1 and Volto to 18? If so, then we need to also link directly to each upgrade guide.
| : `17.x.x` is no longer supported and became legacy when Volto 18 was released. | |
| : `17.x.x` is no longer supported and became _legacy_ (see above definition) when Volto 18 was released. |
Note that we can't use a label in an include file that is used in multiple places in Sphinx (duplicate label warning), so we have to write "(see above definition)".
There was a problem hiding this comment.
It's not mandatory to upgrade. It can get some updates, if people still care for it, and the Volto Team approve them.
There was a problem hiding this comment.
@sneridagh Steve's right, if we're saying it's no longer supported, we need to give some advice on how to move forward.
It's possible to upgrade to Volto 18 (i.e. by generating a new cookieplone project and moving your custom code over) without updating the backend to Plone 6.1.
There was a problem hiding this comment.
I edited my suggestion to adapt to the new "legacy" term.
| Semantic UI development and maintenance has sputtered since 2018. | ||
| The Volto Team made the decision to move forward in a sustainable direction. | ||
| Plone 7 will use a different theming approach, based on the [`@plone/components`](https://www.npmjs.com/package/@plone/components)—which in turn is based on [React Aria Components](https://react-spectrum.adobe.com/react-aria/components.html)—and [`@plone/theming`](https://github.com/plone/volto/tree/main/packages/theming) packages. | ||
| Using Semantic UI theming for your project or add-on is deprecated from Volto 18 onward, and will be removed in Plone 7. |
There was a problem hiding this comment.
As a side note, after seeing all the added admonitions in theming docs regarding Semantic UI, where would I look now for theming docs for the new way of theming? We should include that in the admonition, too.
There was a problem hiding this comment.
Nowhere to look yet. We should start sending the message: "Whatever you use for theming your site, but SemanticUI, is fine. You can continue using it if you want, but core will abandon it in Plone 7."
There was a problem hiding this comment.
I completed the info on 17.x.x
There was a problem hiding this comment.
That's not what I meant. Please read my original statement. The separate PR would be in Documentation.
There was a problem hiding this comment.
Let's rename it to _semantic-ui-deprecation.md because there is a space in its official brand name.
Co-authored-by: Steve Piercy <[email protected]>
| : `17.x.x` is no longer supported and became legacy when Volto 18 was released. | ||
| It won't receive any bug fixes nor security updates. | ||
| It is recommended that you update to 18.x.x. | ||
| If you need a bug fix or security update for this version, please submit a pull request, and the Volto Team will review it to determine whether it's suitable to merge. |
There was a problem hiding this comment.
This seems to contradict line 41.
There was a problem hiding this comment.
I'm adding a "legacy" entry at the top of the document to clarify it.
There was a problem hiding this comment.
We shouldn't tell people to submit security issues or pull requests publicly. It should go through [email protected], unless I'm totally off about that. True story, I once got slapped for creating an issue stating that a Plone repo's primary branch lacked branch protection, even though it was stated publicly on the repo's home page.
Also I think we should tell people to create an issue to discuss a bug fix with the Volto Team before doing any work with a pull request.
| If you need a bug fix or security update for this version, please submit a pull request, and the Volto Team will review it to determine whether it's suitable to merge. | |
| If you need a bug fix, please create an issue to discuss with the Volto Team. | |
| For security issues, please contact the Plone Security Team by sending email to [email protected]. |
| @@ -0,0 +1,6 @@ | |||
| ```{deprecated} Volto 18 | |||
| Semantic UI development and maintenance has sputtered since 2018. | |||
There was a problem hiding this comment.
| Semantic UI development and maintenance has sputtered since 2018. | |
| Semantic UI development and maintenance has been inconsistent since 2018. |
| ```{deprecated} Volto 18.0.0 | ||
| `@plone/volto-generator` was deprecated in Volto 18.0.0. | ||
| It is not maintained, and you should not use it. | ||
| For new projects, use [Cookieplone](https://github.com/plone/cookieplone) instead. |
There was a problem hiding this comment.
We should link to https://6.docs.plone.org/install/create-project-cookieplone.html here, not the Cookieplone repository.
There was a problem hiding this comment.
The whole sentence needs a rewrite. This syntax should work via Intersphinx for both here and plone/documentation.
| For new projects, use [Cookieplone](https://github.com/plone/cookieplone) instead. | |
| For new projects, follow {doc}`plone:install/create-project-cookieplone` instead. |
=>
For new projects, follow Install Plone with Cookieplone instead.
| ``` | ||
|
|
||
| `@plone/volto-generator` is a tool that generates a Volto project. | ||
| The following table describes the compatibility between versions of `@plone/volto-generator` and Volto. | ||
|
|
||
| | Generator version | Volto version | | ||
| |-------------------|---------------| |
There was a problem hiding this comment.
The next line makes it sound like it's still supported for Volto 18, we need to change that.
There was a problem hiding this comment.
Does it work in 18? I assumed that if something works, then that means it's supported.
Also if something works, it can also be deprecated.
There was a problem hiding this comment.
No, we started to update it for Volto 18 but then realized we needed to create Cookieplone instead, because the structure was too different.
There was a problem hiding this comment.
Since it doesn't work in 18, then why do we even have it in 18? https://github.com/plone/volto/tree/main/packages/generator-volto
There was a problem hiding this comment.
"It does work" but it's true that maybe we should not advertise it, it could be confusing.
There was a problem hiding this comment.
The version of @plone/volto-generator for Volto 18 was created quite early in the process of developing Volto 18, and it hasn't really gotten much attention as further changes have happened after we switched to recommending cookieplone. It doesn't surprise me that it's not working fully, and I don't think it's worth a lot of effort to fix it. We need to update trainings to use cookieplone or be clear that they are for an older version of Volto.
@wesleybl There's a new structure for Volto 18, and there's no longer a distinction between an app and an addon. (Similar to how in the backend a project and an addon are both just Python packages.) Use the project template in cookieplone if you want to generate both a backend and a frontend, or the frontend_addon template if you only want to generate a frontend (for use with an existing backend).
There was a problem hiding this comment.
@sneridagh this came up in #6528 (comment).
There was a problem hiding this comment.
@davisagli do we also need to update these items in the upgrade guide? The first implies it's all good, especially when the second says it really ain't.
There was a problem hiding this comment.
Use the project template in cookieplone if you want to generate both a backend and a frontend, or the frontend_addon template if you only want to generate a frontend (for use with an existing backend).
@davisagli I have some considerations about this. I think there should be an app template. However, I believe this is not the place to discuss it. I’ll create an issue in the cookieplone repository.
There was a problem hiding this comment.
If @plone/volto-generator doesn't work 100% with Volto 18, I also think it should be removed from the compatibility table.
Co-authored-by: David Glick <[email protected]> Co-authored-by: Steve Piercy <[email protected]>
…larify what legacy means.
| legacy | ||
| : The term _legacy_ refers to a version that is no longer supported or actively maintained. | ||
| They are the versions between official Plone minor releases. | ||
| It is recommended that you update to minor Plone releases as soon as possible. |
There was a problem hiding this comment.
| It is recommended that you update to minor Plone releases as soon as possible. | |
| You should update to minor Plone releases as soon as possible. |
| : The term _legacy_ refers to a version that is no longer supported or actively maintained. | ||
| They are the versions between official Plone minor releases. | ||
| It is recommended that you update to minor Plone releases as soon as possible. | ||
| They won't receive any new features. |
There was a problem hiding this comment.
| They won't receive any new features. | |
| Legacy versions won't receive any new features. |
| They are the versions between official Plone minor releases. | ||
| It is recommended that you update to minor Plone releases as soon as possible. | ||
| They won't receive any new features. | ||
| They might receive occasional bugfixes or security updates, via a pull request, and it's approved by the Volto Team. |
There was a problem hiding this comment.
This legacy section is a good addition.
| They might receive occasional bugfixes or security updates, via a pull request, and it's approved by the Volto Team. | |
| They might receive occasional bug fixes or security updates, subject to approval from the Volto Team. |
| Any new feature will be merged into the `main` branch, and only backported to and released in older versions, if the Volto Team approves it. | ||
|
|
||
| `17.x.x` | ||
| : `17.x.x` is no longer supported and became legacy when Volto 18 was released. | ||
| It is recommended that you update to 18.x.x. |
There was a problem hiding this comment.
The second sentence in my suggestion below was omitted from the Upgrade Guide https://6.docs.plone.org/volto/upgrade-guide/index.html#cookieplone-is-now-the-recommended-project-and-add-on-generator-for-volto-18. Should we add it there as well?
| It is recommended that you update to 18.x.x. | |
| You should upgrade to the latest released version of Volto 18. | |
| You can use Cookieplone to generate a new Volto 18 project, then copy-paste over the relevant parts from your existing project into the new one. | |
| See {ref}`volto-upgrade-guide-18.x.x`. |
| Any new feature will be merged into the `main` branch, and only backported to and released in older versions, if the Volto Team approves it. | ||
|
|
||
| `17.x.x` | ||
| : `17.x.x` is no longer supported and became legacy when Volto 18 was released. |
There was a problem hiding this comment.
I edited my suggestion to adapt to the new "legacy" term.
| : `17.x.x` is no longer supported and became legacy when Volto 18 was released. | ||
| It won't receive any bug fixes nor security updates. | ||
| It is recommended that you update to 18.x.x. | ||
| If you need a bug fix or security update for this version, please submit a pull request, and the Volto Team will review it to determine whether it's suitable to merge. |
There was a problem hiding this comment.
We shouldn't tell people to submit security issues or pull requests publicly. It should go through [email protected], unless I'm totally off about that. True story, I once got slapped for creating an issue stating that a Plone repo's primary branch lacked branch protection, even though it was stated publicly on the repo's home page.
Also I think we should tell people to create an issue to discuss a bug fix with the Volto Team before doing any work with a pull request.
| If you need a bug fix or security update for this version, please submit a pull request, and the Volto Team will review it to determine whether it's suitable to merge. | |
| If you need a bug fix, please create an issue to discuss with the Volto Team. | |
| For security issues, please contact the Plone Security Team by sending email to [email protected]. |
| ``` | ||
|
|
||
| `@plone/volto-generator` is a tool that generates a Volto project. | ||
| The following table describes the compatibility between versions of `@plone/volto-generator` and Volto. | ||
|
|
||
| | Generator version | Volto version | | ||
| |-------------------|---------------| |
There was a problem hiding this comment.
@davisagli do we also need to update these items in the upgrade guide? The first implies it's all good, especially when the second says it really ain't.
| @@ -11,6 +11,9 @@ myst: | |||
|
|
|||
| ## Semantic UI | |||
|
|
|||
| ```{include} /_inc/_semanticui-deprecation.md | |||
There was a problem hiding this comment.
Always check your local build, or at least verify on RTD previews https://volto--6541.org.readthedocs.build/theming/custom-styling.html.
All includes must be relative to the current file, not the documentation root, else it will break in the main documentation. Please update the others.
| ```{include} /_inc/_semanticui-deprecation.md | |
| ```{include} ../_inc/_semantic-ui-deprecation.md |
| @@ -0,0 +1,2 @@ | |||
| Amended version-policy docs. @sneridagh | |||
There was a problem hiding this comment.
| Amended version-policy docs. @sneridagh | |
| Amended version policy documentation. @sneridagh |
For 5.2, do not mention 3.6 and 3.7 in this table. They are long end of life.
First draft
📚 Documentation preview 📚: https://volto--6541.org.readthedocs.build/