Repository navigation
Improve the documentation: new guides, corrections, and tested samples - #14
Merged
Merged
Conversation
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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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
srcare two docstrings.New pages
portal_workflow.getInfoFor(..., wf_id=...), and anIAfterTransitionEventsubscriber that transitions another workflow. Guard expressions run as restricted Python and cannot importcollective.multiworkflow.api; the page warns about it.Corrections
before_scriptandafter_scripton every transition, and theactionattribute it used is ignored, so its transitions would never have been offered to users. The composing-workflow guide's fragments had the same problems.owning_workflowand@workflowserializer docstrings.workflow_statesnor applies the contributed workflow's role mappings. Documented, with the two repair calls.plone.apiinterop table; which shadow applies when two Volto add-ons shadow the same component.Tests
New tests pin down the documented behavior:
tests/demo/test_behavior_enabled_on_existing_content.pytests/chain/test_contribution_order.pytests/api/test_plone_api_interop.pytests/classicui/test_classic_ui.pyAnd the samples of the pages:
tests/docs/test_react_to_another_workflow.pyandtests/docs/test_tutorial.pyload the pages' workflow XML through DCWorkflow's own parser and their ZCML throughxmlconfig, verbatim.tests/docs/test_troubleshoot.pyruns each check on content where it passes and on content set up to fail it.Checks
Screenshots of the add-on in use are tracked separately in #13.