Add Create a backend add-on section in the Developer guide with `GenericSetup` by stevepiercy · Pull Request #1757 · plone/documentation

stevepiercy · 2024-11-06T08:56:31Z

Enhance the Development Guide index
Update the term Buildout in the Glossary to point to dusty old, yet useful, docs in Plone 4.
Source for GenericSetup already converted to MyST: https://github.com/plone/documentation/blob/5.2-myst/5.2-myst/develop/addons/components/genericsetup.md
List of possible sources from Backend > Configuration Registry needs content (GenericSetup) #1424

Closes #1754.

Ping @petschki to take it from here.

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

@petschki

Ping @petschki - Enhance the Development Guide index - Update the term Buildout in the Glossary to point to dusty old, yet useful, docs in Plone 4. (cherry picked from commit 8142b96)

- Add term reference for Buildout

stevepiercy · 2025-11-25T12:10:11Z

I'm ready to close this issue as won't fix. Does anyone on @plone/classicui-team care about the topic of how to add or create a backend add-on section in the Developer guide with GenericSetup? If so, speak up, and let's get this finished.

petschki · 2025-11-25T12:45:11Z

@stevepiercy will have a look at this.

petschki · 2025-11-25T14:56:41Z

I've created a basic "addon creation documentation" and moved the old docs for GenericSetup here. I've also removed several outdated parts/link and tried to update the XML examples. Not finished yet though.

I would recommend to place these docs all inside "Backend" and make a link from "Developer guide / Develop backend add-ons" -> "Backend / Add-ons" (like its done for Volto add-ons)

Further we can add references for several plonecli installation guides (like Classic-UI / theming / create theme addon) to the new "Backend / Add-on" doc ...

What do you think?

petschki · 2025-11-25T14:59:58Z

what's also missing is something like "Installing backend Add-on" ... at least I didn't find it... would also make sense to add it to "Backend / Add-ons" chapter.

EDIT: I mean adding a pypi package or source checkout to cookieplone/buildout project ...

stevepiercy · 2025-11-26T05:57:32Z

what's also missing is something like "Installing backend Add-on" ... at least I didn't find it... would also make sense to add it to "Backend / Add-ons" chapter.

EDIT: I mean adding a pypi package or source checkout to cookieplone/buildout project ...

Was this what you couldn't find?

https://6.docs.plone.org/admin-guide/add-ons.html

The plan is to merge the Admin section into Develop section so that people don't have to think of what role they're in versus the task they want to perform. See #1997.

stevepiercy · 2025-12-08T10:25:09Z

@petschki @erral are there any other technical issues to resolve before I dive in for a general editorial review? Please let me know. Thank you!

Co-authored-by: Mikel Larreategi <mlarreategi@codesyntax.com>

petschki · 2025-12-09T07:05:45Z

@petschki @erral are there any other technical issues to resolve before I dive in for a general editorial review? Please let me know. Thank you!

I still need to go through the genericsetup doc technically. There are some outdated bits which have to be removed.

stevepiercy · 2026-01-14T23:10:18Z

I still need to go through the genericsetup doc technically. There are some outdated bits which have to be removed.

@petschki I don't see a commit to remove the outdated bits. Did you forget to push it? Please let me know. Thank you!

MrTango · 2026-01-15T09:47:55Z

I would use plonecli for all, after @erral did the final release in the comming days.
It will then work as it was working for Plone 5 development, with the difference that now the create addon part is using cookieplone backend_addon under the hood. This is exactly why we have plonecli, to hide stuff under it and give the developers a clean cli.

example:

uv tool install plonecli
plonecli create addon collective.myaddon

cd collective.myaddon
plonecli add content_type
...

make add, would be an abstraction, which calls an abstraction (plonecli), which calls a bobtemplate.
I don't mind that the make command exist, for who want to do it this way, but i would not put this out as the default, otherwise we can take out plonecli from the mix and do it purely in Make.

We could even create a full cookieplone project with plonecli.

plonecli create volto-project

or

plonecli create cookieplone-project

or

plonecli create plone-project

it doesn't matter and we are flexible to replace part under it, with the next cool tool, someone creates, without destroing exiting docs and api's.

my 50cent...

petschki · 2026-01-15T09:53:55Z

@MrTango I had documente the plonecli part initially and removed it as @erral's request ... can we find a consent here?

I think, due to the fact that the whole plone installation and theme development documentation uses cookieplone, we should at least use it for the inital addon package creation too ... when adding further features inside the addon, we can document this with using plonecli ...

