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 3 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
9 changes: 6 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,14 @@ 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
Upon the final release of version `19.0.0`, the `18.x.x` branch line will be no longer supported.
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.


`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
10 changes: 10 additions & 0 deletions docs/source/_inc/_install-browser-reqs-volto.md
View file
Open in desktop
Copy link
Collaborator

Choose a reason for hiding this comment

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

We need to remove the copy of this file from the documentation repo, and refer to this include instead, in a separate PR.

Copy link
Member Author

Choose a reason for hiding this comment

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

Can we do that, from another repo?

Copy link
Collaborator

Choose a reason for hiding this comment

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

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.

Copy link
Member Author

Choose a reason for hiding this comment

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

Done. Removed the local inc.

Copy link
Collaborator

Choose a reason for hiding this comment

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

That's not what I meant. Please read my original statement. The separate PR would be in Documentation.

Copy link
Member Author

Choose a reason for hiding this comment

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

but the original is in docs already.

Copy link
Collaborator

Choose a reason for hiding this comment

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

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.

Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
You can view the list of supported browsers for Volto at [Browserslist](https://browsersl.ist/#q=%3E1%25%0Alast+4+versions%0AFirefox+ESR%0Anot+dead).

These browsers are set according to the `browserslist` key in Volto's [`package.json`](https://github.com/plone/volto/blob/1aff8d0451f5cb375ca9f5afe9b2b72a0555afd8/packages/volto/package.json#L170-L176) file, whose content is below.

```shell
>1%
last 4 versions
Firefox ESR
not dead
```
36 changes: 25 additions & 11 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,18 @@ 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

sneridagh marked this conversation as resolved.
Show resolved Hide resolved
```{important}
sneridagh marked this conversation as resolved.
Show resolved Hide resolved
`@plone/volto-generator` is deprecated, unmaintaned, and its usage is discouraged from Volto 18.0.0.
sneridagh marked this conversation as resolved.
Show resolved Hide resolved
For new projects, please use [Cookieplone](https://github.com/plone/cookieplone) instead.
sneridagh marked this conversation as resolved.
Show resolved Hide resolved
In case of having an existing project and you need to upgrade to Volto 18 but don't have time to migrate to use Cookieplone, you can still use it.
Copy link
Collaborator

Choose a reason for hiding this comment

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

This sentence is not clear, specifically "you can still use it" where "it" can mean Cookieplone, volto-generator, or Volto 18.

Cookieplone does not support Volto 17, so it's even more confusing.

Copy link
Member Author

Choose a reason for hiding this comment

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

Removing, as it might be confusing.

```

`@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 +48,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.11 | 16.0.0 or 17.0.0 |
sneridagh marked this conversation as resolved.
Show resolved Hide resolved
| 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,6 +81,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 | Volto |
| ------- | ----------- |
| 20, 22 | Volto 18 |
| 18, 20 | Volto 17 |
| 16, 18 | Volto 16 |

- Node.js 22 LTS: Supported since Volto 18.
sneridagh marked this conversation as resolved.
Show resolved Hide resolved
- Node.js 20 LTS: Supported since Volto 17.
sneridagh marked this conversation as resolved.
Show resolved Hide resolved
- Node.js 18: No longer supported. It was supported in Volto 16 - 17.
Expand All @@ -83,11 +98,10 @@ We recommend using the current LTS version.

(version-policy-supported-browsers)=

## Supported browsers

Volto works well with the current version of any modern browser—including Chrome, Firefox, Safari, and Edge—as well as their mobile flavors.
### Supported web browsers
sneridagh marked this conversation as resolved.
Show resolved Hide resolved

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
5 changes: 5 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,11 @@ myst:

# About Semantic UI

```{deprecated} Volto 18
Using SemanticUI theming for your project or add-on is deprecated from Volto 18 on and will be removed from Plone 7.
sneridagh marked this conversation as resolved.
Show resolved Hide resolved
Plone 7 will use another theming approach, based on `@plone/components` and `@plone/theming` packages.
sneridagh marked this conversation as resolved.
Show resolved Hide resolved
```

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
5 changes: 5 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 @@ -7,6 +7,11 @@ myst:
"keywords": "Volto, Plone, frontend, React, Custom, Styling, Semantic UI, LESS, Pastanaga"
---

```{deprecated} Volto 18
sneridagh marked this conversation as resolved.
Show resolved Hide resolved
Using SemanticUI theming for your project or add-on is deprecated from Volto 18 on and will be removed from Plone 7.
Plone 7 will use another theming approach, based on `@plone/components` and `@plone/theming` packages.
```

# Custom Styling

## Semantic UI
Expand Down
4 changes: 4 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,10 @@ myst:

This section of the documentation describes theming in Volto.

```{deprecated} Volto 18
Using SemanticUI theming for your project or add-on is deprecated from Volto 18 on and will be removed from Plone 7.
Plone 7 will use another theming approach, based on `@plone/components` and `@plone/theming` packages.
```

## Conceptual guides

Expand Down
5 changes: 5 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 @@ -7,6 +7,11 @@ myst:
"keywords": "Volto, Plone, frontend, React, Semantic UI, Theming"
---

```{deprecated} Volto 18
Using SemanticUI theming for your project or add-on is deprecated from Volto 18 on and will be removed from Plone 7.
Plone 7 will use another theming approach, based on `@plone/components` and `@plone/theming` packages.
```

# Semantic UI Theming

As we hinted previously, Semantic UI theming happens in several stages using several layers of inheritance.
Expand Down
5 changes: 5 additions & 0 deletions docs/source/theming/theming-a-base-theme.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,11 @@ myst:
"keywords": "Volto, Plone, frontend, React, themes, Volto Light Theme"
---

```{deprecated} Volto 18
Using SemanticUI theming for your project or add-on is deprecated from Volto 18 on and will be removed from Plone 7.
Plone 7 will use another theming approach, based on `@plone/components` and `@plone/theming` packages.
```

# Customize a base theme

You can customize a base theme for your add-on.
Expand Down
5 changes: 5 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 @@ -7,6 +7,11 @@ myst:
"keywords": "Volto, Plone, frontend, React, theming, engine, LESS"
---

```{deprecated} Volto 18
Using SemanticUI theming for your project or add-on is deprecated from Volto 18 on and will be removed from Plone 7.
Plone 7 will use another theming approach, based on `@plone/components` and `@plone/theming` packages.
```

# How does the theming engine work?

It basically uses heavily the LESS precompiler language features. No code is involved (which is good).
Expand Down
5 changes: 5 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 @@ -7,6 +7,11 @@ myst:
"keywords": "Volto, Plone, frontend, React, Theming, Strategy"
---

```{deprecated} Volto 18
Using SemanticUI theming for your project or add-on is deprecated from Volto 18 on and will be removed from Plone 7.
Plone 7 will use another theming approach, based on `@plone/components` and `@plone/theming` packages.
```

# Theming Strategy

One approaches the theming of a Volto site usually with a predefined mockup or
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 SemanticUI theming.
sneridagh marked this conversation as resolved.
Show resolved Hide resolved
Loading