Skip to content

Improve the documentation: new guides, corrections, and tested samples - #14

Merged
ericof merged 15 commits into
mainfrom
docs/review-followup
Sep 14, 2026
Merged

ericof merged 15 commits into
mainfrom
docs/review-followup

Conversation

@ericof

@ericof ericof commented Sep 14, 2026

Copy link
Copy Markdown
Member

Summary

A follow-up to a review of the documentation.
Every claim this PR adds or changes is backed by a test or a source reference, and every new code sample runs in the test suite.
The package's behavior does not change: the only changes to src are two docstrings.

New pages

  • How to make one workflow react to another: a guard that reads another workflow's state through portal_workflow.getInfoFor(..., wf_id=...), and an IAfterTransitionEvent subscriber that transitions another workflow. Guard expressions run as restricted Python and cannot import collective.multiworkflow.api; the page warns about it.
  • How to troubleshoot additional workflows: seven symptoms, each with its cause, a check, and the fix.
  • About when an additional workflow fits: membership, translation status, and records retention, and the signs of a problem that calls for something else.
  • Compatibility: release status, the Plone, Python, and Volto versions CI tests, what Classic UI shows, the changelogs, and where each package is published. The home page gains a status line linking to it.

Corrections

  • The tutorial's workflow definition did not import. DCWorkflow requires before_script and after_script on every transition, and the action attribute it used is ignored, so its transitions would never have been offered to users. The composing-workflow guide's fragments had the same problems.
  • Contribution order across behaviors is the reverse of the order the type lists the behaviors in, not the registration order the concept page stated.
  • A transition id shared by two workflows is executed in the first workflow that can execute it from its current state, not the first that defines it. Corrected in four pages and in the owning_workflow and @workflow serializer docstrings.
  • Enabling a behavior on a type with content neither reindexes workflow_states nor applies the contributed workflow's role mappings. Documented, with the two repair calls.
  • The install guide's verification step; the REST API reference's compatibility tables (unchanged, added, changed), with the content serializer patch disclosed at the top of its section; a plone.api interop table; which shadow applies when two Volto add-ons shadow the same component.
  • Prose: closing sentences that added nothing are gone, and the tutorial links the facts it used before introducing them. The badges moved off the documentation home page; the README gains a documentation badge.

Tests

New tests pin down the documented behavior:

  • tests/demo/test_behavior_enabled_on_existing_content.py
  • tests/chain/test_contribution_order.py
  • tests/api/test_plone_api_interop.py
  • tests/classicui/test_classic_ui.py

And the samples of the pages:

  • tests/docs/test_react_to_another_workflow.py and tests/docs/test_tutorial.py load the pages' workflow XML through DCWorkflow's own parser and their ZCML through xmlconfig, verbatim.
  • tests/docs/test_troubleshoot.py runs each check on content where it passes and on content set up to fail it.

Checks

  • Backend: 339 passed. Frontend: 107 passed.
  • Documentation: builds with warnings as errors; Vale 0 errors; linkcheck 0 broken.

Screenshots of the add-on in use are tracked separately in #13.

Verify, rather than assume, the claims two documentation reviews made
about the package:

- enabling a participating behavior on a type with content lets existing
  objects read the contributed workflow's initial state, but neither
  reindexes workflow_states nor applies the workflow's permission map;
- several behaviors' workflows are appended in the reverse of the order
  the behaviors are listed on the type, whatever the registration order;
- plone.api's get_state takes no workflow_id, its transition reaches a
  unique id of an additional workflow, and to_state cannot reach an
  additional workflow's state;
- Classic UI's State menu mixes every workflow's transitions, and its
  history viewlet shows the primary workflow only;
- a guard can read another workflow through portal_workflow.getInfoFor
  with wf_id but cannot import collective.multiworkflow.api, and an
  IAfterTransitionEvent subscriber can transition another workflow.
The concept page said several behaviors' workflows are concatenated in
registration order. Measured in tests/chain/test_contribution_order.py,
they are appended in the reverse of the order the behaviors are listed
on the type, whatever the registration order. Document the rule in the
ZCML reference, with its cause, and point the concept pages and the
declaration guide at it.

Enabling a participating behavior on a type with content leaves existing
objects unindexed under the new workflow and without its permission map
(tests/demo/test_behavior_enabled_on_existing_content.py). Explain why
in the concept page, and add the repair step to the declaration guide.
The page opened by calling every change additive, while its own table
listed the narrowed top-level transitions list among the unchanged
rows. Split the table into unchanged, added and changed payloads, state
the narrowing as the one change to an existing key and who it affects,
and say so in the introduction.

Move the disclosure that plone.restapi's content serializer is patched
from a trailing note to an important admonition at the top of its
section, note that the demo's bare transition ids predate the advice to
prefix them, and point the chain order sentence at the ZCML reference.
@ericof
ericof merged commit 740d6d8 into main Sep 14, 2026
20 checks passed
@ericof
ericof deleted the docs/review-followup branch September 14, 2026 00:58
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant