Add "create project" docs for cookieplone

[davisagli]

This is my attempt to update the docs to cover the new project templates from Cookieplone. It is based partly on @animus888's work in #1649 but goes a bit further:

• The existing create-project.md remains as is for now, but is re-titled as "Create a project with the Volto frontend". Once we have a final release of Volto 18, this should be re-titled again as "Create a project with the Volto frontend (Volto 17 and earlier)" and renamed to create-project-legacy.md
• New page create-project-cookieplone.md titled "Create a project with the Volto frontend (Volto 18+)". Once we have a final release of Volto 18, this should become the "default" recommendation in create-project.md.
• New page create-project-classicui.md titled "Create a project with the Classic UI".

---

📚 Documentation preview 📚: https://plone6--1714.org.readthedocs.build/

[sneridagh]

LGTM! Thanks for working on this!

Just a small comment: yes, corepack is needed.

[davisagli]

Thanks for the editing @stevepiercy, your improvements make sense.

[stevepiercy]

Is Cookieplone "preferred", "experimental", or some other term for Plone, not just Volto? We say it is the new way for Volto 18, but do not specify a Plone version. We need to clarify this in the new Classic UI install page.

The latest I heard is that buildout shall remain in use when installing Plone 6.1 for new backend projects, add-ons, and contributing. But now with the addition of Cookieplone to create backend projects and add-ons, for what purposes shall we use buildout as a method to install Plone?

Will we deprecate buildout? If so, for what version of Plone?

I think we'll need to add this to the Plone 6.1/7.0 roadmap, too. @tisto @mauritsvanrees

[animus888]

The "create a project..." parts ( 📚 https://plone6--1714.org.readthedocs.build/install/index.html) are now more convenient and fit better in the "Install" section.
In my opinion it's a big improvement 👍

It's good that the examples on changing header, footer, fonts, etc. with Volto18+ have been left out. They could be added to the frontend theming section in another pull request and then we could link to these examples in "Create a project with Volto (development or pre-release)".
But that's another topic and maybe it's really too early for that..

[stevepiercy]

@animus888 with the move to remove Semantic UI, the Theming docs need to be overhauled.

I think that much of the content in Custom Styling is still relevant for the items you mention, except it needs to be written in the context of an add-on, not file overrides.

[1letter]

cookieplone use pytest for backend addons as default test engine... thats not documented, missing examples. For me is this a blocker.

[stevepiercy]

cookieplone use pytest for backend addons as default test engine...

What should be the default, if not pytest?

thats not documented,

Cookieplone's README has this: https://github.com/plone/cookieplone?tab=readme-ov-file#run-tests

missing examples.

To do what? We have Common management tasks and a PR to reorganize it which needs review and feedback for improvement.

For me is this a blocker.

Let's remove the blockers and fill in the gaps in documentation. I lack the experience and knowledge with Plone that you and many other long-time developers have, otherwise I'd write a lot more documentation. We started collaboration on a couple of other PRs to fill a few gaps, they got reviews, and I'm waiting for revisions and further feedback:

• add install notes for classic ui, pip and buildout method #1701
• add notes to create an emergency user #1703

[davisagli]

What should be the default, if not pytest?

Plone has for many years used unittest-style tests built with test layers from plone.app.testing and run via the Zope testrunner.

The Cookieplone template uses pytest-style tests built with the same test layers (thanks to pytest-plone) and run via pytest. This has been an effort mostly on @ericof's part and it has some benefits, to be more compatible with the rest of the Python ecosystem. I'm feeling a bit grumpy about it at the moment because it got added to the templates without going through any PLIP review, and while I like pytest, it might be a bit premature to make it the default.

@1letter is right to point out that more docs are needed, although the Plone 6 docs also don't cover the old way of testing either. (i.e. the sort of material that was in https://5.docs.plone.org/develop/testing/index.html)

Cookieplone's README has this: https://github.com/plone/cookieplone?tab=readme-ov-file#run-tests

Those are commands to run Cookieplone's own tests, it doesn't cover how to write and run tests for the project or addon you created with Cookieplone.

There is some info in https://github.com/collective/pytest-plone but this is more of a reference than a guide.

To do what? We have Common management tasks and a #1724 which needs review and feedback for improvement.

That's a different topic with a different audience. "Common management tasks" covers things that an admin running a Plone site needs to know. How to write and run tests is for more of a developer audience.

[stevepiercy]

Thanks for the feedback.

Additionally, this friendly warning explains a lot to me https://github.com/collective/pytest-plone?tab=readme-ov-file#warning:

Warning

THIS PACKAGE IS NOT CONSIDERED TO BE STABLE AND FIXTURES COULD CHANGE BEFORE A FINAL RELEASE

@1letter, @davisagli, and any other long-time backend developers, for Documentation, would the following be next steps?

• Promote buildout in Plone 6 Documentation as the only supported and stable way to develop the Plone 6 backend. We have a PR in progress.
• Add a warning admonition on Cookieplone for the backend that it is not stable and it uses pytest as a test runner.
• Port testing documentation from https://5.docs.plone.org/develop/testing/index.html to Plone 6 Documentation. I can start a PR for that, but we need some long-timers to review it and verify its accuracy for Plone 6.
• Ensure that the new backend testing PR is either unrelated to, or is consistent with, Contribute to Plone 6 core > Test locally.

Did I miss anything?

[davisagli]

pytest-plone actually is pretty stable and we should remove that warning. It's used in enough places that breaking changes would require a new major version. PR: collective/pytest-plone#15

Promote buildout in Plone 6 Documentation as the only supported and stable way to develop the Plone 6 backend.

When you say "the Plone 6 backend", do you mean for developing Plone itself, or for working on Plone backend add-ons and projects?

I would argue buildout and the setup created by Cookieplone are about equally supported and stable at present. Buildout obviously has been around a lot longer, but it has had some issues keeping up with recent changes in setuptools and is receiving a bare minimum amount of maintenance. The Cookieplone setup has some rough edges that need to be sorted out, but is also proven in real projects and is being actively supported.

I would definitely object to only covering buildout in the docs. It's not a tool I'm using any more, except when I work on an old Plone 5 project or do core development using buildout.coredev, and I intend to try out the non-buildout way of doing the latter that Maurits recently merged.

Port testing documentation from https://5.docs.plone.org/develop/testing/index.html to Plone 6 Documentation. I can start a PR for that, but we need some long-timers to review it and verify its accuracy for Plone 6.

I can try to help work on some up-to-date testing docs, but I'd prefer to start from scratch and then refer to the old docs to see what is missing, rather than start by porting the old docs.

[1letter]

Short actual story by me. Yesterday i setup a small addon via cookieplone for a Plone 6 Classic UI Site. My first impression, good! I see the pytests and think "Hmm WTF" why a new way, why a fundemantal change through a backdoor ;-) . I know that pytest is the defacto standard in the python world. I can live with this change but i need some examples and explanations for the magical pytest layers... I'm feeling a bit grumpy, also. I would be happy if such a change can be discussed in a larger group of plonistas, perhaps during the Conf?

[stevepiercy]

Revised checklist:

• Complete the PR in progress for buildout in Plone 6 Documentation. add install notes for classic ui, pip and buildout method #1701
• Add a page to Plone 6 documentation for testing the backend the current way which points to https://5.docs.plone.org/develop/testing/index.html. We can add usage and examples to it, and add a note to the link staging why we have two testing methods and which should be used at that moment. When complete, we'd remove the link to Plone 5 documentation. I think this page would go under Backend > Development.
• Ensure that these two pages are either unrelated to, or consistent with, Contribute to Plone 6 core > Test locally. I think this context is distinct from the other two items, but I'd appreciate verification.

For these items, let's not wait until PloneConf. Right now we have a gaping hole in Plone 6 Documentation for testing the backend. This will put a patch over the hole and create a place to accept future contributions.

As far as the change to use pytest in Cookieplone, I absolutely agree that it needs more discussion at PloneConf, Team meetings, and wherever else Plonistas gather. I also think there should be a PLIP to serve as a centralized location for information about this change, even though it mostly already happened, but without the required documentation and communication, which makes me grumpy, too. We can give it the title "PLIP: Degrumpify Cookieplone for backend developers and documentarians".

[sneridagh]

@stevepiercy +1 we need docs for "Pytest Patterns while writting tests for Plone" and another "Pytest for former Plone developers turned into the JS front-end development dark side"

PloneConf talk, anyone? :)

[sneridagh]

@stevepiercy @davisagli BTW, thanks for working on this!

[stevepiercy]

• Add a page to Plone 6 documentation for testing the backend the current way which points to https://5.docs.plone.org/develop/testing/index.html. We can add usage and examples to it, and add a note to the link staging why we have two testing methods and which should be used at that moment. When complete, we'd remove the link to Plone 5 documentation. I think this page would go under Backend > Development.

I've never been happy with the mixture of primary navigation items in the docs. It's not good for newcomers to Plone. We have a mixture of actions (Install, Manage Plone, Upgrade guide, Deployment, Contributing) and things (Frontend, REST API, Backend, Classic UI, i18n and l10n, and Conceptual guides). The "actions" group is understandable to almost any visitor, whereas the "things" group is Plone-specific jargon. And I especially despise "Frontend" (Volto or Classic UI) and "Backend" (REST API, plone.api, the dozens of other Plone core packages, and even Classic UI sometimes gets tossed in here), because they mean different things in different contexts. Ultimately the primary navigation should consist of actions, not things.

With recent additions, and more on the way, we should have a new section "Development guide". Taking Testing as an example, it would have links and content for the following:

• Volto
  • Unit testing https://6.docs.plone.org/volto/contributing/testing.html
  • Acceptance tests https://6.docs.plone.org/volto/contributing/acceptance-tests.html
• Classic UI
  • Admonition and link to https://5.docs.plone.org/develop/testing/index.html

[stevepiercy]

PR created: #1731

That and the other PR should resolve the issues brought up after merging this PR. Thank you, everyone, for your feedback.