erral · 2026-01-15T10:00:36Z

@petschki @MrTango sorry for the mess...

with plonecli right now we can create an add-on calling plonecli create addon which creates a backend_addon calling uvx cookieplone backend_addon.

I haven't checked to do the same for volto addon, project, etc, but could be done, and it is not that hard.

If we do that we can document everything to use plonecli indeed, and cookieplone would be just an "implementation detail".

But we also have documentation to create Volto projects using uvx cookieplone so the mess is bigger...

yurj · 2026-01-15T10:09:50Z

cookieplone is the framework with utils to full manage a Plone project while plonecli is a client that implements the frameworks (past and present).

stevepiercy · 2026-01-15T10:41:25Z

What are the use cases that we're trying to solve with this page of documentation? Maybe that answer will help us give a direction. Would y'all agree there are essentially two scenarios?

Create a backend add-on only.
Create a backend add-on along with a combination of anything else, such as a full Plone project, a Volto add-on, project documentation scaffold, and devops.

Neither Cookieplone nor plonecli are going away anytime soon. If we have two or more ways of doing the same thing, that's fine, too, provided we give sufficient information for the reader to choose which tool is best for them. For an example of that, see Choose a user interface. It's also OK if we use one tool to do one part, such as using Cookieplone to create a monorepo with all the things, and another tool to do another part, such as add new features to the backend add-on.

Does this help at all?

petschki · 2026-01-15T11:21:15Z

@erral @MrTango I've now replaced the cookieplone part with my formerly removed plonecli part ...

davisagli

Let's see if we can get this over the finish line.

davisagli · 2026-02-20T05:35:57Z

I just skimmed through to check that this is still accurate/relevant information. It is and we should prioritize getting this merged. It does need some editing to match current doc styles.

erral · 2026-04-16T14:56:04Z

I have just released new versions for mr.bob, plonecli and bobtemplates removing all pkg_resources style namespaces. I tested the three of them together and it works as expected. I will review this PR tomorrow to check that everything is Ok.

erral

I have checked the output of uvx plonecli and it is a bit different than the previous version.

erral · 2026-05-03T14:12:08Z

+
+--> Package description [An add-on for Plone]:
+
+--> Plone version [6.0.0]:
+
+--> Python version for virtualenv [python3]:
+
+--> Do you want me to activate VS Code support? (y/n) [y]:
+
+
+
+isort-apply: successful:
+isort-apply: install_deps> python -I -m pip install isort -c constraints.txt
+isort-apply: commands[0]> isort /Users/<username>/Development/collective.addon/src
+/Users/<username>/Development/collective.addon/setup.py
+Fixing /Users/<username>/Development/collective.addon/src/collective/addon/testing.py
+Fixing /Users/<username>/Development/collective.addon/src/collective/addon/tests/test_setup.py
+  isort-apply: OK (2.57=setup[1.94]+cmd[0.63] seconds)
+  congratulations :) (2.59 seconds)
+
+
+Identified `/` as project root containing a file system root.
+Sources to be formatted: "Users/<username>/Development/collective.addon/src",
+  "Users/<username>/Development/collective.addon/setup.py"
+src/collective/__init__.py wasn't modified on disk since last run.
+src/collective/addon/browser/__init__.py wasn't modified on disk since last run.
+src/collective/addon/locales/__init__.py wasn't modified on disk since last run.
+src/collective/addon/tests/__init__.py wasn't modified on disk since last run.
+src/collective/addon/interfaces.py already well formatted, good job.
+reformatted src/collective/addon/__init__.py
+reformatted src/collective/addon/setuphandlers.py
+reformatted src/collective/addon/testing.py
+reformatted setup.py
+reformatted src/collective/addon/locales/update.py
+reformatted src/collective/addon/tests/test_setup.py
+
+All done! ✨ 🍰 ✨
+6 files reformatted, 5 files left unchanged.
+
+black-enforce: successful:
+black-enforce: install_deps> python -I -m pip install black -c constraints.txt
+black-enforce: commands[0]> black -v src setup.py
+  black-enforce: OK (2.60=setup[2.12]+cmd[0.48] seconds)
+  congratulations :) (2.61 seconds)
+
+
+git init is disabled!
+Generated file structure at /Users/<username>/Development/collective.addon/collective.addon
+```


Suggested change

--> Package description [An add-on for Plone]:

--> Plone version [6.0.0]:

--> Python version for virtualenv [python3]:

--> Do you want me to activate VS Code support? (y/n) [y]:

isort-apply: successful:

isort-apply: install_deps> python -I -m pip install isort -c constraints.txt

isort-apply: commands[0]> isort /Users/<username>/Development/collective.addon/src

/Users/<username>/Development/collective.addon/setup.py

Fixing /Users/<username>/Development/collective.addon/src/collective/addon/testing.py

Fixing /Users/<username>/Development/collective.addon/src/collective/addon/tests/test_setup.py

isort-apply: OK (2.57=setup[1.94]+cmd[0.63] seconds)

congratulations :) (2.59 seconds)

Identified `/` as project root containing a file system root.

Sources to be formatted: "Users/<username>/Development/collective.addon/src",

"Users/<username>/Development/collective.addon/setup.py"

src/collective/__init__.py wasn't modified on disk since last run.

src/collective/addon/browser/__init__.py wasn't modified on disk since last run.

src/collective/addon/locales/__init__.py wasn't modified on disk since last run.

src/collective/addon/tests/__init__.py wasn't modified on disk since last run.

src/collective/addon/interfaces.py already well formatted, good job.

reformatted src/collective/addon/__init__.py

reformatted src/collective/addon/setuphandlers.py

reformatted src/collective/addon/testing.py

reformatted setup.py

reformatted src/collective/addon/locales/update.py

reformatted src/collective/addon/tests/test_setup.py

All done! ✨ 🍰 ✨

6 files reformatted, 5 files left unchanged.

black-enforce: successful:

black-enforce: install_deps> python -I -m pip install black -c constraints.txt

black-enforce: commands[0]> black -v src setup.py

black-enforce: OK (2.60=setup[2.12]+cmd[0.48] seconds)

congratulations :) (2.61 seconds)

git init is disabled!

Generated file structure at /Users/<username>/Development/collective.addon/collective.addon

```

