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

stevepiercy · 2026-05-13T08:32:54Z

Description

This PR consists of purely editorial review changes against PR #1757.

I'll add comments where I need help from someone with technical knowledge.

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

…er introduction and overview section. Add Zope Management Interface as an alias to ZMI in the glossary and use it as a term.

…and older

- Rename to "Add-on properties", as these aren't issues at all. - Fix incorrect cross-reference link to custom installation steps - Rename `Import various` step to the step actually used, `setup_various` - Create a seealso directive to a really old web archive. Maybe remove this link?

- Move comment from code block to narrative text. - Use python lexer in code block.

- Clarify purpose of this section with definitive language instead of vague language. - `plone.app.testing` fix link to current documentation on GitHub. - Rename "Manually" section to explicit "Manual installation" - Use python lexer in code block. - Change `note` to `versionchanged` directive and clarify wording.

…files" section.

…placed first, and remove unnecessary and obsolete information.

- Improve grammar, syntax, and style - It's still way too confusing and needs technical help.

- Fix reference target syntax - Replace Management Interface with ZMI - Add a TODO to fix the autodoc warning.

stevepiercy

Reviewers, please see my comments where I got stuck and need your help. Thank you!

stevepiercy · 2026-05-13T08:35:35Z

+Creating relationships between ZCML and site-specific behavior is usually done using {doc}`layers </develop/plone/views/layers>`.
+ZCML directives, like viewlets and views, are registered to be active only on a certain layer using the `layer` attribute.


These changes were a best guess, based on the original text which made no sense to me.

stevepiercy · 2026-05-13T08:37:22Z

+### Multiple profiles

-When you have more than one profile in your add-on package, the add-ons control panel needs to decide which one to use when you install it.
+When you have more than one profile in your add-on package, the add-ons control panel decides which one to use when you install it.

-Since Plone 5.1, when there is a `default` profile, it is always used as the installation profile, regardless of other profile names.
+When there is a `default` profile, it's used as the installation profile, except when this `default` profile is marked in an `INonInstallable` utility.
+In this case, it's ignored, and Plone falls back to using the first profile sorted alphabetically by `name`.

