From bd55f9369b5e2f5ccf248b2f5e6e70f130b38c14 Mon Sep 17 00:00:00 2001 From: Philip Bauer Date: Thu, 28 May 2026 14:23:38 +0200 Subject: [PATCH 1/4] update/fix documentation for installing addons and overriding core-packages in uv-managed projects --- docs/admin-guide/add-ons.md | 50 ++++++++++++++++++---------- docs/admin-guide/override-core.md | 54 +++++++++++++++++++++---------- 2 files changed, 70 insertions(+), 34 deletions(-) diff --git a/docs/admin-guide/add-ons.md b/docs/admin-guide/add-ons.md index eb6f0a7fb0..cbfde3f0a0 100644 --- a/docs/admin-guide/add-ons.md +++ b/docs/admin-guide/add-ons.md @@ -42,11 +42,11 @@ This example adds [`collective.easyform`](https://pypi.org/project/collective.ea ```{code-block} toml :emphasize-lines: 6 dependencies = [ - "Products.CMFPlone==6.1.4", + "Products.CMFPlone==6.2.0", "plone.api", "plone.classicui", "plone.app.caching", - "collective.easyform==4.5.1", + "collective.easyform==5.0.0", ] ``` @@ -81,7 +81,7 @@ eggs = collective.easyform [versions] -collective.easyform = 4.5.1 +collective.easyform = 5.0.0 ``` ```` ````` @@ -147,26 +147,26 @@ Select the tab according to your Python package manager. ```{tip} For projects created with Cookieplone, select the tab labeled: -- {guilabel}`pip` if your project has the file {file}`backend/mx.ini` -- {guilabel}`uv` if your project doesn't have this file +- {guilabel}`uv` if your {file}`pyproject.toml` has the setting `managed = true` in the part `tool.uv`. +- {guilabel}`pip` if your {file}`pyproject.toml` doesn't have this setting ``` `````{tab-set} ````{tab-item} uv :sync: uv -Clone the repository into a local directory. -This example uses [`collective.easyform`](https://pypi.org/project/collective.easyform/). - -```shell -git clone git@github.com:collective/collective.easyform.git -``` - -Add the local directory to your uv project as an editable package. +Add the name of your add-on in the file {file}`backend/pyproject.toml` in the section `dependencies`. +This example adds [`collective.easyform`](https://pypi.org/project/collective.easyform/). -```shell -cd backend -uv add --editable ../collective.easyform +```{code-block} toml +:emphasize-lines: 6 +dependencies = [ + "Products.CMFPlone==6.2.0", + "plone.api", + "plone.classicui", + "plone.app.caching", + "collective.easyform", +] ``` To configure the add-on to load, in the file {file}`backend/instance.yaml`, under the key `default_context`, for the key `zcml_package_includes`, set its value to the add-on's name. @@ -175,6 +175,22 @@ To configure the add-on to load, in the file {file}`backend/instance.yaml`, unde default_context: zcml_package_includes: project_title, collective.easyform ``` + +Finally, add the package's source to the file {file}`mx.ini`. + +```cfg +[collective.easyform] +url=git@github.com:collective/collective.easyform.git +branch=dev-branch-name +extras=test +``` + +When installing the add-on in the next step the add-on will be added as a "editable dependency" in your {file}`pyproject.toml` like this: + +```cfg +[tool.uv.sources] +"collective.easyform" = {path = "sources/collective.easyform", editable = true} +``` ```` ````{tab-item} pip @@ -186,7 +202,7 @@ This example adds [`collective.easyform`](https://pypi.org/project/collective.ea ```{code-block} toml :emphasize-lines: 6 dependencies = [ - "Products.CMFPlone==6.1.4", + "Products.CMFPlone==6.2.0", "plone.api", "plone.classicui", "plone.app.caching", diff --git a/docs/admin-guide/override-core.md b/docs/admin-guide/override-core.md index f428fa841a..625eba547d 100644 --- a/docs/admin-guide/override-core.md +++ b/docs/admin-guide/override-core.md @@ -32,21 +32,22 @@ Select the tab according to your Python package manager. ```{tip} For projects created with Cookieplone, select the tab labeled: -- {guilabel}`pip` if your project has the file {file}`backend/mx.ini` -- {guilabel}`uv` if your project doesn't have this file +- {guilabel}`uv` if your {file}`pyproject.toml` has the setting `managed = true` in the part `tool.uv`. +- {guilabel}`pip` if your {file}`pyproject.toml` doesn't have this setting ``` `````{tab-set} ````{tab-item} uv :sync: uv -In the file {file}`pyproject.toml`, under the table `[tool.uv]`, edit `constraint-dependencies`. +In the file {file}`pyproject.toml`, under the table `[tool.uv]`, add or edit `override-dependencies`. This example uses `plone.api`. -``` +```toml [tool.uv] -constraint-dependencies = [ - "plone.api==2.0.0a3", +managed = True +override-dependencies = [ + "plone.api==3.0.0a3", ] ``` ```` @@ -60,7 +61,7 @@ This example uses `plone.api`. ``` [settings] version-overrides = - plone.api==2.0.0a3 + plone.api==3.0.0a3 ``` ```{seealso} @@ -91,7 +92,7 @@ eggs = Plone [versions] -plone.api = 2.0.0a3 +plone.api = 3.0.0a3 ``` ```{note} @@ -118,31 +119,50 @@ Select the tab according to your Python package manager. ```{tip} For projects created with Cookieplone, select the tab labeled: -- {guilabel}`pip` if your project has the file {file}`backend/mx.ini` -- {guilabel}`uv` if your project doesn't have this file +- {guilabel}`uv` if your {file}`pyproject.toml` has the setting `managed = true` in the part `tool.uv`. +- {guilabel}`pip` if your {file}`pyproject.toml` doesn't have this setting ``` -`````{tab-set} -````{tab-item} uv +``````{tab-set} +`````{tab-item} uv :sync: uv This example uses `plone.restapi`. Clone the repository into a local directory. +add the package's source to the file {file}`mx.ini`. + +```cfg +[plone.restapi] +url=git@github.com:collective/plone.restapi.git +branch=dev-branch-name +extras=test +``` + +When installing the add-on in the next step the add-on will be added as a "editable dependency" in your {file}`pyproject.toml` like this: + +```cfg +[tool.uv.sources] +"plone.restapi" = {path = "sources/plone.restapi", editable = true} +``` +````{tip} +The result is the same as cloning the repository in a local directory... + ```shell git clone git@github.com:plone/plone.restapi.git ``` -Add the local directory to your uv project as an editable package. +...and then adding the local directory to your uv project as an editable package: ```shell cd backend uv add --editable ../plone.restapi ``` ```` +````` -````{tab-item} pip +`````{tab-item} pip :sync: pip Add the Plone package you want to check out in the file {file}`backend/mx.ini`. @@ -159,9 +179,9 @@ extras = test The {file}`mx.ini` file configures a tool called {term}`mxdev`. For an explanation of why Plone uses mxdev, see {ref}`manage-packages-mxdev-label`. ``` -```` +````` -````{tab-item} Buildout +`````{tab-item} Buildout :sync: buildout Update the file {file}`buildout.cfg`. @@ -199,8 +219,8 @@ Setting an empty version ensures that the copy of `plone.restapi` from source co ```{seealso} This approach uses the [`mr.developer`](https://pypi.org/project/mr.developer/) Buildout extension. ``` -```` ````` +`````` ### Install the package From d2f19d450620f133701a069f48ebe0e98c75ac3c Mon Sep 17 00:00:00 2001 From: Philip Bauer Date: Fri, 29 May 2026 12:16:35 +0200 Subject: [PATCH 2/4] Update installation docs for newest cookieplone with unified project template --- docs/install/create-project-cookieplone.md | 410 +++++++-------------- 1 file changed, 134 insertions(+), 276 deletions(-) diff --git a/docs/install/create-project-cookieplone.md b/docs/install/create-project-cookieplone.md index 272c8bf5cc..2064e61be8 100644 --- a/docs/install/create-project-cookieplone.md +++ b/docs/install/create-project-cookieplone.md @@ -31,8 +31,9 @@ Subsequently, support for the Classic UI frontend was added in https://github.co ## Choose a user interface With Cookieplone, you can create projects that use either {term}`Volto` or {term}`Classic UI` as a frontend. -First, choose a Plone frontend, or user interface. +It is a good idea to choose a Plone frontend, or user interface before creating a project. You can read {doc}`/conceptual-guides/choose-user-interface` to help inform your choice between Volto and Classic UI. +You can also create one {term}`Volto` and one {term}`Classic UI` project to test both variants locally before making a final decision. (create-project-cookieplone-system-requirements)= @@ -119,14 +120,9 @@ Node.js is required only for Volto projects and not for Classic UI projects. (create-project-cookieplone-create-volto-project-label)= -## Create a Volto project +## Create a Plone project -This section describes how to install Plone by creating a project with Volto as the frontend. - - -### Generate a Volto project - -After satisfying the prerequisites and having {ref}`activated an LTS version of Node.js `, generate a Volto project. +After satisfying the prerequisites, generate a Plone project. ```shell uvx cookieplone project @@ -134,7 +130,10 @@ uvx cookieplone project You will be presented with a series of prompts. You can accept the default values in square brackets (`[default-option]`) by hitting the {kbd}`Enter` key, or enter your preferred values. -For ease of documentation, we will use the default values. + +For ease of documentation, we will use the default values and thus create a project using the Volto frontend. + +To create a project using the ClassicUI frontend instead answer `No` when asked `Use Volto as frontend (Yes/no)`. ```{tip} See Cookieplone's README for how to [Use options to avoid prompts](https://github.com/plone/cookieplone/?tab=readme-ov-file#use-options-to-avoid-prompts). @@ -146,64 +145,49 @@ Note that pip normalizes these names, so `plone.volto` and `plone-volto` are the ``` ```console -╭──────────────────────────────── cookieplone ────────────────────────────────╮ -│ │ -│ .xxxxxxxxxxxxxx. │ -│ ;xxxxxxxxxxxxxxxxxxxxxx; │ -│ ;xxxxxxxxxxxxxxxxxxxxxxxxxxxx; │ -│ xxxxxxxxxx xxxxxxxxxx │ -│ xxxxxxxx. .xxxxxxxx │ -│ xxxxxxx xxxxxxx: xxxxxxx │ -│ :xxxxxx xxxxxxxxxx xxxxxx: │ -│ :xxxxx+ xxxxxxxxxxx +xxxxx: │ -│ .xxxxx. :xxxxxxxxxx .xxxxx. │ -│ xxxxx+ ;xxxxxxxx +xxxxx │ -│ xxxxx +xx. xxxxx. │ -│ xxxxx: .xxxxxxxx :xxxxx │ -│ xxxxx .xxxxxxxxxx xxxxx │ -│ xxxxx xxxxxxxxxxx xxxxx │ -│ xxxxx .xxxxxxxxxx xxxxx │ -│ xxxxx: .xxxxxxxx :xxxxx │ -│ .xxxxx ;xx. ... xxxxx. │ -│ xxxxx+ :xxxxxxxx +xxxxx │ -│ .xxxxx. :xxxxxxxxxx .xxxxx. │ -│ :xxxxx+ xxxxxxxxxxx ;xxxxx: │ -│ :xxxxxx xxxxxxxxxx xxxxxx: │ -│ xxxxxxx xxxxxxx; xxxxxxx │ -│ xxxxxxxx. .xxxxxxxx │ -│ xxxxxxxxxx xxxxxxxxxx │ -│ ;xxxxxxxxxxxxxxxxxxxxxxxxxxxx+ │ -│ ;xxxxxxxxxxxxxxxxxxxxxx; │ -│ .xxxxxxxxxxxxxx. │ -│ │ -╰─────────────────────────────────────────────────────────────────────────────╯ -You've downloaded /Users/username/.cookiecutters/cookieplone-templates before. -Is it okay to delete and re-download it? [y/n] (y): -╭─────────────────────────────── Plone Project ───────────────────────────────╮ -│ │ -│ Creating a new Plone Project │ -│ │ -│ Sanity check results: │ -│ │ -│ - Cookieplone: ✓ │ -│ - uv: ✓ │ -│ - Node: ✓ │ -│ - git: ✓ │ -│ - Docker (optional): ✓ │ -│ │ -╰─────────────────────────────────────────────────────────────────────────────╯ - [1/19] Project Title (Project Title): - [2/19] Project Description (A new project using Plone 6.): - [3/19] Project Slug (Used for repository id) (project-title): - [4/19] Project URL (without protocol) (project-title.example.com): - [5/19] Author (Plone Foundation): - [6/19] Author E-mail (collective@plone.org): - [7/19] Should we use prerelease versions? (No): - [8/19] Plone Version (6.1.1): - [9/19] Volto Version (18.22.0): - [10/19] Python Package Name (project.title): - [11/19] Volto Addon Name (volto-project-title): - [12/19] Language +╭──────────────────────────── cookieplone (2.0.0a3) ─────────────────────────────╮ +│ │ +│ ******* │ +│ *************** │ +│ *** *** │ +│ *** *** *** │ +│ *** ***** *** │ +│ *** *** *** │ +│ *** *** *** │ +│ *** ***** *** │ +│ *** *** *** *** │ +│ *** ***** *** │ +│ *** *** *** │ +│ *** *** │ +│ *************** │ +│ ******* │ +│ │ +╰───────────────────── Made with ❤️ by the Plone Community ──────────────────────╯ +``` + +``` + [1/20] Project Title (Project Title) + [2/20] Project Description (A new project using Plone 6.): + [3/20] Project Slug (Used for repository id) (project-title): + [4/20] Project URL (without protocol) (project-title.example.com): + [5/20] Author (Plone Foundation): + [6/20] Author E-mail (collective@plone.org): + [7/20] Python Package Name (project.title): + [8/20] Should we use prerelease versions? (yes/No): + [9/20] Plone Version (6.2.0): +``` +The next questions will determine if you will create a Volto or ClassicUI project. +``` + [10/20] Use Volto as frontend (Yes/no): +``` +These two questions are only asked if you choose to create a project using Volto: +``` + [11/20] Volto Version (19.1.0): + [12/20] Volto Addon Name (volto-project-title): +``` +For the remaining questions again we choose the default answer. +``` + [13/20] Language 1 - English 2 - Deutsch 3 - Español @@ -213,74 +197,90 @@ Is it okay to delete and re-download it? [y/n] (y): 7 - Italiano 8 - Svenska Choose from [1/2/3/4/5/6/7/8] (1): - [13/19] GitHub or GitLab username or organization slug from URL (collective): - [14/19] Container Registry + [14/20] GitHub or GitLab username or organization slug from URL (collective): + [15/20] Container Registry 1 - GitHub Container Registry 2 - Docker Hub 3 - GitLab Choose from [1/2/3] (1): - [15/19] Which persistent storage to use in the deployment stack? + [16/20] Which persistent storage to use in the deployment stack? 1 - RelStorage with PostgreSQL (recommended) 2 - ZEO with FileStorage 3 - Local FileStorage, implies a single backend Choose from [1/2/3] (1): - [16/19] Should we setup a caching server? - 1 - Yes - 2 - No - Choose from [1/2] (1): - [17/19] Add Ansible playbooks? - 1 - Yes - 2 - No - Choose from [1/2] (1): - [18/19] Add GitHub Action to Deploy this project? - 1 - Yes - 2 - No - Choose from [1/2] (1): - [19/19] Would you like to add a documentation scaffold to your project? - 1 - Yes - 2 - No - Choose from [1/2] (1): -╭───────────────────────── Project Title generation ──────────────────────────╮ -│ │ -│ Summary: │ -│ │ -│ - Plone version: 6.1.1 │ -│ - Volto version: 18.22.0 │ -│ - Output folder: /project-title │ -│ │ -│ │ -╰─────────────────────────────────────────────────────────────────────────────╯ + [17/20] Should we setup a caching server? (Yes/no) + [18/20] Add Ansible playbooks? (Yes/no) + [19/20] Add GitHub Action to Deploy this project? (Yes/no) + [20/20] Would you like to add a documentation scaffold to your project? (Yes/no) + +╭─ Review your answers ──────────────────────────────────────────────────────────╮ +│ │ +│ Container Registry GitHub Container Registry │ +│ Should we use prerelease versions? No │ +│ Language English │ +│ Python Package Name project.title │ +│ Which persistent storage to use in RelStorage with PostgreSQL │ +│ the deployment stack? (recommended) │ +│ Author E-mail │ +│ GitHub or GitLab username or collective │ +│ organization slug from URL │ +│ Project Title Project Title │ +│ Use Volto as frontend? Yes │ +│ Add Ansible playbooks? Yes │ +│ Volto Addon Name volto-project-title │ +│ Volto Version 19.1.1 │ +│ Author │ +│ Should we setup a caching server? Yes │ +│ Plone Version 6.2.0 │ +│ Project Description A new project using Plone 6. │ +│ Project URL (without protocol) project-title.example.com │ +│ Project Slug (Used for repository project-title │ +│ id) │ +│ Add GitHub Action to Deploy this Yes │ +│ project? │ +│ Would you like to add a Yes │ +│ documentation scaffold to your │ +│ project? │ +│ │ +╰────────────────────────────────────────────────────────────────────────────────╯ +Proceed? [Y/n]: + -> Setup Backend -> Setup Frontend -> Generate documentation scaffold -> Setup Cache -> Setup Project Settings -==> Format codebase -Installed 1 package in 1ms -Found 4 errors (4 fixed, 0 remaining). -Installed 1 package in 2ms -2 files reformatted, 17 files left unchanged -Installed 6 packages in 10ms + -> Setup VSCode configuration + -> Setup GitHub CI + -> Ignoring (Remove unneeded documentation files) + -> Ignoring (Remove unneeded cache files) + -> Ignoring (Remove unneeded deploy files) + -> Ignoring (Remove frontend files for Classic UI) + -> Backend final cleanup + -> Format backend code + -> Format frontend code + -> Ignoring (Remove Ansible files) + -> Ignoring (Remove GitHub Actions deployment files) -> Organize documentation files - -> Remove unneeded documentation files + -> Ignoring (Remove unneeded documentation files) -> Initialize Git repository -╭───────────────────────── New project was generated ─────────────────────────╮ -│ │ -│ Project Title │ -│ │ -│ Now, code it, create a git repository, push to your organization. │ -│ │ -│ Sorry for the convenience, │ -│ The Plone Community. │ -│ │ -│ https://plone.org/ │ -╰─────────────────────────────────────────────────────────────────────────────╯ +╭─────────────────────────── New project was generated ───────────────────────────╮ +│ │ +│ Project Title │ +│ │ +│ Now, code it, create a git repository, push to your organization. │ +│ │ +│ Sorry for the convenience, │ +│ The Plone Community. │ +│ │ +│ https://plone.org/ │ +╰─────────────────────────────────────────────────────────────────────────────────╯ ``` -### Install the Volto project +### Install the project -To work on your Volto project, you need to install both the Plone backend and frontend. +To work on your project, you need to install both the backend and frontend. Change your current working directory to {file}`project-title`. @@ -294,7 +294,7 @@ To install both the Plone backend and Volto as frontend, use the following comma make install ``` -This will take a few minutes. +This will take a few minutes if you run it for the first time. ☕️ First the backend, then Volto as the frontend will be installed. @@ -304,7 +304,7 @@ When the process completes successfully, it will exit with no message. ``` -### Start Plone +### Start Plone backend and Volto frontend Plone with Volto for its frontend has two servers: one each for the backend and frontend. As such, we need to maintain two active shell sessions, one for each server, to start your Plone site. @@ -321,30 +321,29 @@ make backend-start The Plone backend server starts up and emits messages to the console similar to the following. ```console -🐎 This Python uses horse-with-no-namespace to make pkg_resources namespace packages compatible with PEP 420 namespace packages. -2025-05-30 00:03:13,990 INFO [chameleon.config:39][MainThread] directory cache: /Users/username/PATH_TO/project-title/backend/instance/var/cache. -2025-05-30 00:03:14,760 WARNING [ZODB.FileStorage:409][MainThread] Ignoring index for /Users/username/PATH_TO/project-title/backend/instance/var/filestorage/Data.fs -2025-05-30 00:03:14,897 INFO [plone.restapi.patches:16][MainThread] PATCH: Disabled ZPublisher.HTTPRequest.ZopeFieldStorage.VALUE_LIMIT. This enables file uploads larger than 1MB. -2025-05-30 00:03:15,091 INFO [plone.app.event:18][MainThread] icalendar has been set up to use pytz instead of zoneinfo. -2025-05-30 00:03:15,917 INFO [plone.volto:22][MainThread] Aliasing collective.folderish classes to plone.volto classes. -2025-05-30 00:03:16,407 INFO [Zope:42][MainThread] Ready to handle requests -Starting server in PID 31951. -2025-05-30 00:03:16,410 INFO [waitress:449][MainThread] Serving on http://[::1]:8080 -2025-05-30 00:03:16,410 INFO [waitress:449][MainThread] Serving on http://127.0.0.1:8080 +2026-05-29 11:48:31,825 INFO [chameleon.config:40][MainThread] directory cache: /Users/username/PATH_TO/project-title/backend/instance/var/cache. +2026-05-29 11:48:32,337 WARNING [ZODB.FileStorage:409][MainThread] Ignoring index for /Users/username/PATH_TO/project-title/backend/instance/var/filestorage/Data.fs +2026-05-29 11:48:32,475 INFO [plone.restapi.patches:15][MainThread] PATCH: Disabled ZPublisher.HTTPRequest.ZopeFieldStorage.VALUE_LIMIT. This enables file uploads larger than 1MB. +2026-05-29 11:48:32,757 INFO [plone.app.event:17][MainThread] icalendar has been set up to use pytz instead of zoneinfo. +2026-05-29 11:48:33,781 INFO [plone.volto:22][MainThread] Aliasing collective.folderish classes to plone.volto classes. +2026-05-29 11:48:34,311 INFO [Zope:42][MainThread] Ready to handle requests +Starting server in PID 93865. +2026-05-29 11:48:34,315 INFO [waitress:449][MainThread] Serving on http://[::1]:8080 +2026-05-29 11:48:34,315 INFO [waitress:449][MainThread] Serving on http://127.0.0.1:8080 ``` -#### Start Plone frontend +#### Start Volto frontend Create a second shell session in a new window. Change your current working directory to {file}`project-title`. -Start the Plone frontend with the following command. +Start the Volto frontend with the following command. ```shell make frontend-start ``` -The Plone frontend server starts up and emits messages to the console, and should end with output similar to the following. +The Volto frontend server starts up and emits messages to the console, and should end with output similar to the following. ```console webpack 5.90.1 compiled successfully in 14898 ms @@ -388,156 +387,15 @@ You can stop the site with {kbd}`ctrl-c`. This section describes how to install Plone by creating a project with Classic UI as the frontend. - -### Generate a Classic UI project - -After satisfying the prerequisites, generate the Classic UI project. +To create a ClassicUI project run the same command as in the section {ref}`create-project-cookieplone-create-volto-project-label`.: ```shell -uvx cookieplone classic_project -``` - -You will be presented with a series of prompts. -You can accept the default values in square brackets (`[default-option]`) by hitting the {kbd}`Enter` key, or enter your preferred values. -For ease of documentation, we will use the default values. - -```{tip} -See Cookieplone's README for how to [Use options to avoid prompts](https://github.com/plone/cookieplone/?tab=readme-ov-file#use-options-to-avoid-prompts). +uvx cookieplone project ``` -```{important} -For {guilabel}`Project Slug`, you must not use any of the Plone core package names listed in [`constraints.txt`](https://dist.plone.org/release/6-latest/constraints.txt). -Note that pip normalizes these names, so `my.project` and `my-project` are the same package. -``` +Only when asked `Use Volto as frontend (Yes/no)` you answer `No`! -```console -╭──────────────────────────────── cookieplone ────────────────────────────────╮ -│ │ -│ .xxxxxxxxxxxxxx. │ -│ ;xxxxxxxxxxxxxxxxxxxxxx; │ -│ ;xxxxxxxxxxxxxxxxxxxxxxxxxxxx; │ -│ xxxxxxxxxx xxxxxxxxxx │ -│ xxxxxxxx. .xxxxxxxx │ -│ xxxxxxx xxxxxxx: xxxxxxx │ -│ :xxxxxx xxxxxxxxxx xxxxxx: │ -│ :xxxxx+ xxxxxxxxxxx +xxxxx: │ -│ .xxxxx. :xxxxxxxxxx .xxxxx. │ -│ xxxxx+ ;xxxxxxxx +xxxxx │ -│ xxxxx +xx. xxxxx. │ -│ xxxxx: .xxxxxxxx :xxxxx │ -│ xxxxx .xxxxxxxxxx xxxxx │ -│ xxxxx xxxxxxxxxxx xxxxx │ -│ xxxxx .xxxxxxxxxx xxxxx │ -│ xxxxx: .xxxxxxxx :xxxxx │ -│ .xxxxx ;xx. ... xxxxx. │ -│ xxxxx+ :xxxxxxxx +xxxxx │ -│ .xxxxx. :xxxxxxxxxx .xxxxx. │ -│ :xxxxx+ xxxxxxxxxxx ;xxxxx: │ -│ :xxxxxx xxxxxxxxxx xxxxxx: │ -│ xxxxxxx xxxxxxx; xxxxxxx │ -│ xxxxxxxx. .xxxxxxxx │ -│ xxxxxxxxxx xxxxxxxxxx │ -│ ;xxxxxxxxxxxxxxxxxxxxxxxxxxxx+ │ -│ ;xxxxxxxxxxxxxxxxxxxxxx; │ -│ .xxxxxxxxxxxxxx. │ -│ │ -╰─────────────────────────────────────────────────────────────────────────────╯ -You've downloaded /Users/username/.cookiecutters/cookieplone-templates before. -Is it okay to delete and re-download it? [y/n] (y): -╭─────────────────────────────── Plone Project ───────────────────────────────╮ -│ │ -│ Creating a new Plone Project │ -│ │ -│ Sanity check results: │ -│ │ -│ - Cookieplone: ✓ │ -│ - uv: ✓ │ -│ - git: ✓ │ -│ - Docker (optional): ✓ │ -│ │ -╰─────────────────────────────────────────────────────────────────────────────╯ - [1/17] Project Title (Project Title): - [2/17] Project Description (A new project using Plone 6.): - [3/17] Project Slug (Used for repository id) (project-title): - [4/17] Project URL (without protocol) (project-title.example.com): - [5/17] Author (Plone Foundation): - [6/17] Author E-mail (collective@plone.org): - [7/17] Should we use prerelease versions? (No): - [8/17] Plone Version (6.1.1): - [9/17] Python Package Name (project.title): - [10/17] Language - 1 - English - 2 - Deutsch - 3 - Español - 4 - Português (Brasil) - 5 - Nederlands - 6 - Suomi - 7 - Italiano - 8 - Svenska - Choose from [1/2/3/4/5/6/7/8] (1): - [11/17] GitHub or GitLab username or organization slug from URL (collective): - [12/17] Container Registry - 1 - GitHub Container Registry - 2 - Docker Hub - 3 - GitLab - Choose from [1/2/3] (1): - [13/17] Which persistent storage to use in the deployment stack? - 1 - RelStorage with PostgreSQL (recommended) - 2 - ZEO with FileStorage - 3 - Local FileStorage, implies a single backend - Choose from [1/2/3] (1): - [14/17] Should we setup a caching server? - 1 - Yes - 2 - No - Choose from [1/2] (1): - [15/17] Add Ansible playbooks? - 1 - Yes - 2 - No - Choose from [1/2] (1): - [16/17] Add GitHub Action to Deploy this project? - 1 - Yes - 2 - No - Choose from [1/2] (1): - [17/17] Would you like to add a documentation scaffold to your project? - 1 - Yes - 2 - No - Choose from [1/2] (1): -╭───────────────────────── Project Title generation ──────────────────────────╮ -│ │ -│ Summary: │ -│ │ -│ - Plone version: 6.1.1 │ -│ - Output folder: /project-title │ -│ │ -│ │ -╰─────────────────────────────────────────────────────────────────────────────╯ - -> Setup Backend - -> Generate documentation scaffold - -> Setup Cache - -> Classic Setup Project Settings -==> Format codebase -Installed 1 package in 3ms -Found 4 errors (4 fixed, 0 remaining). -Installed 1 package in 1ms -17 files left unchanged -Installed 6 packages in 21ms - -> Organize documentation files - -> Remove unneeded documentation files - -> Initialize Git repository -╭───────────────────────── New project was generated ─────────────────────────╮ -│ │ -│ Project Title │ -│ │ -│ Now, code it, create a git repository, push to your organization. │ -│ │ -│ Sorry for the convenience, │ -│ The Plone Community. │ -│ │ -│ https://plone.org/ │ -╰─────────────────────────────────────────────────────────────────────────────╯ -``` - -### Install the Classic UI project +### Install the project To work on your project, you need to install it. From b807cae020503817c566c3a7437a237aa08d220e Mon Sep 17 00:00:00 2001 From: Philip Bauer Date: Fri, 29 May 2026 16:16:58 +0200 Subject: [PATCH 3/4] re-add the output of a classicui project --- docs/install/create-project-cookieplone.md | 168 ++++++++++++++++++--- 1 file changed, 147 insertions(+), 21 deletions(-) diff --git a/docs/install/create-project-cookieplone.md b/docs/install/create-project-cookieplone.md index 2064e61be8..629ab39540 100644 --- a/docs/install/create-project-cookieplone.md +++ b/docs/install/create-project-cookieplone.md @@ -120,9 +120,9 @@ Node.js is required only for Volto projects and not for Classic UI projects. (create-project-cookieplone-create-volto-project-label)= -## Create a Plone project +## Create a Volto project -After satisfying the prerequisites, generate a Plone project. +After satisfying the prerequisites and having {ref}`activated an LTS version of Node.js `, generate a Volto project. ```shell uvx cookieplone project @@ -133,8 +133,6 @@ You can accept the default values in square brackets (`[default-option]`) by hit For ease of documentation, we will use the default values and thus create a project using the Volto frontend. -To create a project using the ClassicUI frontend instead answer `No` when asked `Use Volto as frontend (Yes/no)`. - ```{tip} See Cookieplone's README for how to [Use options to avoid prompts](https://github.com/plone/cookieplone/?tab=readme-ov-file#use-options-to-avoid-prompts). ``` @@ -175,18 +173,9 @@ Note that pip normalizes these names, so `plone.volto` and `plone-volto` are the [7/20] Python Package Name (project.title): [8/20] Should we use prerelease versions? (yes/No): [9/20] Plone Version (6.2.0): -``` -The next questions will determine if you will create a Volto or ClassicUI project. -``` [10/20] Use Volto as frontend (Yes/no): -``` -These two questions are only asked if you choose to create a project using Volto: -``` [11/20] Volto Version (19.1.0): [12/20] Volto Addon Name (volto-project-title): -``` -For the remaining questions again we choose the default answer. -``` [13/20] Language 1 - English 2 - Deutsch @@ -278,9 +267,9 @@ Proceed? [Y/n]: ``` -### Install the project +### Install the Volto project -To work on your project, you need to install both the backend and frontend. +To work on your Volto project, you need to install both the Plone backend and frontend. Change your current working directory to {file}`project-title`. @@ -304,7 +293,7 @@ When the process completes successfully, it will exit with no message. ``` -### Start Plone backend and Volto frontend +### Start Plone Plone with Volto for its frontend has two servers: one each for the backend and frontend. As such, we need to maintain two active shell sessions, one for each server, to start your Plone site. @@ -333,17 +322,17 @@ Starting server in PID 93865. ``` -#### Start Volto frontend +#### Start Plone frontend Create a second shell session in a new window. Change your current working directory to {file}`project-title`. -Start the Volto frontend with the following command. +Start the Plone frontend with the following command. ```shell make frontend-start ``` -The Volto frontend server starts up and emits messages to the console, and should end with output similar to the following. +The Plone frontend server starts up and emits messages to the console, and should end with output similar to the following. ```console webpack 5.90.1 compiled successfully in 14898 ms @@ -393,9 +382,146 @@ To create a ClassicUI project run the same command as in the section {ref}`creat uvx cookieplone project ``` -Only when asked `Use Volto as frontend (Yes/no)` you answer `No`! +You will be presented with a series of prompts. +You can accept the default values in square brackets (`[default-option]`) by hitting the {kbd}`Enter` key, or enter your preferred values. + +```{tip} +See Cookieplone's README for how to [Use options to avoid prompts](https://github.com/plone/cookieplone/?tab=readme-ov-file#use-options-to-avoid-prompts). +``` + +```{important} +For {guilabel}`Project Slug`, you must not use any of the Plone core package names listed in [`constraints.txt`](https://dist.plone.org/release/6-latest/constraints.txt). +Note that pip normalizes these names, so `my.project` and `my-project` are the same package. +``` + +We accept the default values, except when asked `Use Volto as frontend (Yes/no)` we answer `No`! + +```console +╭──────────────────────────── cookieplone (2.0.0a3) ─────────────────────────────╮ +│ │ +│ ******* │ +│ *************** │ +│ *** *** │ +│ *** *** *** │ +│ *** ***** *** │ +│ *** *** *** │ +│ *** *** *** │ +│ *** ***** *** │ +│ *** *** *** *** │ +│ *** ***** *** │ +│ *** *** *** │ +│ *** *** │ +│ *************** │ +│ ******* │ +│ │ +╰───────────────────── Made with ❤️ by the Plone Community ──────────────────────╯ +``` + +``` + [1/18] Project Title (Project Title) + [2/18] Project Description (A new project using Plone 6.): + [3/18] Project Slug (Used for repository id) (project-title): + [4/18] Project URL (without protocol) (project-title.example.com): + [5/18] Author (Plone Foundation): + [6/18] Author E-mail (collective@plone.org): + [7/18] Python Package Name (project.title): + [8/18] Should we use prerelease versions? (yes/No): + [9/18] Plone Version (6.2.0): +``` + +To the question `Use Volto as frontend` you need to answer `No` to create a ClassicUI project! + +``` + [10/18] Use Volto as frontend (Yes/no): No + [11/18] Language + 1 - English + 2 - Deutsch + 3 - Español + 4 - Português (Brasil) + 5 - Nederlands + 6 - Suomi + 7 - Italiano + 8 - Svenska + Choose from [1/2/3/4/5/6/7/8] (1): + [12/18] GitHub or GitLab username or organization slug from URL (collective): + [13/18] Container Registry + 1 - GitHub Container Registry + 2 - Docker Hub + 3 - GitLab + Choose from [1/2/3] (1): + [14/18] Which persistent storage to use in the deployment stack? + 1 - RelStorage with PostgreSQL (recommended) + 2 - ZEO with FileStorage + 3 - Local FileStorage, implies a single backend + Choose from [1/2/3] (1): + [15/18] Should we setup a caching server? (Yes/no) + [16/18] Add Ansible playbooks? (Yes/no) + [17/18] Add GitHub Action to Deploy this project? (Yes/no) + [18/18] Would you like to add a documentation scaffold to your project? (Yes/no) + +╭─ Review your answers ──────────────────────────────────────────────────────────╮ +│ │ +│ Container Registry GitHub Container Registry │ +│ Should we use prerelease versions? No │ +│ Language English │ +│ Python Package Name project.title │ +│ Which persistent storage to use in RelStorage with PostgreSQL │ +│ the deployment stack? (recommended) │ +│ Author E-mail │ +│ GitHub or GitLab username or collective │ +│ organization slug from URL │ +│ Project Title Project Title │ +│ Use Volto as frontend? No │ +│ Add Ansible playbooks? Yes │ +│ Author │ +│ Should we setup a caching server? Yes │ +│ Plone Version 6.2.0 │ +│ Project Description A new project using Plone 6. │ +│ Project URL (without protocol) project-title.example.com │ +│ Project Slug (Used for repository project-title │ +│ id) │ +│ Add GitHub Action to Deploy this Yes │ +│ project? │ +│ Would you like to add a Yes │ +│ documentation scaffold to your │ +│ project? │ +│ │ +╰────────────────────────────────────────────────────────────────────────────────╯ +Proceed? [Y/n]: + + -> Setup Backend + -> Ignoring (Setup Frontend) + -> Generate documentation scaffold + -> Setup Cache + -> Setup Project Settings + -> Setup VSCode configuration + -> Setup GitHub CI + -> Ignoring (Remove unneeded documentation files) + -> Ignoring (Remove unneeded cache files) + -> Ignoring (Remove unneeded deploy files) + -> Remove frontend files for Classic UI + -> Backend final cleanup + -> Format backend code + -> Ignoring (Format frontend code) + -> Ignoring (Remove Ansible files) + -> Ignoring (Remove GitHub Actions deployment files) + -> Organize documentation files + -> Ignoring (Remove unneeded documentation files) + -> Initialize Git repository + ╭─────────────────────────── New project was generated ───────────────────────────╮ +│ │ +│ Project Title │ +│ │ +│ Now, code it, create a git repository, push to your organization. │ +│ │ +│ Sorry for the convenience, │ +│ The Plone Community. │ +│ │ +│ https://plone.org/ │ +╰─────────────────────────────────────────────────────────────────────────────────╯ +``` -### Install the project +### Install the Classic UI project To work on your project, you need to install it. From 3ac5655c68e3b44f7fa24687033eaa1fe20d1999 Mon Sep 17 00:00:00 2001 From: Philip Bauer Date: Fri, 29 May 2026 17:33:14 +0200 Subject: [PATCH 4/4] wording --- docs/install/create-project-cookieplone.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/install/create-project-cookieplone.md b/docs/install/create-project-cookieplone.md index 629ab39540..c1e8b7146c 100644 --- a/docs/install/create-project-cookieplone.md +++ b/docs/install/create-project-cookieplone.md @@ -376,7 +376,7 @@ You can stop the site with {kbd}`ctrl-c`. This section describes how to install Plone by creating a project with Classic UI as the frontend. -To create a ClassicUI project run the same command as in the section {ref}`create-project-cookieplone-create-volto-project-label`.: +After satisfying the prerequisites, generate a ClassicUI project. ```shell uvx cookieplone project