```suggestion

--> Author's name [John Doe]:

--> Author's email [johndoe@plone.org]:

--> Author's GitHub username:

--> Package description [An add-on for Plone]:

--> Do you want me to initialize a GIT repository in your new package? (y/n) [y]:

--> Plone version [6.0.0]:

--> Python version for virtualenv [python3]:

--> Do you want me to activate VS Code support? (y/n) [y]:

╭────────────────────────────────────────────────────────────────── cookieplone ──────────────────────────────────────────────────────────────────╮

│ │

│ ******* │

│ *************** │

│ *** *** ********* *** *** │

│ *** *** *** *********** *** * R * │

│ *** ***** *** *** *** *** *** │

│ *** *** *** *** *** *** **** *** *** **** │

│ *** *** *** *** *** *** ******** ********* ******** │

│ *** ***** *** *********** *** *** *** **** *** *** *** │

│ *** *** *** *** ********* *** *** *** *** *** ********** │

│ *** ***** *** *** *** *** *** *** *** ********* │

│ *** *** *** *** **** *** *** *** *** *** ... │

│ *** *** *** ***** ******** *** *** ******** │

│ *************** *** *** **** *** *** **** │

│ ******* │

│ │

╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

╭────────────────────────────────────────────────────────────────── Plone Addon ──────────────────────────────────────────────────────────────────╮

│ │

│ Creating a new Plone Addon │

│ │

│ Sanity check results: │

│ │

│ - Cookieplone: ✓ │

│ - uv: ✓ │

│ - git: ✓ │

│ │

╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

-> Remove files used in classic UI setup

-> Create namespace packages

-> Format code

-> Initialize Git repository

-> Generate documentation scaffold

-> Setup VSCode configuration

-> Setup GitHub CI

╭──────────────────────────────────────────────────────────── New addon was generated ────────────────────────────────────────────────────────────╮

│ │

│ collective.addon │

│ │

│ Now, enter the repository, start coding, and push to your organization. │

│ │

│ Sorry for the convenience, │

│ The Plone Community. │

│ │

│ https://plone.org/ │

╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

Done

Generated file structure at /tmp/collective.addon

stevepiercy added 3 commits November 6, 2024 00:52

Add Create a backend add-on section in the Developer guide.

091a89a

Ping @petschki - Enhance the Development Guide index - Update the term Buildout in the Glossary to point to dusty old, yet useful, docs in Plone 4. (cherry picked from commit 8142b96)

- Update meta information

a766f5a

- Add term reference for Buildout

Merge branch '6.0' into dev-guide-create-a-backend-add-on

d8e135c

This was referenced Nov 6, 2024

Explain how to create a custom pattern #1748

Merged

Update: buildout docs #278

Closed

Create Development guide as a primary navigation item and entry point #1731

Closed

davisagli reviewed Nov 6, 2024

View reviewed changes

Comment thread docs/developer-guide/create-a-backend-add-on.md Outdated

davisagli mentioned this pull request Nov 8, 2024

Add chapter or section to admin guide on how to create a new backend add-on and how to include in backend #1768

Open

stevepiercy added 3 commits November 8, 2024 11:52

Merge branch '6.0' into dev-guide-create-a-backend-add-on

ed9c4af

Merge branch '6.0' into dev-guide-create-a-backend-add-on

13b85f7

Merge branch '6.0' into dev-guide-create-a-backend-add-on

0f7a455

stevepiercy changed the title ~~Add Create a backend add-on section in the Developer guide.~~ Add Create a backend add-on section in the Developer guide with GenericSetup Nov 24, 2024

stevepiercy added 2 commits December 5, 2024 05:26

Merge branch '6.0' into dev-guide-create-a-backend-add-on

7767c8b

Merge branch '6.0' into dev-guide-create-a-backend-add-on

9d9994f

stevepiercy assigned petschki, yurj, MrTango, 1letter and stevepiercy Feb 9, 2025

Merge branch '6.0' into dev-guide-create-a-backend-add-on

3119199

stevepiercy removed this from Alpine City Sprint 2025 Feb 26, 2025

Merge branch '6.0' into dev-guide-create-a-backend-add-on

dcc8b32

petschki added 2 commits November 25, 2025 15:46

create backend addon documentation

67b1ee7

create genericsetup documentation

0cad2b0

remove note

042ff32

erral requested changes Dec 1, 2025

View reviewed changes

Comment thread docs/developer-guide/create-a-backend-add-on.md Outdated

github-project-automation Bot moved this from Todo to In Progress in Plone Documentation Dec 1, 2025

Update docs/developer-guide/create-a-backend-add-on.md

132f1be

Co-authored-by: Mikel Larreategi <mlarreategi@codesyntax.com>

Merge branch '6.0' into dev-guide-create-a-backend-add-on

2fe88be

explain how to create a backend-addon with plonecli only.

bb795bc

minor command fix

3db83f5

stevepiercy requested review from MrTango, davisagli, erral and jensens January 15, 2026 22:25

erral previously approved these changes Jan 16, 2026

View reviewed changes

github-project-automation Bot moved this from In Progress to Approved in Plone Documentation Jan 16, 2026

stevepiercy added 2 commits February 9, 2026 02:57

Merge branch '6.0' into dev-guide-create-a-backend-add-on

a7b0d43

Begin editorial clean up

096109d

stevepiercy dismissed erral’s stale review via 096109d February 9, 2026 22:11

davisagli reviewed Feb 20, 2026

View reviewed changes

Merge branch '6.0' into dev-guide-create-a-backend-add-on

a0358f1

Merge branch '6.0' into dev-guide-create-a-backend-add-on

80201c7

erral requested changes May 3, 2026

View reviewed changes

github-project-automation Bot moved this from Approved to In Progress in Plone Documentation May 3, 2026

Uh oh!

Conversation

stevepiercy commented Nov 6, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

stevepiercy commented Nov 25, 2025

Uh oh!

petschki commented Nov 25, 2025

Uh oh!

petschki commented Nov 25, 2025

Uh oh!

petschki commented Nov 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

stevepiercy commented Nov 26, 2025

Uh oh!

Uh oh!

stevepiercy commented Dec 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

petschki commented Dec 9, 2025

Uh oh!

stevepiercy commented Jan 14, 2026

Uh oh!

MrTango commented Jan 15, 2026

Uh oh!

petschki commented Jan 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

erral commented Jan 15, 2026

Uh oh!

yurj commented Jan 15, 2026

Uh oh!

stevepiercy commented Jan 15, 2026

Uh oh!

petschki commented Jan 15, 2026

Uh oh!

davisagli left a comment

Choose a reason for hiding this comment

Uh oh!

davisagli Feb 20, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

erral commented Apr 16, 2026

Uh oh!

erral left a comment

Choose a reason for hiding this comment

Uh oh!

erral May 3, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

8 participants

stevepiercy commented Nov 6, 2024 •

edited

Loading

petschki commented Nov 25, 2025 •

edited

Loading

stevepiercy commented Dec 8, 2025 •

edited

Loading

petschki commented Jan 15, 2026 •

edited

Loading