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 11 commits into
base: main
Choose a base branch
from
+63 −16
Open

Amend version policy docs #6541

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
11 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
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

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 when Volto 18 was released.

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.


`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
```
37 changes: 24 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,17 @@ 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.

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

Well, I just tried it, and it didn't work for me. But it could be that the Training I followed has incorrect information.

Copy link
Member Author

Choose a reason for hiding this comment

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

@stevepiercy there's still an acceptance test for it in place. So it should still work for 18. For project, the add-on template is not being tested. What did you do? That training could be outdated.

Copy link
Collaborator

Choose a reason for hiding this comment

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

I followed the exact instructions published in that training, pretending to be a learner.

Expand All @@ -40,10 +47,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.

| 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,8 +80,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 +95,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
7 changes: 7 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,13 @@ myst:

# About Semantic UI

```{deprecated} Volto 18
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.
Copy link
Collaborator

Choose a reason for hiding this comment

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

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.

Copy link
Member Author

Choose a reason for hiding this comment

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

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

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 completed the info on 17.x.x

```

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
Added deprecation notice for SemanticUI theming.
sneridagh marked this conversation as resolved.
Show resolved Hide resolved
Loading