From b498fdea65ff663b3333446d323150c6518eaae4 Mon Sep 17 00:00:00 2001 From: Marius Storhaug Date: Sun, 9 Aug 2026 11:50:01 +0200 Subject: [PATCH 1/3] docs: add module development orchestration guide Document parent and child session coordination, draft PR targeting, integration, and release readiness for substantial module work.\n\nCo-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- .../module-development-orchestration.md | 141 ++++++++++++++++++ 1 file changed, 141 insertions(+) create mode 100644 docs/content/guides/module-development-orchestration.md diff --git a/docs/content/guides/module-development-orchestration.md b/docs/content/guides/module-development-orchestration.md new file mode 100644 index 00000000..845a65bf --- /dev/null +++ b/docs/content/guides/module-development-orchestration.md @@ -0,0 +1,141 @@ +--- +title: Module development orchestration +description: Coordinate substantial module work across an orchestrator session and narrowly scoped child sessions, then integrate it safely for release. +--- + +# Module development orchestration + +Substantial module work is easier to review and integrate when it is split into +small, independently verifiable changes. Use one parent (orchestrator) session +to own the plan and integration branch, and use narrowly scoped child sessions +for the work that can proceed independently. + +This complements [Module bootstrap](../get-started/module-bootstrap.md). During +bootstrap, the shared branch is an **integration branch** for the load-bearing +core. For a larger change to an existing module, it is usually a **release +branch** representing the intended release. In both cases, child pull requests +target the shared branch and the parent owns the pull request to `main`. + +## Roles and boundaries + +### Parent or orchestrator session + +The orchestrator: + +- defines the outcome, boundaries, dependencies, and acceptance criteria +- creates the integration or release branch and its draft pull request to + `main` +- gives each child one reviewable unit of work and the branch it must target +- keeps shared design decisions, naming, and cross-cutting changes coherent +- reviews each child pull request, runs the relevant validation, and integrates + it into the shared branch +- owns release readiness and the final pull request to `main` + +The orchestrator coordinates the work; it does not become a second place where +the implementation is silently changed. Changes outside a child's scope should +become a new child task or an explicitly recorded decision. + +### Child session + +A child session owns one cohesive change, such as one public function and its +tests, one documentation page, or one focused fix. A child should be able to +describe its change without referring to unrelated planned work. + +Each child: + +1. starts from the shared integration or release branch +2. opens a **draft pull request** targeting that branch, not `main` +3. implements and validates only its assigned scope +4. updates the documentation and tests required by that scope +5. reports the result to the orchestrator before asking for integration + +Use the repository's normal [branching and merging +practice](https://msx.no/docs/Ways-of-Working/Branching-and-Merging/) and the +shared [workflow](https://msx.no/docs/Ways-of-Working/Workflow/) for the +ordinary branch, draft PR, implementation, test, and review loop. This page +only describes how to coordinate several such changes. + +## Coordination protocol + +### Give every child a complete handoff + +The orchestrator's handoff should include: + +- the user-visible outcome and the exact in-scope files or capability +- the base branch and the child pull request's target branch +- dependencies on other children, including what is deliberately out of scope +- the relevant [module + standards](../reference/module-development-foundations.md), test guidance, + and existing implementation to follow +- the validation expected before the child reports completion +- the orchestrator session's identifier or communication channel + +If the child discovers a missing prerequisite or a conflicting design choice, +it should stop at that boundary and report it rather than expanding its scope +silently. + +### Require a useful completion report + +The child reports: + +- the draft pull request URL and target branch +- what changed and what was intentionally left out +- the tests, lint, documentation build, or other validation that ran, including + failures +- decisions or risks the orchestrator must review +- follow-up issues for work that does not belong in the child pull request + +The orchestrator treats this as input to review, not as a substitute for +review. Read the diff, verify the acceptance criteria, and run the smallest +relevant checks before merging. Use +[Validating before review](validating-before-review.md) for the PSModule +specific validation pass. + +### Integrate deliberately + +Merge children into the shared branch only after their checks and review are +complete. Integrate independent children in any order. For dependent work, +either wait for the prerequisite to merge or make the dependency explicit in a +stacked branch arrangement; do not make a child appear independent by copying +unreviewed changes. + +Keep the shared branch buildable. Resolve conflicts in the orchestrator's +context, rerun affected checks after integration, and record any cross-cutting +decision in the relevant pull request or issue. + +## Release readiness + +Keep the parent pull request to `main` in draft until the shared branch is a +coherent release candidate. Before marking it ready, confirm: + +- every child pull request is merged, closed with a documented reason, or + explicitly deferred with a follow-up issue +- the integrated branch passes the applicable build, test, lint, and + documentation checks +- the final tree still follows + [Structuring your module](structuring-your-module.md), the module + [repository standard](../reference/repository-standard.md), and the + [test specification](../reference/test-specification.md) +- user-facing documentation, examples, and generated-help inputs describe the + integrated behavior +- the release pull request records the outcome, links the child pull requests, + and identifies related issues without claiming unrelated work +- the version and prerelease intent match + [Versioning and releases](versioning-and-releases.md) + +If the branch is not ready, keep the parent pull request in draft and create +another focused child task or follow-up issue. Once it is ready, follow [Your +first release](../get-started/your-first-release.md) and the canonical MSX +[definition of ready for review](https://msx.no/docs/Ways-of-Working/Definition-of-Ready-and-Done/#definition-of-ready-for-review). + +## Relationship to other work + +- Use [Module bootstrap](../get-started/module-bootstrap.md) when a new module + needs a load-bearing core before its first release. +- Use a release branch for a larger post-release effort, as described in + [Principles and practices](../specification/principles-and-practices.md). +- Use an ordinary topic branch for a self-contained change that does not need + coordination across several child sessions. +- Use a stacked pull request only when the changes genuinely depend on one + another; see [MSX branching and + merging](https://msx.no/docs/Ways-of-Working/Branching-and-Merging/). From 45307971ee6229c34e9e729da01f2d14e9c060cf Mon Sep 17 00:00:00 2001 From: Marius Storhaug Date: Sun, 9 Aug 2026 11:50:30 +0200 Subject: [PATCH 2/3] docs: link orchestration guide Add the orchestration guide to the documentation landing page and Zensical navigation.\n\nCo-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- docs/content/index.md | 1 + docs/zensical.toml | 1 + 2 files changed, 2 insertions(+) diff --git a/docs/content/index.md b/docs/content/index.md index 8e126e11..9e4e42da 100644 --- a/docs/content/index.md +++ b/docs/content/index.md @@ -38,6 +38,7 @@ Task-oriented deep dives into the pipeline's functionality. | [Skipping framework tests](guides/skipping-framework-tests.md) | Skip individual framework tests on a per-file basis. | | [Versioning and releases](guides/versioning-and-releases.md) | Label-driven versioning, prereleases, and what a release produces. | | [Validating before review](guides/validating-before-review.md) | The PSModule validation pass before a draft pull request is marked ready. | +| [Module development orchestration](guides/module-development-orchestration.md) | Coordinate substantial work across an orchestrator session and narrowly scoped child sessions. | ## Reference diff --git a/docs/zensical.toml b/docs/zensical.toml index cdd222bf..a5728af9 100644 --- a/docs/zensical.toml +++ b/docs/zensical.toml @@ -33,6 +33,7 @@ nav = [ {"Skipping framework tests" = "guides/skipping-framework-tests.md"}, {"Versioning and releases" = "guides/versioning-and-releases.md"}, {"Validating before review" = "guides/validating-before-review.md"}, + {"Module development orchestration" = "guides/module-development-orchestration.md"}, ]}, {"Reference" = [ {"Module development foundations" = "reference/module-development-foundations.md"}, From a539cc0003e5dfe71e39dc28e4cad2d3ea10f16a Mon Sep 17 00:00:00 2001 From: Marius Storhaug Date: Fri, 4 Sep 2026 20:47:40 +0200 Subject: [PATCH 3/3] docs: align orchestration guidance with trunk based flow Limit integration branches to module bootstrap, align existing-module guidance with the repository trunk-based development standard, and update the guidance-source link after the documentation repository migration.\n\nCo-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- .../module-development-orchestration.md | 58 ++++++++++--------- docs/content/reference/guidance-scripts.md | 2 +- 2 files changed, 32 insertions(+), 28 deletions(-) diff --git a/docs/content/guides/module-development-orchestration.md b/docs/content/guides/module-development-orchestration.md index 845a65bf..cdb029c1 100644 --- a/docs/content/guides/module-development-orchestration.md +++ b/docs/content/guides/module-development-orchestration.md @@ -7,14 +7,15 @@ description: Coordinate substantial module work across an orchestrator session a Substantial module work is easier to review and integrate when it is split into small, independently verifiable changes. Use one parent (orchestrator) session -to own the plan and integration branch, and use narrowly scoped child sessions -for the work that can proceed independently. +to own the plan and integration, and use narrowly scoped child sessions for the +work that can proceed independently. This complements [Module bootstrap](../get-started/module-bootstrap.md). During bootstrap, the shared branch is an **integration branch** for the load-bearing -core. For a larger change to an existing module, it is usually a **release -branch** representing the intended release. In both cases, child pull requests -target the shared branch and the parent owns the pull request to `main`. +core. For an existing module, follow the repository's +[trunk-based development](../specification/principles-and-practices.md#trunk-based-development) +default: child pull requests use short-lived branches and target `main`. +Use a stacked pull request only when a dependency requires it. ## Roles and boundaries @@ -23,13 +24,13 @@ target the shared branch and the parent owns the pull request to `main`. The orchestrator: - defines the outcome, boundaries, dependencies, and acceptance criteria -- creates the integration or release branch and its draft pull request to - `main` +- creates the bootstrap integration branch and its draft pull request to + `main` when the module needs one - gives each child one reviewable unit of work and the branch it must target - keeps shared design decisions, naming, and cross-cutting changes coherent - reviews each child pull request, runs the relevant validation, and integrates it into the shared branch -- owns release readiness and the final pull request to `main` +- owns release readiness for the coordinated change set The orchestrator coordinates the work; it does not become a second place where the implementation is silently changed. Changes outside a child's scope should @@ -43,8 +44,10 @@ describe its change without referring to unrelated planned work. Each child: -1. starts from the shared integration or release branch -2. opens a **draft pull request** targeting that branch, not `main` +1. starts from `main`, or from the bootstrap integration branch when one is + required +2. opens a **draft pull request** targeting `main`, or the bootstrap integration + branch when one is required 3. implements and validates only its assigned scope 4. updates the documentation and tests required by that scope 5. reports the result to the orchestrator before asking for integration @@ -93,20 +96,22 @@ specific validation pass. ### Integrate deliberately -Merge children into the shared branch only after their checks and review are -complete. Integrate independent children in any order. For dependent work, -either wait for the prerequisite to merge or make the dependency explicit in a -stacked branch arrangement; do not make a child appear independent by copying -unreviewed changes. +Merge children only after their checks and review are complete. Merge +independent children into `main` in any order. For dependent work, either wait +for the prerequisite to merge or make the dependency explicit in a stacked +branch arrangement; do not make a child appear independent by copying +unreviewed changes. During bootstrap, merge children into the integration +branch, then merge that branch to `main` when the load-bearing core is ready. -Keep the shared branch buildable. Resolve conflicts in the orchestrator's -context, rerun affected checks after integration, and record any cross-cutting -decision in the relevant pull request or issue. +Keep `main` or the bootstrap integration branch buildable. Resolve conflicts in +the orchestrator's context, rerun affected checks after integration, and record +any cross-cutting decision in the relevant pull request or issue. ## Release readiness -Keep the parent pull request to `main` in draft until the shared branch is a -coherent release candidate. Before marking it ready, confirm: +Release readiness is a property of the integrated change, not a reason to keep +a long-lived release branch. Before marking a bootstrap integration pull +request ready, or reporting a coordinated trunk-based change complete, confirm: - every child pull request is merged, closed with a documented reason, or explicitly deferred with a follow-up issue @@ -118,12 +123,13 @@ coherent release candidate. Before marking it ready, confirm: [test specification](../reference/test-specification.md) - user-facing documentation, examples, and generated-help inputs describe the integrated behavior -- the release pull request records the outcome, links the child pull requests, - and identifies related issues without claiming unrelated work +- the parent or coordinating pull request records the outcome, links the child + pull requests when one exists, and identifies related issues without claiming + unrelated work - the version and prerelease intent match [Versioning and releases](versioning-and-releases.md) -If the branch is not ready, keep the parent pull request in draft and create +If the change is not ready, keep the relevant pull request in draft and create another focused child task or follow-up issue. Once it is ready, follow [Your first release](../get-started/your-first-release.md) and the canonical MSX [definition of ready for review](https://msx.no/docs/Ways-of-Working/Definition-of-Ready-and-Done/#definition-of-ready-for-review). @@ -132,10 +138,8 @@ first release](../get-started/your-first-release.md) and the canonical MSX - Use [Module bootstrap](../get-started/module-bootstrap.md) when a new module needs a load-bearing core before its first release. -- Use a release branch for a larger post-release effort, as described in - [Principles and practices](../specification/principles-and-practices.md). -- Use an ordinary topic branch for a self-contained change that does not need - coordination across several child sessions. +- For an existing module, use short-lived topic branches targeting `main`, as + described in [Principles and practices](../specification/principles-and-practices.md). - Use a stacked pull request only when the changes genuinely depend on one another; see [MSX branching and merging](https://msx.no/docs/Ways-of-Working/Branching-and-Merging/). diff --git a/docs/content/reference/guidance-scripts.md b/docs/content/reference/guidance-scripts.md index 745a7ce0..7f3d8bd3 100644 --- a/docs/content/reference/guidance-scripts.md +++ b/docs/content/reference/guidance-scripts.md @@ -28,4 +28,4 @@ Run an individual script only when its scenario is suitable for the local enviro ## Maintenance -The files were imported byte-for-byte from [`PSModule/docs/guidance`](https://github.com/PSModule/docs/tree/main/guidance). When that published set changes, import the complete current file from its Git blob into this directory and preserve its contents. Keep this index synchronized with the directory so users can discover every available script. +The files are maintained in the [`guidance` directory](https://github.com/PSModule/Process-PSModule/tree/main/guidance). When that published set changes, import the complete current file from its Git blob into this directory and preserve its contents. Keep this index synchronized with the directory so users can discover every available script.