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 all 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
18 changes: 15 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 @@ -13,6 +13,13 @@ canary
During the development process, a canary release will be cut from the `main` branch.
When it becomes worthy of a beta or release candidate version, a new numbered branch should be cut, and non-breaking changes must be merged into it.

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

`main`
: This is the bleeding edge branch in git.
It is the branch upon which future development occurs, and from which future releases shall be cut.
Expand All @@ -31,11 +38,16 @@ 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

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.

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


`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 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, follow {doc}`plone:install/create-project-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
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 +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.

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

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
Added deprecation notice for Semantic UI theming.
Loading