-Exception: when this `default` profile is marked in an `INonInstallable` utility, it is ignored and Plone falls back to using the first from the alphabetical sorting.
-
-```{note}
-In Plone 5.0 and lower,
-the profiles are sorted alphabetically by id,
-and the first one is chosen.
-If you have profiles `base` and `default`,
-the `base` profile is installed.
-It is recommended to let `default` be the alphabetically first profile.
+```{versionchanged} Plone 5.1
+The profile `name` of `default` now takes precedence over the `name` of the first profile sorted alphabetically.
+In previous versions, the first profile sorted alphabetically by `name` was chosen without regard to the `default` name.
 ```


This entire section needs careful technical review. Please help by adding a comment.

stevepiercy · 2026-05-13T08:37:54Z

+```{seealso}
+[Custom import steps](https://web.archive.org/web/20151016163743/https://plone.293351.n2.nabble.com/indexing-of-content-created-by-Generic-Setup-td4454703.html)
+```


I have doubts that this ancient post is still helpful. Should I remove it?

stevepiercy · 2026-05-13T08:38:55Z

+-   A default GenericSetup XML profile, which is automatically run when the package is installed using the quick-installer.
+    The profile name is usually `default`.
+-   Other profiles, which the user may install using the ZMI {guilabel}`portal_setup` under the {guilabel}`Export` tab, or which can be manually enabled for unit tests.
+-   An `setup_various` step, which runs Python code every time the GenericSetup XML profile is installed.


Note that I renamed this from "Import various" because it didn't exist, so I made a best guess from the rest of the text.

stevepiercy · 2026-05-13T08:43:31Z

-Upgrade steps have a sort order in which they are executed. This used to be alphabetical sorting.
-
-When you had eleven upgrade steps, marked from 1 through 11, alphabetical sorting meant this order: 1, 10, 11, 2, 3, etc.
+## Metadata version numbers


For this section, see my comment from the original PR at #1757 (comment).

stevepiercy · 2026-05-13T08:43:56Z

 (genericsetup-custom-installer-code-label)=

-## Custom Installer Code (`setuphandlers.py`)
+## Custom installer code


For this section, see my comment from the original PR at #1757 (comment).

MrTango

LGTM

…docstrings in the Products.GenericSetup.rolemap module. ``` /documentation/venv/lib/python3.13/site-packages/Products/GenericSetup/rolemap.py:docstring of Products.GenericSetup.rolemap.importRolemap:9: ERROR: Unexpected indentation. [docutils] /documentation/venv/lib/python3.13/site-packages/Products/GenericSetup/rolemap.py:docstring of Products.GenericSetup.rolemap.importRolemap:19: WARNING: Definition list ends without a blank line; unexpected unindent. [docutils] ```

stevepiercy · 2026-05-13T11:29:19Z

 .. automodule:: Products.GenericSetup.rolemap
-  :members: importRolemap RolemapImportConfigurator
-
+   :members: importRolemap, RolemapImportConfigurator


The docstring in importRolemap is malformed. I opened a PR to fix it in zopefoundation/Products.GenericSetup#141.

Once that PR is merged and released, then the docs should be previewed and checked at https://plone6--2083.org.readthedocs.build/backend/generic-setup.html#Products.GenericSetup.rolemap.importRolemap.

Oops, it looks like we need an update in Plone as well. @mauritsvanrees would you please do the honors to bump Products.GenericSetup==5.1.0 to 5.2.0 for both 6.1.x and 6.2.x?

I have just bumped it in Plone 6.2 (see https://dist.plone.org/release/6.2-dev/)

But I can't do that for 6.1. It uses Products.GenericSetup 5.0.0. Updating this to 5.1 or later means we get a version with native namespaces, which we can't do in Plone 6.1.

Thanks @mauritsvanrees!

I expect that we'll have a 6.2 final release before this PR is merged, so I'll keep this comment open to remind me to check at that time.

stevepiercy added 14 commits May 12, 2026 15:44

Rewrite and restructure the GenericSetup documentation to have a prop…

98dfce6

…er introduction and overview section. Add Zope Management Interface as an alias to ZMI in the glossary and use it as a term.

Tidy up links

0b24fa2

Clean up Create a profile section

0bb47fe

Clean up Multiple profiles section, removing obsolete mention of 5.0 …

a485dce

…and older

Clean up "List available profiles"

72fbc5c

- Move comment from code block to narrative text. - Use python lexer in code block.

Add a versionchanged directive and clarify wording to "Multiple pro…

def7ca5

…files" section.

Grammar, MyST syntax, and style corrections

df98e97

Revise "Metadata version numbers" to modernize it to a best practice …

e866523

…placed first, and remove unnecessary and obsolete information.

Revise "Metadata version numbers" to modernize it to a best practice …

fc88c28

…placed first, and remove unnecessary and obsolete information.

Revise "Custom installer code"

f5a5e56

- Improve grammar, syntax, and style - It's still way too confusing and needs technical help.

- Clean up code comments

ca80a8e

- Fix reference target syntax - Replace Management Interface with ZMI - Add a TODO to fix the autodoc warning.

- Fix typos

a2afebd

github-project-automation Bot added this to Plone Documentation May 13, 2026

github-project-automation Bot moved this to New in Plone Documentation May 13, 2026

stevepiercy requested review from MrTango, davisagli, erral, mauritsvanrees, petschki and yurj and removed request for erral May 13, 2026 08:33

stevepiercy mentioned this pull request May 13, 2026

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

Open

stevepiercy commented May 13, 2026

View reviewed changes

MrTango approved these changes May 13, 2026

View reviewed changes

github-project-automation Bot moved this from New to Approved in Plone Documentation May 13, 2026

stevepiercy added 2 commits May 13, 2026 03:50

Fix reference target

9dd5dc3

Fix invalid XML syntax

800adcc

stevepiercy added 3 commits May 13, 2026 03:56

Fix invalid reference links

5975f46

stevepiercy mentioned this pull request May 13, 2026

Fix malformed docstring for rolemap.importRolemap zopefoundation/Products.GenericSetup#141

Merged

8 tasks

stevepiercy commented May 13, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Editorial review of Add Create a backend add-on section in the Developer guide with GenericSetup #1757#2083

Editorial review of Add Create a backend add-on section in the Developer guide with GenericSetup #1757#2083
stevepiercy wants to merge 19 commits into
dev-guide-create-a-backend-add-onfrom
dev-guide-create-a-backend-add-on-editorial

stevepiercy commented May 13, 2026 •

edited by github-actions Bot

Loading

Uh oh!

stevepiercy left a comment

Uh oh!

stevepiercy May 13, 2026

Uh oh!

stevepiercy May 13, 2026

Uh oh!

stevepiercy May 13, 2026

Uh oh!

stevepiercy May 13, 2026

Uh oh!

stevepiercy May 13, 2026

Uh oh!

stevepiercy May 13, 2026

Uh oh!

MrTango left a comment

Uh oh!

stevepiercy May 13, 2026

Uh oh!

stevepiercy May 13, 2026

Uh oh!

mauritsvanrees May 14, 2026

Uh oh!

stevepiercy May 15, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

		Creating relationships between ZCML and site-specific behavior is usually done using {doc}`layers </develop/plone/views/layers>`.
		ZCML directives, like viewlets and views, are registered to be active only on a certain layer using the `layer` attribute.

Uh oh!

Conversation

stevepiercy commented May 13, 2026 • edited by github-actions Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Uh oh!

stevepiercy left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

MrTango left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

stevepiercy commented May 13, 2026 •

edited by github-actions Bot

Loading