Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 21 additions & 0 deletions src/docs/Coding-Standards/GitHub-Actions.md
Original file line number Diff line number Diff line change
Expand Up @@ -514,6 +514,27 @@ appears.
`main.<ext>` sits at the action root for a single-file action, or under `src/`
as the entry point alongside the other modules.

### Name helper modules after the action

- **A helper module bundled inside an action is named after the action**, not
given a generic name. For a `publish-docs` action the module is
`publish-docs.Helpers` in `publish-docs.Helpers.psm1`, imported by path from
the entry script.
- **Why it matters:** every module imported during a job shares one session on
the runner. A generic name β€” `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 they can no longer be told
apart: module resolution is ambiguous, and unit tests that target a module by
name β€” mocking a command *inside* the module, say β€” fail because the framework
cannot choose which copy to patch.
- **An action-scoped name is unambiguous, mockable, and traceable.** It never
clashes, tests can address it by name, and it identifies the owning action in
loaded-module listings, errors, and stack traces.
- **The exception is a module published for sharing.** A helper whose whole
purpose is to be installed and imported by many actions keeps its shared,
stable name; only an action's *private* helper module is action-scoped.

## Toolchain

Two linters enforce this standard in CI, and their configuration is derived from
Expand Down
1 change: 1 addition & 0 deletions src/docs/Coding-Standards/PowerShell/Scripts.md
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,7 @@ $ErrorActionPreference = 'Stop'
## Rules

- **Name scripts `Verb-Noun.ps1`** to match the function convention.
- **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).
- **No side effects on load.** A script runs top to bottom when invoked; it should not do work merely by being dot-sourced.
- **Return objects**, so the script composes in a pipeline like any other command.

Expand Down