You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 6744ca2
Browse filesBrowse the repository at this point in the historyBrowse files
description: Coordinate substantial module work across an orchestrator session and narrowly scoped child sessions, then integrate it safely for release.
3
+
description: Coordinate scoped module changes through an orchestrator, child sessions, and verified integration.
4
4
---
5
5
6
6
# Module development orchestration
7
7
8
-
Substantial module work is easier to review and integrate when it is split into
9
-
small, independently verifiable changes. Use one parent (orchestrator) session
10
-
to own the plan and integration, and use narrowly scoped child sessions for the
11
-
work that can proceed independently.
8
+
Coordinate module work as small, independently verifiable changes. Use one
9
+
parent (orchestrator) session for the plan and integration. Assign independent
10
+
work to narrowly scoped child sessions.
12
11
13
-
This complements [Module bootstrap](../get-started/module-bootstrap.md). During
14
-
bootstrap, the shared branch is an **integration branch**for the load-bearing
15
-
core. For an existing module, follow the repository's
12
+
During [Module bootstrap](../get-started/module-bootstrap.md), the shared
13
+
**integration branch**holds the load-bearing core. For an existing module,
Copy file name to clipboardExpand all lines: docs/content/guides/validating-before-review.md
+32-31Lines changed: 32 additions & 31 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,88 +1,89 @@
1
1
---
2
2
title: Validating before review
3
-
description: PSModule-specific validation checks that extend the shared MSXOrg Build/Implement workflow step before a draft pull request is marked ready.
3
+
description: Validate a module change against design, documentation, and PowerShell requirements before independent review.
4
4
---
5
5
6
6
# Validating before review
7
7
8
-
Use this page after scaffolding a module change or implementing a function and before you finish self-review or mark a draft pull request ready. It extends the shared MSXOrg [Workflow Build step](https://msx.no/docs/Ways-of-Working/Workflow/#build) and [Implement guidance](https://msx.no/docs/Ways-of-Working/Workflow-Stages/Implement/) with the PSModule-specific validation checks that module repositories must pass.
8
+
Use this sequence after you scaffold a module change or implement a function. Run it before you complete self-review or mark a draft pull request ready. It extends the shared MSXOrg [Workflow Build step](https://msx.no/docs/Ways-of-Working/Workflow/#build) and [Implement guidance](https://msx.no/docs/Ways-of-Working/Workflow-Stages/Implement/). Module repositories must satisfy these PSModule-specific validation requirements.
9
9
10
-
Do not repeat the shared workflow here. Follow the shared branch → draft PR → implement → test → self-review loop first, then run this PSModule pass to confirm the change still fits the module's design, documentation, and PowerShell standards.
10
+
Follow the shared branch → draft PR → implement → test → self-review loop first. Then run this author-side validation sequence for module design, documentation, and PowerShell standards.
11
11
12
12
## Validation sequence
13
13
14
14
1.**Module design alignment**
15
15
16
-
Confirm that the change fits the module's archetype and the module-specific design rules before reviewing individual files.
16
+
Before you review individual files, make sure that the change fits the module's archetype and design rules.
17
17
18
-
Check:
18
+
Make sure that:
19
19
20
-
- the module still follows the right archetype from [Module types](../reference/module-types.md)
21
-
- the change respects the layout, private-helper boundaries, context rules, and SOLID guidance in [PowerShell module standard](../reference/powershell-module-standard.md)
20
+
- the module follows the applicable archetype from [Module types](../reference/module-types.md)
21
+
- the change follows the layout, private-helper boundaries, context rules, and SOLID guidance in [PowerShell module standard](../reference/powershell-module-standard.md)
22
22
- the function belongs in this module instead of a different module, a shared helper, or a follow-up issue
23
23
24
-
A human contributor or agent should be able to explain why this change belongs in this module, in this shape, without inventing new local rules.
24
+
A contributor or agent should be able to explain why this change and its design belong in this module. The explanation should not introduce local rules.
25
25
26
26
2.**Module documentation**
27
27
28
-
Confirm that the repository-level and group-level documentation still matches the delivered behavior.
28
+
Make sure that the repository-level and group-level documentation describes the delivered behavior.
29
29
30
-
Check:
30
+
Make sure that:
31
31
32
-
-`README.md`still answers the start-page questions and reflects any user-visible behavior, prerequisites, or setup changes from [Repository Standard](../reference/repository-standard.md#readme-default)
33
-
- the relevant public command-group overview page (`src/functions/public/<Group>/<Group>.md`) exists or is updated when the change affects that group's purpose or usage, per[PowerShell module standard](../reference/powershell-module-standard.md#repository-layout)
34
-
-any module-level documentation under `docs/` or other published surfaces is updated when the change adds or changes guidance that should not live only in comment-based help
32
+
-`README.md` answers the start-page questions and reflects user-visible behavior, prerequisites, or setup changes from [Repository Standard](../reference/repository-standard.md#readme-default)
33
+
- the relevant public command-group overview page (`src/functions/public/<Group>/<Group>.md`) exists or reflects changes to that group's purpose or usage, as required by[PowerShell module standard](../reference/powershell-module-standard.md#repository-layout)
34
+
- module-level documentation under `docs/` or other published surfaces includes guidance that should not appear only in comment-based help
35
35
36
-
If the change teaches the user something new, confirm that the user can discover it from the published documentation surfaces, not only from the diff.
36
+
If the change affects user guidance, make sure that users can find it in published documentation, not only the diff.
37
37
38
38
3.**Function structure**
39
39
40
-
Confirm that each changed function still follows the expected repository anatomy.
40
+
Make sure that each changed function follows the repository layout.
41
41
42
-
Check:
42
+
Make sure that:
43
43
44
44
- public functions live under `src/functions/public/<Group>/` and private helpers live under `src/functions/private/<Group>/`
45
45
- file placement, grouping, and exported surface match [Structuring your module](structuring-your-module.md) and the layout rules in [PowerShell module standard](../reference/powershell-module-standard.md#repository-layout)
46
46
- there are no nested helper functions, multi-function files, or naming shortcuts that break the "one declaration per file" rule
47
47
48
-
This step is about shape, not behavior: the goal is that a reader or tool can find the module surface and its helpers exactly where PSModule expects them.
48
+
This step concerns file layout, not function behavior. The layout lets readers and tools locate the module's public functions and private helpers.
49
49
50
50
4.**Function documentation**
51
51
52
-
Confirm that every changed function carries complete comment-based help and that the help matches the implementation contract.
52
+
Make sure that every changed function has complete comment-based help that matches the implementation contract.
53
53
54
-
Check:
54
+
Make sure that:
55
55
56
56
- comment-based help is present for every changed function, including private helpers
57
57
- help sections, examples, `.INPUTS`, `.OUTPUTS`, and parameter documentation match the function contract from [MSX PowerShell Functions](https://msx.no/docs/Coding-Standards/PowerShell/Functions/)
58
58
- every public function has a first `.LINK` entry using an absolute HTTPS URL whose path matches the generated command documentation path
59
-
- public-function links and usage examples are current enough that generated documentation will stay accurate
59
+
- public-function links resolve and usage examples match the implemented parameters and outputs
60
60
61
-
Do not treat help as optional cleanup. In PSModule repositories, the function help is part of the delivered behavior.
61
+
Function help is part of the delivered behavior in PSModule repositories. Do not defer help as optional cleanup.
62
62
63
63
5.**PowerShell best practices**
64
64
65
-
Confirm that the implementation still reads like idiomatic PowerShell after the mechanical checks pass.
65
+
After the mechanical checks pass, review the implementation against the PowerShell standards.
66
66
67
-
Check:
67
+
Make sure that:
68
68
69
69
- advanced-function structure, parameter typing and validation, `ShouldProcess`, output behavior, and error handling align with [MSX PowerShell](https://msx.no/docs/Coding-Standards/PowerShell/) and [MSX PowerShell Functions](https://msx.no/docs/Coding-Standards/PowerShell/Functions/)
70
-
- the code also satisfies the PSModule-specific conventions in [PowerShell module standard](../reference/powershell-module-standard.md), especially around private helpers, context handling, and repository layout
71
-
- PSScriptAnalyzer warnings are addressed or intentionally justified, but review does not stop there; also look for awkward parameter design, leaky transport details, non-idiomatic output, or code that technically passes lint but is not good PowerShell
70
+
- the code satisfies the PSModule-specific conventions in [PowerShell module standard](../reference/powershell-module-standard.md), including private helpers, context handling, and repository layout
71
+
- PSScriptAnalyzer warnings have fixes or intentional justifications
72
72
73
-
PSScriptAnalyzer is part of the validation loop, not the whole loop.
73
+
Do not limit the review to PSScriptAnalyzer. Also examine parameter design, exposed transport details, output behavior, and deviations from PowerShell conventions, even when lint passes.
74
74
75
75
6.**Coding standards alignment**
76
76
77
-
Run one final cross-check against the shared MSX coding standards before leaving self-review.
77
+
Before you complete self-review, compare the change with the shared MSX coding standards.
78
78
79
-
Check:
79
+
Make sure that:
80
80
81
81
- naming, documentation, error handling, testing expectations, and security posture align with the relevant pages under [MSX Coding Standards](https://msx.no/docs/Coding-Standards/)
82
-
- the change follows the shared "written once, referenced everywhere" rule by linking canonical guidance instead of copying it into local docs or code comments, as described in [Agentic Development](https://msx.no/docs/Capabilities/agentic-development/)
83
-
- the draft PR description, issue progress, and any follow-up issues reflect what actually shipped and what still belongs out of scope
82
+
- the change follows the shared "written once, referenced everywhere" rule from [Agentic Development](https://msx.no/docs/Capabilities/agentic-development/)
83
+
- local documentation and code comments link to canonical guidance instead of copying it
84
+
- the draft PR description, issue progress, and follow-up issues describe the delivered change and its exclusions
84
85
85
-
This is the last author-side gate before a PSModule draft PR is ready for independent review.
86
+
This completes the author-side validation before independent review of a PSModule draft PR.
0 commit comments