Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Amend version policy docs #6541

Open
wants to merge 12 commits into
base: main
Choose a base branch
from
Open

Amend version policy docs #6541

Show file tree
Hide file tree
Changes from 9 commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
10459fd
First version
sneridagh Dec 14, 2024
1cfe19c
Deprecation warning for SemanticUI theming.
sneridagh Dec 14, 2024
1a3ddef
Changelog
sneridagh Dec 14, 2024
7d0d06d
Apply suggestions from code review
sneridagh Dec 15, 2024
8dc2ab7
Add reference to Plone 6.1 and the release schedule page. Remove conf…
sneridagh Dec 16, 2024
3bb6191
Use an inc for the SemanticUI notice, move under titles
sneridagh Dec 16, 2024
097dda6
Apply suggestions from code review
sneridagh Dec 16, 2024
23723b9
Rename _semantic-ui-deprecation.md
sneridagh Dec 16, 2024
99292c6
Complete what legacy means
sneridagh Dec 16, 2024
3b84aca
Apply suggestions from code review
sneridagh Dec 17, 2024
427e449
Remove contradicting statement in 17.x.x branch, create an entry to c…
sneridagh Dec 17, 2024
50f1b39
Plone 6.0.14 and 6.1.0b2 support Python 3.13.
mauritsvanrees Dec 20, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 9 additions & 3 deletions docs/source/_inc/_branch-policy.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,11 +31,17 @@ canary

If the pull request is a feature or a bugfix, and if the release manager deems it useful to the latest version's branch, they may ask you to backport it to that branch.

`17.x.x`
: `17.x.x` is the current stable and actively developed branch in git.
Upon the final release of version `18.0.0`, the `17.x.x` branch line will be no longer supported.
`18.x.x`
: `18.x.x` is the current stable and actively developed branch in git.
stevepiercy marked this conversation as resolved.
Show resolved Hide resolved
This version of Volto has the [same maintenance and support schedule as Plone 6.1](https://plone.org/download/release-schedule).
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.
Copy link
Collaborator

@stevepiercy stevepiercy Dec 15, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Suggested change
: `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)".

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's not mandatory to upgrade. It can get some updates, if people still care for it, and the Volto Team approve them.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@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.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I edited my suggestion to adapt to the new "legacy" term.

It won't receive any bug fixes nor security updates.
It is recommended that you update to 18.x.x.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

Suggested change
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`.

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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This seems to contradict line 41.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm adding a "legacy" entry at the top of the document to clarify it.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Suggested change
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].


