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

[stevepiercy]

• 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

See #1748 (comment)

Closes #1754.

Ping @petschki to take it from here.

---

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

[stevepiercy]

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]

@stevepiercy will have a look at this.

[petschki]

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]

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]

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]

@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!

[petschki]

@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]

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]

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]

@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]

@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]

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]

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?

1. Create a backend add-on only.
2. 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]

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