Skip to content

Commit 869c031

Browse files
πŸ“– [Docs]: Name GitHub Action helper modules after the action (#25)
Declares the standard from #24: a helper module bundled inside a GitHub Action is named after the action (`<action-name>.Helpers`), never a generic name like `Helpers`. ## Why Every module imported during a job shares one session on the runner. A generically named module (`Helpers`, `Utils`, `Common`) collides with a shared module of the same name (an ecosystem often installs a shared helper module that actions import by name) or with another action's helper loaded in the same job. Once two loaded modules share a name, module resolution is ambiguous and unit tests that mock a command *inside* the module by module name fail. Real example: PSModule/Resolve-PSModuleVersion#4. ## Changes - `Coding-Standards/GitHub-Actions.md` β€” new "Name helper modules after the action" subsection under "Extract non-trivial `run:` scripts into an action" (rule, rationale, and the shared-module carve-out). - `Coding-Standards/PowerShell/Scripts.md` β€” cross-reference bullet in Rules. ## Validation markdownlint, textlint terminology, codespell, link check, and index-drift check all pass locally. Closes #24. Ecosystem rollout across PSModule actions is tracked in PSModule/Process-PSModule#364.
1 parent 3e196a6 commit 869c031

2 files changed

Lines changed: 22 additions & 0 deletions

File tree

β€Žsrc/docs/Coding-Standards/GitHub-Actions.mdβ€Ž

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -514,6 +514,27 @@ appears.
514514
`main.<ext>` sits at the action root for a single-file action, or under `src/`
515515
as the entry point alongside the other modules.
516516

517+
### Name helper modules after the action
518+
519+
- **A helper module bundled inside an action is named after the action**, not
520+
given a generic name. For a `publish-docs` action the module is
521+
`publish-docs.Helpers` in `publish-docs.Helpers.psm1`, imported by path from
522+
the entry script.
523+
- **Why it matters:** every module imported during a job shares one session on
524+
the runner. A generic name β€” `Helpers`, `Utils`, `Common` β€” collides with a
525+
shared module of the same name (an ecosystem often installs a shared helper
526+
module that actions import by name) or with another action's helper loaded in
527+
the same job. Once two loaded modules share a name they can no longer be told
528+
apart: module resolution is ambiguous, and unit tests that target a module by
529+
name β€” mocking a command *inside* the module, say β€” fail because the framework
530+
cannot choose which copy to patch.
531+
- **An action-scoped name is unambiguous, mockable, and traceable.** It never
532+
clashes, tests can address it by name, and it identifies the owning action in
533+
loaded-module listings, errors, and stack traces.
534+
- **The exception is a module published for sharing.** A helper whose whole
535+
purpose is to be installed and imported by many actions keeps its shared,
536+
stable name; only an action's *private* helper module is action-scoped.
537+
517538
## Toolchain
518539

519540
Two linters enforce this standard in CI, and their configuration is derived from

β€Žsrc/docs/Coding-Standards/PowerShell/Scripts.mdβ€Ž

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -46,6 +46,7 @@ $ErrorActionPreference = 'Stop'
4646
## Rules
4747

4848
- **Name scripts `Verb-Noun.ps1`** to match the function convention.
49+
- **Name a helper module bundled inside a GitHub Action after the action** (`action-name.Helpers`), never a generic name like `Helpers` β€” a generic name collides with shared or sibling modules in the runner's shared session. See [GitHub Actions](../GitHub-Actions.md#name-helper-modules-after-the-action).
4950
- **No side effects on load.** A script runs top to bottom when invoked; it should not do work merely by being dot-sourced.
5051
- **Return objects**, so the script composes in a pipeline like any other command.
5152

0 commit comments

Comments
Β (0)