`16.x.x`
: This version of Volto has the [same maintenance and support schedule as Plone 6.0](https://plone.org/download/release-schedule).
It receives bug fixes and security updates.
Expand Down
6 changes: 6 additions & 0 deletions docs/source/_inc/_semantic-ui-deprecation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
```{deprecated} Volto 18
Semantic UI development and maintenance has sputtered since 2018.
Copy link
Member

@davisagli davisagli Dec 16, 2024 •
edited by stevepiercy
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Semantic UI development and maintenance has sputtered since 2018.
Semantic UI development and maintenance has been inconsistent 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.
```
36 changes: 23 additions & 13 deletions docs/source/contributing/version-policy.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,10 +16,16 @@ This chapter describes the versions of software that Volto supports and how Volt

(volto-generator-compatibility-with-volto-label)=

## `volto-generator` compatibility with Volto
## `@plone/volto-generator` compatibility with Volto

`volto-generator` is a tool that generates a Volto project.
The following table describes the compatibility between versions of `volto-generator` and Volto.
```{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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should link to https://6.docs.plone.org/install/create-project-cookieplone.html here, not the Cookieplone repository.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The whole sentence needs a rewrite. This syntax should work via Intersphinx for both here and plone/documentation.

Suggested change
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 |
|-------------------|---------------|
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The next line makes it sound like it's still supported for Volto 18, we need to change that.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No, we started to update it for Volto 18 but then realized we needed to create Cookieplone instead, because the structure was too different.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"It does work" but it's true that maybe we should not advertise it, it could be confusing.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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).

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@sneridagh this came up in #6528 (comment).

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@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.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If @plone/volto-generator doesn't work 100% with Volto 18, I also think it should be removed from the compatibility table.

Expand All @@ -40,10 +46,11 @@ We will always support the [latest major Plone release](https://plone.org/downlo

The versions of Python that are supported in Volto depend on the version of Plone that you use.

| Plone | Python | Volto |
| ----- | ------------ | ------------ |
| 6.0 | 3.8-3.11 | 16.0 or 17.0 |
| 5.2 | 2.7, 3.6-3.8 | 15.0 |
| Plone | Python | Volto |
| ----- | ------------ | ---------------- |
| 6.1 | 3.10-3.12 | 18.0.0 |
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Awaiting response to my question in plone/Products.CMFPlone#3926 (comment) for Python 3.13 support. We can amend later, too.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Amend it later. Python 3.13 support is close, but not released yet.

Copy link
Collaborator

@stevepiercy stevepiercy Dec 17, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I added a couple of comments in the release checklists just now, so we don't forget.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have released 6.0.14 and 6.1.0b2 with Python 3.13 support. I have added commit 50f1b39 to this PR to reflect this.

| 6.0 | 3.8-3.12 | 16.0.0 or 17.0.0 |
| 5.2 | 2.7, 3.6-3.8 | 15.0.0 |
stevepiercy marked this conversation as resolved.
Show resolved Hide resolved

On Plone 6, we recommend using the known good set (KGS) of package versions that are specified in the Plone release.

Expand Down Expand Up @@ -72,8 +79,12 @@ Volto runs using [Node.js](https://nodejs.org/en).
Volto supports only the latest two [LTS versions of Node.js](https://github.com/nodejs/release#release-schedule).
We recommend using the current LTS version.

- Node.js 22 LTS: Supported since Volto 18.
- Node.js 20 LTS: Supported since Volto 17.
| Node.js | Volto |
| ------- | ----------- |
| 20, 22 | Volto 18 |
| 18, 20 | Volto 17 |
| 16, 18 | Volto 16 |

- Node.js 18: No longer supported. It was supported in Volto 16 - 17.
- Node.js 16: No longer supported. It was supported in Volto 14 - 16.
- Node.js 14: No longer supported. It was supported in Volto 8.8.0 - 16.
Expand All @@ -83,11 +94,10 @@ We recommend using the current LTS version.

(version-policy-supported-browsers)=

## Supported browsers
## Supported web browsers

Volto works well with the current version of any modern browser—including Chrome, Firefox, Safari, and Edge—as well as their mobile flavors.

We do not guarantee that outdated browsers, such as Internet Explorer 11, are supported by Volto.
```{include} ../../_inc/_install-browser-reqs-volto.md
```


## Branch policy
Expand Down
3 changes: 3 additions & 0 deletions docs/source/theming/about-semantic.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,9 @@ myst:

# About Semantic UI

```{include} ../_inc/_semantic-ui-deprecation.md
```

Volto uses [Semantic UI](https://semantic-ui.com/) and
[React Semantic UI](https://react.semantic-ui.com)
(via [semantic-ui-less](https://github.com/Semantic-Org/Semantic-UI-LESS))
Expand Down
3 changes: 3 additions & 0 deletions docs/source/theming/custom-styling.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,9 @@ myst:

## Semantic UI

```{include} /_inc/_semanticui-deprecation.md
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Suggested change
```{include} /_inc/_semanticui-deprecation.md
```{include} ../_inc/_semantic-ui-deprecation.md

```

For styling our website in Volto we use Semantic UI. It uses LESS as
the underlying technology. By default Volto uses the Pastanaga theme but any
theme can be used. A theme has the following folder structure:
Expand Down
2 changes: 2 additions & 0 deletions docs/source/theming/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,8 @@ myst:

This section of the documentation describes theming in Volto.

```{include} /_inc/_semanticui-deprecation.md
```

## Conceptual guides

Expand Down
3 changes: 3 additions & 0 deletions docs/source/theming/semanticui-theming.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,9 @@ myst:

# Semantic UI Theming

```{include} /_inc/_semanticui-deprecation.md
```

As we hinted previously, Semantic UI theming happens in several stages using several layers of inheritance.
Let's discover each of these layers.

Expand Down
3 changes: 3 additions & 0 deletions docs/source/theming/theming-engine.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,9 @@ myst:

# How does the theming engine work?

```{include} /_inc/_semanticui-deprecation.md
```

It basically uses heavily the LESS precompiler language features. No code is involved (which is good).

## `theme.config`
Expand Down
3 changes: 3 additions & 0 deletions docs/source/theming/theming-strategy.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,9 @@ myst:

# Theming Strategy

```{include} /_inc/_semanticui-deprecation.md
```

One approaches the theming of a Volto site usually with a predefined mockup or
design from a design agency or an UX/UI designer in the form of Sketch files
(a common design and prototyping tool), a series of photoshop or PDFs with the
Expand Down
2 changes: 2 additions & 0 deletions packages/volto/news/6541.documentation
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
Amended version-policy docs. @sneridagh
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Amended version-policy docs. @sneridagh
Amended version policy documentation. @sneridagh

Added deprecation notice for Semantic UI theming.
Loading