From 3f2ed56d7cd6e17d0d8a55b87d0e0adb34423689 Mon Sep 17 00:00:00 2001 From: Marius Storhaug Date: Wed, 4 Nov 2026 14:52:53 +0100 Subject: [PATCH 1/7] State reserved action descriptions directly --- .../Cleanup-PSModulePrereleases/action.yml | 6 +++--- .../actions/Get-PSModuleSettings/action.yml | 18 ++++++++++-------- .github/actions/Publish-PSModule/action.yml | 10 +++++----- .github/actions/Release-PSModule/action.yml | 14 +++++++------- .../actions/Resolve-PSModuleVersion/action.yml | 10 +++++----- 5 files changed, 30 insertions(+), 28 deletions(-) diff --git a/.github/actions/Cleanup-PSModulePrereleases/action.yml b/.github/actions/Cleanup-PSModulePrereleases/action.yml index e9ebcecb..d54d15a5 100644 --- a/.github/actions/Cleanup-PSModulePrereleases/action.yml +++ b/.github/actions/Cleanup-PSModulePrereleases/action.yml @@ -1,5 +1,5 @@ name: Cleanup-PSModulePrereleases -description: Cleanup prerelease GitHub releases associated with the current pull request branch. +description: Delete prerelease GitHub releases associated with the current pull request branch. author: PSModule inputs: @@ -16,11 +16,11 @@ inputs: required: false default: '' WhatIf: - description: If specified, the action will only log the changes it would make. + description: If specified, the action logs only the changes it would make. required: false default: 'false' WorkingDirectory: - description: The working directory where the script will run from. + description: Working directory for the script. required: false default: '.' diff --git a/.github/actions/Get-PSModuleSettings/action.yml b/.github/actions/Get-PSModuleSettings/action.yml index 1a209701..c39cccb0 100644 --- a/.github/actions/Get-PSModuleSettings/action.yml +++ b/.github/actions/Get-PSModuleSettings/action.yml @@ -1,5 +1,5 @@ name: Get-PSModuleSettings -description: Get settings for a PowerShell module workflow +description: Get settings for a PowerShell module workflow. author: PSModule branding: icon: settings @@ -10,7 +10,7 @@ inputs: description: Name of the module. required: false SettingsPath: - description: Path to the settings file (json, yaml/yml, or psd1) + description: Path to the settings file (json, yaml/yml, or psd1). required: false Debug: description: Enable debug output. @@ -21,21 +21,23 @@ inputs: required: false default: 'false' Version: - description: Specifies the version of the GitHub module to be installed. Accepts an exact version or a NuGet version range (for example '[1.2.0, 2.0.0)'). + description: Version of the GitHub module to install. The action accepts an exact version or a NuGet version range (for example '[1.2.0, 2.0.0)'). required: false Prerelease: description: Allow prerelease versions if available. required: false default: 'false' WorkingDirectory: - description: The working directory where the script will run from. + description: Working directory for the script. required: false default: ${{ github.workspace }} ImportantFilePatterns: description: | - Newline-separated list of regex patterns that identify important files. - Changes matching these patterns trigger build, test, and publish stages. - When set, fully replaces the defaults. + Newline-separated list of regular expression patterns that identify + important files. + Changes that match these patterns trigger build, test, and publish + stages. + When set, the list fully replaces the defaults. required: false default: | ^src/ @@ -43,7 +45,7 @@ inputs: outputs: Settings: - description: The complete settings object as JSON, including test suites + description: The complete settings object as JSON, including test suites. value: ${{ fromJson(steps.Get-PSModuleSettings.outputs.result).Settings }} runs: diff --git a/.github/actions/Publish-PSModule/action.yml b/.github/actions/Publish-PSModule/action.yml index d21604d1..51aa2181 100644 --- a/.github/actions/Publish-PSModule/action.yml +++ b/.github/actions/Publish-PSModule/action.yml @@ -7,26 +7,26 @@ inputs: description: Name of the module to publish. required: false ModulePath: - description: Path to the folder containing the / module subdirectory from Build-PSModule. + description: Path to the folder with the / module subdirectory from Build-PSModule. required: false default: .PSModule/module PSGALLERY_API_KEY: - description: PowerShell Gallery API Key. + description: PowerShell Gallery API key. required: true PullRequest: description: Normalized pull request context JSON from Get-PSModuleSettings. required: false default: '' WhatIf: - description: If specified, the action will only log the changes it would make, but will not publish the module. + description: If specified, the action logs only the changes it would make, but does not publish the module. required: false default: 'false' WorkingDirectory: - description: The working directory where the script will run from. + description: Working directory for the script. required: false default: '.' ArtifactName: - description: Name of the uploaded artifact to download. Must match the name used in the upstream upload-artifact step. + description: Name of the uploaded artifact to download. It must match the name used in the upstream upload-artifact step. required: false default: module diff --git a/.github/actions/Release-PSModule/action.yml b/.github/actions/Release-PSModule/action.yml index 33789546..ca1857b2 100644 --- a/.github/actions/Release-PSModule/action.yml +++ b/.github/actions/Release-PSModule/action.yml @@ -7,31 +7,31 @@ inputs: description: Name of the module to release. required: false ModulePath: - description: Path to the folder containing the / module subdirectory from Build-PSModule. + description: Path to the folder with the / module subdirectory from Build-PSModule. required: false default: .PSModule/module ArtifactName: - description: Name of the uploaded artifact to download. Must match the name used in the upstream upload-artifact step. + description: Name of the uploaded artifact to download. It must match the name used in the upstream upload-artifact step. required: false default: module WhatIf: - description: If specified, the action will only log the changes it would make, but will not actually create the release or upload artifacts. + description: If specified, the action logs only the changes it would make, but does not create the release or upload artifacts. required: false default: 'false' WorkingDirectory: - description: The working directory where the script will run from. + description: Working directory for the script. required: false default: '.' UsePRTitleAsReleaseName: - description: When enabled, uses the pull request title as the name for the GitHub release. If not set, the version string is used. + description: When enabled, the action uses the pull request title as the GitHub release name. If not set, it uses the version string. required: false default: 'false' UsePRBodyAsReleaseNotes: - description: When enabled, uses the pull request body as the release notes for the GitHub release. If not set, the release notes are auto-generated. + description: When enabled, the action uses the pull request body as the GitHub release notes. If not set, it auto-generates the release notes. required: false default: 'true' UsePRTitleAsNotesHeading: - description: When enabled along with UsePRBodyAsReleaseNotes, the release notes will begin with the pull request title as a H1 heading followed by the pull request body. The title will reference the pull request number. + description: When enabled with UsePRBodyAsReleaseNotes, the release notes start with the pull request title as an H1 heading. The pull request body follows the heading. The title references the pull request number. required: false default: 'true' ReleaseTag: diff --git a/.github/actions/Resolve-PSModuleVersion/action.yml b/.github/actions/Resolve-PSModuleVersion/action.yml index 5192f28f..708f7230 100644 --- a/.github/actions/Resolve-PSModuleVersion/action.yml +++ b/.github/actions/Resolve-PSModuleVersion/action.yml @@ -1,5 +1,5 @@ name: Resolve-PSModuleVersion -description: Resolves the next module version from settings, PR labels, GitHub releases, and the PowerShell Gallery. +description: Resolve the next module version from settings, PR labels, GitHub releases, and the PowerShell Gallery. author: PSModule branding: icon: tag @@ -10,10 +10,10 @@ inputs: description: The complete settings object as a JSON string (output of Get-PSModuleSettings). required: true Name: - description: Name of the module. When empty, the repository name is used. + description: Module name. When empty, the action uses the repository name. required: false WorkingDirectory: - description: The working directory where the script will run from. + description: Working directory for the script. required: false default: '.' Debug: @@ -25,11 +25,11 @@ inputs: required: false default: 'false' EventPath: - description: Path to the GitHub event JSON file. Defaults to the standard GitHub event path. Override for testing. + description: Path to the GitHub event JSON file. The default is the standard GitHub event path. Override for testing. required: false default: '' EventJson: - description: GitHub event payload as a JSON string. When set, overrides reading from the event file. Use for testing. + description: GitHub event payload as a JSON string. When set, this value overrides the event file. Use for testing. required: false default: '' From 0dd4f648d1a649ca81a7dd465c637ccb1ea25756 Mon Sep 17 00:00:00 2001 From: Marius Storhaug Date: Wed, 4 Nov 2026 14:54:44 +0100 Subject: [PATCH 2/7] Clarify settings and reusable workflow descriptions --- .../src/Settings.schema.json | 34 +++++++++---------- .github/workflows/AfterAll-ModuleLocal.yml | 7 ++-- .github/workflows/BeforeAll-ModuleLocal.yml | 7 ++-- .github/workflows/Plan.yml | 15 ++++---- .github/workflows/Test-ModuleLocal.yml | 7 ++-- .github/workflows/workflow.yml | 27 +++++++++------ 6 files changed, 54 insertions(+), 43 deletions(-) diff --git a/.github/actions/Get-PSModuleSettings/src/Settings.schema.json b/.github/actions/Get-PSModuleSettings/src/Settings.schema.json index a51b90ac..25eb27da 100644 --- a/.github/actions/Get-PSModuleSettings/src/Settings.schema.json +++ b/.github/actions/Get-PSModuleSettings/src/Settings.schema.json @@ -11,7 +11,7 @@ }, "ImportantFilePatterns": { "type": "array", - "description": "Regex patterns that identify important files. Changes matching these patterns trigger build, test, and publish stages. Defaults to ['^src/', '^README\\.md$'] when not configured.", + "description": "Regular expression patterns that identify important files. Changes that match these patterns trigger build, test, and publish stages. When not configured, the defaults are ['^src/', '^README\\.md$'].", "items": { "type": "string", "minLength": 1 @@ -19,7 +19,7 @@ }, "Test": { "type": "object", - "description": "Test configuration settings", + "description": "Test configuration", "properties": { "Skip": { "type": "boolean", @@ -54,7 +54,7 @@ "properties": { "Skip": { "type": "boolean", - "description": "Skip test results collection" + "description": "Skip collection of test results" } } }, @@ -64,7 +64,7 @@ "properties": { "Skip": { "type": "boolean", - "description": "Skip code coverage collection" + "description": "Skip collection of code coverage" }, "PercentTarget": { "type": "number", @@ -74,7 +74,7 @@ }, "StepSummaryMode": { "type": "string", - "description": "Mode for displaying step summary" + "description": "Display mode for the step summary" } } } @@ -82,7 +82,7 @@ }, "Build": { "type": "object", - "description": "Build configuration settings", + "description": "Build configuration", "properties": { "Skip": { "type": "boolean", @@ -124,7 +124,7 @@ }, "Publish": { "type": "object", - "description": "Publish configuration settings", + "description": "Publish configuration", "properties": { "Module": { "type": "object", @@ -156,19 +156,19 @@ }, "MajorLabels": { "type": "string", - "description": "Comma-separated labels that trigger major version bump" + "description": "Comma-separated labels that trigger a major version bump" }, "MinorLabels": { "type": "string", - "description": "Comma-separated labels that trigger minor version bump" + "description": "Comma-separated labels that trigger a minor version bump" }, "PatchLabels": { "type": "string", - "description": "Comma-separated labels that trigger patch version bump" + "description": "Comma-separated labels that trigger a patch version bump" }, "IgnoreLabels": { "type": "string", - "description": "Comma-separated labels that prevent release" + "description": "Comma-separated labels that prevent a release" }, "PrereleaseLabels": { "type": "string", @@ -176,15 +176,15 @@ }, "UsePRTitleAsReleaseName": { "type": "boolean", - "description": "Use pull request title as the GitHub release name" + "description": "Use the pull request title as the GitHub release name" }, "UsePRBodyAsReleaseNotes": { "type": "boolean", - "description": "Use pull request body as the release notes content" + "description": "Use the pull request body as the release notes content" }, "UsePRTitleAsNotesHeading": { "type": "boolean", - "description": "Add pull request title as H1 heading in release notes" + "description": "Add the pull request title as an H1 heading in release notes" }, "ReleaseType": { "type": "string", @@ -203,7 +203,7 @@ "properties": { "Skip": { "type": "boolean", - "description": "Skip publishing the generated documentation site" + "description": "Skip publication of the generated documentation site" } } } @@ -211,7 +211,7 @@ }, "Linter": { "type": "object", - "description": "Linter configuration settings", + "description": "Linter configuration", "properties": { "Skip": { "type": "boolean", @@ -272,7 +272,7 @@ }, "Run": { "type": "null", - "description": "Deprecated. Runtime execution flags are now stored on each phase object." + "description": "Deprecated. Runtime execution flags are stored on each phase object." } }, "definitions": { diff --git a/.github/workflows/AfterAll-ModuleLocal.yml b/.github/workflows/AfterAll-ModuleLocal.yml index 7671605e..28260fee 100644 --- a/.github/workflows/AfterAll-ModuleLocal.yml +++ b/.github/workflows/AfterAll-ModuleLocal.yml @@ -5,9 +5,10 @@ on: secrets: TestData: description: | - Optional single-line JSON object with 'secrets' and 'variables' maps. Each entry is exposed - as an environment variable available to the AfterAll teardown script; 'secrets' values are - masked in the logs, 'variables' values are not. + Optional single-line JSON object with 'secrets' and 'variables' maps. + The workflow exposes each entry as an environment variable for the + AfterAll teardown script. It masks 'secrets' values in the logs but + does not mask 'variables' values. required: false inputs: Settings: diff --git a/.github/workflows/BeforeAll-ModuleLocal.yml b/.github/workflows/BeforeAll-ModuleLocal.yml index bd56f376..41d89801 100644 --- a/.github/workflows/BeforeAll-ModuleLocal.yml +++ b/.github/workflows/BeforeAll-ModuleLocal.yml @@ -5,9 +5,10 @@ on: secrets: TestData: description: | - Optional single-line JSON object with 'secrets' and 'variables' maps. Each entry is exposed - as an environment variable available to the BeforeAll setup script; 'secrets' values are - masked in the logs, 'variables' values are not. + Optional single-line JSON object with 'secrets' and 'variables' maps. + The workflow exposes each entry as an environment variable for the + BeforeAll setup script. It masks 'secrets' values in the logs but does + not mask 'variables' values. required: false inputs: Settings: diff --git a/.github/workflows/Plan.yml b/.github/workflows/Plan.yml index 0e0f1a7b..0c0613d3 100644 --- a/.github/workflows/Plan.yml +++ b/.github/workflows/Plan.yml @@ -33,25 +33,28 @@ on: default: false Version: type: string - description: Specifies the version of the GitHub module to be installed. The value must be an exact version. + description: Version of the GitHub module to install. The value must be an exact version. required: false default: '' Prerelease: type: boolean - description: Whether to use a prerelease version of the 'GitHub' module. + description: Use a prerelease version of the 'GitHub' module. required: false default: false WorkingDirectory: type: string - description: The path to the root of the repo. + description: Path to the repository root. required: false default: '.' ImportantFilePatterns: type: string description: | - Newline-separated list of regex patterns that identify important files. - Changes matching these patterns trigger build, test, and publish stages. - When set, fully replaces the defaults (^src/ and ^README\.md$). + Newline-separated list of regular expression patterns that identify + important files. + Changes that match these patterns trigger build, test, and publish + stages. + When set, the list fully replaces the defaults + (^src/ and ^README\.md$). required: false default: | ^src/ diff --git a/.github/workflows/Test-ModuleLocal.yml b/.github/workflows/Test-ModuleLocal.yml index a3945bad..6bd5cd81 100644 --- a/.github/workflows/Test-ModuleLocal.yml +++ b/.github/workflows/Test-ModuleLocal.yml @@ -5,9 +5,10 @@ on: secrets: TestData: description: | - Optional single-line JSON object with 'secrets' and 'variables' maps. Each entry is exposed - as an environment variable the module's Pester tests read via $env:; 'secrets' values - are masked in the logs, 'variables' values are not. + Optional single-line JSON object with 'secrets' and 'variables' maps. + The workflow exposes each entry as an environment variable that the + module's Pester tests read via $env:. It masks 'secrets' values + in the logs but does not mask 'variables' values. required: false inputs: Settings: diff --git a/.github/workflows/workflow.yml b/.github/workflows/workflow.yml index db9a0999..b7617833 100644 --- a/.github/workflows/workflow.yml +++ b/.github/workflows/workflow.yml @@ -14,22 +14,24 @@ on: required: true TestData: description: | - Optional single-line JSON object carrying all data the module test jobs + Optional single-line JSON object with all data the module test jobs (BeforeAll-ModuleLocal, Test-ModuleLocal, AfterAll-ModuleLocal) need, in two maps: { "secrets": { "NAME": "value", ... }, "variables": { "NAME": "value", ... } } - Every entry is exposed as an environment variable the module's Pester tests read via - $env:. Values under "secrets" are masked in the logs; values under "variables" are not. + The workflow exposes every entry as an environment variable that the + module's Pester tests read via $env:. + It masks values under "secrets" in the logs but does not mask values + under "variables". Build it from secrets. / vars. in the calling workflow (see the README). Keep it on a single line so GitHub registers one mask for the whole value. Omit it when the module needs no test data. The same keys are exported before BeforeAll-ModuleLocal, Test-ModuleLocal, and AfterAll-ModuleLocal run. If setup or teardown scripts see a missing - key, confirm the caller explicitly maps a TestData JSON value; secrets: inherit only passes + key, confirm the caller explicitly maps a TestData JSON value. secrets: inherit only passes an already-created TestData secret and does not build JSON from individual secrets. required: false inputs: SettingsPath: type: string - description: The path to the settings file. Settings in the settings file take precedence over the action inputs. + description: Path to the settings file. Settings in this file take precedence over the action inputs. required: false default: .github/PSModule.yml Debug: @@ -44,25 +46,28 @@ on: default: false Version: type: string - description: Specifies the version of the GitHub module to be installed. The value must be an exact version. + description: Version of the GitHub module to install. The value must be an exact version. required: false default: '' Prerelease: type: boolean - description: Whether to use a prerelease version of the 'GitHub' module. + description: Use a prerelease version of the 'GitHub' module. required: false default: false WorkingDirectory: type: string - description: The path to the root of the repo. + description: Path to the repository root. required: false default: '.' ImportantFilePatterns: type: string description: | - Newline-separated list of regex patterns that identify important files. - Changes matching these patterns trigger build, test, and publish stages. - When set, fully replaces the defaults (^src/ and ^README\.md$). + Newline-separated list of regular expression patterns that identify + important files. + Changes that match these patterns trigger build, test, and publish + stages. + When set, the list fully replaces the defaults + (^src/ and ^README\.md$). required: false default: | ^src/ From 668c4d55264854c46de446be25b7df5c69bbac54 Mon Sep 17 00:00:00 2001 From: Marius Storhaug Date: Wed, 4 Nov 2026 14:57:30 +0100 Subject: [PATCH 3/7] Keep WhatIf log-only effects explicit --- .github/actions/Cleanup-PSModulePrereleases/action.yml | 2 +- .github/actions/Publish-PSModule/action.yml | 2 +- .github/actions/Release-PSModule/action.yml | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/actions/Cleanup-PSModulePrereleases/action.yml b/.github/actions/Cleanup-PSModulePrereleases/action.yml index d54d15a5..1d3c0a19 100644 --- a/.github/actions/Cleanup-PSModulePrereleases/action.yml +++ b/.github/actions/Cleanup-PSModulePrereleases/action.yml @@ -16,7 +16,7 @@ inputs: required: false default: '' WhatIf: - description: If specified, the action logs only the changes it would make. + description: If specified, the action only logs the changes it would make. required: false default: 'false' WorkingDirectory: diff --git a/.github/actions/Publish-PSModule/action.yml b/.github/actions/Publish-PSModule/action.yml index 51aa2181..9d39381a 100644 --- a/.github/actions/Publish-PSModule/action.yml +++ b/.github/actions/Publish-PSModule/action.yml @@ -18,7 +18,7 @@ inputs: required: false default: '' WhatIf: - description: If specified, the action logs only the changes it would make, but does not publish the module. + description: If specified, the action only logs the changes it would make, but does not publish the module. required: false default: 'false' WorkingDirectory: diff --git a/.github/actions/Release-PSModule/action.yml b/.github/actions/Release-PSModule/action.yml index ca1857b2..f929cbd2 100644 --- a/.github/actions/Release-PSModule/action.yml +++ b/.github/actions/Release-PSModule/action.yml @@ -15,7 +15,7 @@ inputs: required: false default: module WhatIf: - description: If specified, the action logs only the changes it would make, but does not create the release or upload artifacts. + description: If specified, the action only logs the changes it would make, but does not create the release or upload artifacts. required: false default: 'false' WorkingDirectory: From c157ce252421d58b3fe91937f35a7e54cdaea6d5 Mon Sep 17 00:00:00 2001 From: Marius Storhaug Date: Wed, 4 Nov 2026 14:58:43 +0100 Subject: [PATCH 4/7] State settings and release native help directly --- .../src/Get-PSModuleSettings.Helpers.psm1 | 8 +++---- .../actions/Get-PSModuleSettings/src/main.ps1 | 24 ++++++++++--------- .../src/Publish-PSModule.Helpers.psm1 | 14 ++++++----- .../actions/Release-PSModule/src/release.ps1 | 14 +++++++---- 4 files changed, 34 insertions(+), 26 deletions(-) diff --git a/.github/actions/Get-PSModuleSettings/src/Get-PSModuleSettings.Helpers.psm1 b/.github/actions/Get-PSModuleSettings/src/Get-PSModuleSettings.Helpers.psm1 index ef5aef29..9af4ba90 100644 --- a/.github/actions/Get-PSModuleSettings/src/Get-PSModuleSettings.Helpers.psm1 +++ b/.github/actions/Get-PSModuleSettings/src/Get-PSModuleSettings.Helpers.psm1 @@ -1,7 +1,7 @@ function Resolve-WorkflowEventRouting { <# .SYNOPSIS - Resolves release and execution routing from normalized GitHub event state. + Resolve release and execution routing from normalized GitHub event state. #> [CmdletBinding()] [OutputType([PSCustomObject])] @@ -82,7 +82,7 @@ function Resolve-WorkflowEventRouting { function Select-PullRequestForPush { <# .SYNOPSIS - Selects the merged default-branch pull request associated with a pushed commit. + Select the merged default-branch pull request associated with a pushed commit. #> [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSReviewUnusedParameter', '', Justification = 'Parameter is used inside a Sort-Object script block.')] @@ -112,7 +112,7 @@ function Select-PullRequestForPush { function Get-FilesFromGitTree { <# .SYNOPSIS - Returns the files contained in a complete Git tree response. + Return the files from a complete Git tree response. #> [CmdletBinding()] [OutputType([string])] @@ -133,7 +133,7 @@ function Get-FilesFromGitTree { function Get-FilesFromGitHubComparison { <# .SYNOPSIS - Returns files from a complete GitHub compare response. + Return files from a complete GitHub compare response. #> [CmdletBinding()] [OutputType([string])] diff --git a/.github/actions/Get-PSModuleSettings/src/main.ps1 b/.github/actions/Get-PSModuleSettings/src/main.ps1 index da1ad72b..8889b9f0 100644 --- a/.github/actions/Get-PSModuleSettings/src/main.ps1 +++ b/.github/actions/Get-PSModuleSettings/src/main.ps1 @@ -528,19 +528,20 @@ if ($settings.Test.Skip) { function Get-TestItemsFromFolder { <# .SYNOPSIS - Retrieves test items from a specified folder. + Get test items from the specified folder. .DESCRIPTION - This function searches for test-related files in the specified folder. - It looks for configuration files (*.Configuration.ps1), container files (*.Container.ps1), - and test files (*.Tests.ps1) in that order of precedence. + The function searches the specified folder for test-related files. + It searches for configuration files (*.Configuration.ps1), container files (*.Container.ps1), + and test files (*.Tests.ps1), in that order of precedence. .PARAMETER FolderPath - The path to the folder to search for test items. + Path to the folder to search for test items. .OUTPUTS System.IO.FileInfo[] - Returns an array of test-related files found in the folder. + + An array of test-related files from the folder. #> param ([string]$FolderPath) @@ -563,18 +564,19 @@ if ($settings.Test.Skip) { function Find-TestDirectory { <# .SYNOPSIS - Finds test directories recursively. + Find test directories recursively. .DESCRIPTION - This function recursively searches for all directories starting from the specified path. - It returns a flat array of all directory paths found. + The function searches recursively for all directories from the specified path. + It returns all directory paths in a flat array. .PARAMETER Path - The root path to start searching for directories. + Root path for the directory search. .OUTPUTS System.String[] - Returns an array of directory paths. + + An array of directory paths. #> param ([string]$Path) diff --git a/.github/actions/Publish-PSModule/src/Publish-PSModule.Helpers.psm1 b/.github/actions/Publish-PSModule/src/Publish-PSModule.Helpers.psm1 index da6aa7f8..81925aee 100644 --- a/.github/actions/Publish-PSModule/src/Publish-PSModule.Helpers.psm1 +++ b/.github/actions/Publish-PSModule/src/Publish-PSModule.Helpers.psm1 @@ -1,16 +1,18 @@ function Get-ModuleVersionString { <# .SYNOPSIS - Builds the SemVer version string that identifies the module itself. + Build the SemVer version string that identifies the module. .DESCRIPTION - Composes the module version and, when there is one, the prerelease label. This is the string the - PowerShell Gallery and the module manifest understand: `Major.Minor.Patch` optionally followed by - `-`. It never carries the repository's version prefix, because neither the manifest's - `ModuleVersion` nor a Gallery package version accepts one. + The function combines the module version with the prerelease label, if present. + The PowerShell Gallery and the module manifest use this string: `Major.Minor.Patch` optionally followed by `-`. + The string never includes the repository's version prefix. + Neither the manifest's `ModuleVersion` nor a Gallery package version accepts a prefix. .OUTPUTS - String with the module version. + System.String + + The module version. .EXAMPLE Get-ModuleVersionString -ModuleVersion '1.1.10' diff --git a/.github/actions/Release-PSModule/src/release.ps1 b/.github/actions/Release-PSModule/src/release.ps1 index 27c1b73c..e8ae40f6 100644 --- a/.github/actions/Release-PSModule/src/release.ps1 +++ b/.github/actions/Release-PSModule/src/release.ps1 @@ -3,11 +3,11 @@ <# .SYNOPSIS - Creates or resumes a GitHub release for a versioned PowerShell module artifact. + Create or resume a GitHub release for a versioned PowerShell module artifact. .DESCRIPTION - Validates the supplied module artifact, creates a GitHub release when its tag does not - already exist, uploads the artifact ZIP, and reports the result on the source pull request. + The script validates the supplied module artifact. If the release tag does not exist, the script creates a GitHub release. + It uploads the artifact ZIP and reports the result on the source pull request. .EXAMPLE ./release.ps1 @@ -15,10 +15,14 @@ Creates or resumes the release using inputs supplied by the Release-PSModule action. .INPUTS - None. The Release-PSModule composite action supplies values through environment variables. + None + + The Release-PSModule composite action supplies values through environment variables. .OUTPUTS - None. The script writes ReleaseTag and ReleaseUrl to the GitHub Actions output file. + None + + The script writes ReleaseTag and ReleaseUrl to the GitHub Actions output file. #> [Diagnostics.CodeAnalysis.SuppressMessageAttribute( 'PSUseDeclaredVarsMoreThanAssignments', 'usePRBodyAsReleaseNotes', From 9cddf4a968b52064d16da9c63d74bc1a61250cdb Mon Sep 17 00:00:00 2001 From: Marius Storhaug Date: Wed, 4 Nov 2026 15:01:00 +0100 Subject: [PATCH 5/7] Clarify resolver native help without changing decisions --- .../src/Resolve-PSModuleVersion.Helpers.psm1 | 107 +++++++++--------- 1 file changed, 56 insertions(+), 51 deletions(-) diff --git a/.github/actions/Resolve-PSModuleVersion/src/Resolve-PSModuleVersion.Helpers.psm1 b/.github/actions/Resolve-PSModuleVersion/src/Resolve-PSModuleVersion.Helpers.psm1 index ab9b8560..7f99b1bd 100644 --- a/.github/actions/Resolve-PSModuleVersion/src/Resolve-PSModuleVersion.Helpers.psm1 +++ b/.github/actions/Resolve-PSModuleVersion/src/Resolve-PSModuleVersion.Helpers.psm1 @@ -1,7 +1,7 @@ function Split-CommaSeparatedList { <# .SYNOPSIS - Splits a comma-separated string into a trimmed, non-empty array. + Split a comma-separated string into a trimmed, non-empty array. .EXAMPLE Split-CommaSeparatedList -Value 'Major, Minor, Patch' @@ -22,14 +22,16 @@ function Read-ActionInput { <# .SYNOPSIS - Reads and validates action inputs from environment variables. + Read and validate action inputs from environment variables. .DESCRIPTION - Reads the module name and settings JSON from GitHub Actions environment variables. - Falls back to the repository name when the module name input is not provided. + The function reads the module name and settings JSON from GitHub Actions environment variables. + If the module name input is not provided, it uses the repository name. .OUTPUTS - PSCustomObject with Name and SettingsJson properties. + System.Management.Automation.PSCustomObject + + An object with Name and SettingsJson properties. .EXAMPLE $actionInput = Read-ActionInput @@ -63,14 +65,16 @@ function Read-ActionInput { function Get-PublishConfiguration { <# .SYNOPSIS - Parses the settings JSON into a publish configuration object. + Parse the settings JSON into a publish configuration object. .DESCRIPTION - Extracts publish module settings including auto-patching flags, version prefix, + The function extracts module publish settings: auto-patching flags, version prefix, release type, and label classification arrays. .OUTPUTS - PSCustomObject with publish configuration properties. + System.Management.Automation.PSCustomObject + + An object with publish configuration properties. .EXAMPLE $config = Get-PublishConfiguration -SettingsJson $actionInput.SettingsJson @@ -123,17 +127,17 @@ function Get-PublishConfiguration { function Get-GitHubPullRequest { <# .SYNOPSIS - Reads normalized pull-request context from settings, with event-payload fallback. + Read normalized pull-request context from settings, with event-payload fallback. .DESCRIPTION - The settings action resolves the pull request associated with a default-branch push - before this action runs. When no pull request exists, a direct push or manual - dispatch on the default branch still receives release context so it resolves the - default patch bump. + The settings action resolves the pull request for a default-branch push before this action runs. + If no pull request exists, a direct push or manual dispatch on the default branch receives release context. + This context resolves the default patch bump. .OUTPUTS - PSCustomObject with pull-request metadata, or a default-branch direct-release - context with no pull-request number. + System.Management.Automation.PSCustomObject + + An object with pull-request metadata, or a default-branch direct-release context with no pull-request number. .EXAMPLE $pullRequest = Get-GitHubPullRequest -SettingsJson $actionInput.SettingsJson @@ -207,14 +211,15 @@ function Get-GitHubPullRequest { function Resolve-ReleaseDecision { <# .SYNOPSIS - Determines whether to publish a release and what kind of version bump to apply. + Determine whether to publish a release and which version bump to apply. .DESCRIPTION - Evaluates the PR labels against the configured label categories and release type - to produce a complete release decision. + The function evaluates the PR labels against the configured label categories and release type to produce a complete release decision. .OUTPUTS - PSCustomObject with ShouldPublish, CreateRelease, CreatePrerelease, MajorRelease, + System.Management.Automation.PSCustomObject + + An object with ShouldPublish, CreateRelease, CreatePrerelease, MajorRelease, MinorRelease, PatchRelease, HasVersionBump, and PrereleaseName properties. .EXAMPLE @@ -338,11 +343,11 @@ function Resolve-ReleaseDecision { function ConvertFrom-GitHubReleaseJson { <# .SYNOPSIS - Converts the JSON output of 'gh release list' into a flat array of release objects. + Convert the JSON output of 'gh release list' into a flat array of release objects. .DESCRIPTION - Normalizes the release listing so a repository with no releases, or a command that - produced no output at all, yields an empty array instead of $null. + The function normalizes the release list. + If the repository has no releases or the command produces no output, the result is an empty array instead of $null. .OUTPUTS Array of release objects. Empty when there are no releases. @@ -370,11 +375,11 @@ function ConvertFrom-GitHubReleaseJson { function Get-GitHubRelease { <# .SYNOPSIS - Retrieves all releases from the current GitHub repository. + Get all releases from the current GitHub repository. .DESCRIPTION - Lists the releases of the current repository. A repository that has no releases yet - produces no output, so callers normalize the result with @() before using it. + The function lists releases from the current repository. If the repository has no releases, it produces no output. + Callers use @() to normalize the result. .OUTPUTS Array of release objects. Nothing when the repository has no releases. @@ -407,12 +412,12 @@ function Get-GitHubRelease { function Get-LatestGitHubVersion { <# .SYNOPSIS - Extracts the latest stable version from a GitHub releases list. + Get the latest stable version from a GitHub releases list. .DESCRIPTION - Returns the version of the release marked as latest. A repository that has no releases - yet - or that has releases but none marked as latest - resolves to '0.0.0' so a brand-new - module can still be versioned before its first release exists. + The function returns the version of the release marked as latest. + If the repository has no releases or no release has the latest marker, the function returns '0.0.0'. + This baseline lets the workflow set a module version before the first release. .OUTPUTS PSSemVer representing the latest GitHub release version. @@ -451,11 +456,11 @@ function Get-LatestGitHubVersion { function Get-LatestPSGalleryVersion { <# .SYNOPSIS - Finds the latest stable version of a module in the PowerShell Gallery. + Find the latest stable version of a module in the PowerShell Gallery. .DESCRIPTION - Queries the PowerShell Gallery for the latest published version of the module. - Retries up to five times with a ten-second delay between attempts. + The function queries the PowerShell Gallery for the latest published version of the module. + It retries up to five times, with a ten-second delay between attempts. .OUTPUTS PSSemVer representing the latest PSGallery version. @@ -509,12 +514,12 @@ function Get-LatestPSGalleryVersion { function Get-LatestPublishedVersion { <# .SYNOPSIS - Returns the highest version between GitHub and the PowerShell Gallery. + Return the highest version between GitHub and the PowerShell Gallery. .DESCRIPTION - Compares the two known published versions and returns the highest one. A missing - (null) version is treated as '0.0.0', so a module that has never been released to - GitHub or published to the PowerShell Gallery resolves to a '0.0.0' baseline. + The function compares the two known published versions and returns the highest one. + If a version is missing (null), the function treats it as '0.0.0'. + A module with no GitHub release or PowerShell Gallery publication has a '0.0.0' baseline. .OUTPUTS PSSemVer representing the highest known published version. @@ -556,15 +561,16 @@ function Get-LatestPublishedVersion { function Get-NextPrereleaseNumber { <# .SYNOPSIS - Calculates the next incremental prerelease number across GitHub and PSGallery. + Calculate the next incremental prerelease number across GitHub and PSGallery. .DESCRIPTION - Queries both GitHub releases and the PowerShell Gallery for existing prereleases - matching the base version and prerelease name, then returns the next number - zero-padded to three digits. + The function queries GitHub releases and the PowerShell Gallery for prereleases that match the base version and prerelease name. + It returns the next number, zero-padded to three digits. .OUTPUTS - String. A zero-padded three-digit number (e.g. '001'). + System.String + + A zero-padded three-digit number (e.g. '001'). .EXAMPLE $number = Get-NextPrereleaseNumber -ModuleName 'MyModule' -BaseVersion '1.2.3' -PrereleaseName 'mybranch' -Releases $releases @@ -631,11 +637,11 @@ function Get-NextPrereleaseNumber { function Get-NextModuleVersion { <# .SYNOPSIS - Calculates the next module version based on the release decision. + Calculate the next module version from the release decision. .DESCRIPTION - Increments the current version according to the version bump type (major, minor, or patch), - then optionally appends a prerelease suffix with support for date-based and incremental numbering. + The function increments the current version for the major, minor, or patch version bump. + It can append a prerelease suffix with date-based and incremental numbering. .OUTPUTS PSSemVer representing the resolved next version. @@ -727,14 +733,13 @@ function Get-NextModuleVersion { function Get-ResolvedModuleVersion { <# .SYNOPSIS - Resolves the next module version and resumes an incomplete stable release when possible. + Resolve the next module version and resume an incomplete stable release when possible. .DESCRIPTION - Normally the highest version from GitHub Releases and the PowerShell Gallery is the - version baseline. If Gallery contains exactly the stable version implied by the latest - GitHub release and this run's version bump, Gallery publication succeeded but GitHub - release creation did not. In that case, return the Gallery version rather than bumping - again so the workflow can resume the missing GitHub release. + The highest version from GitHub Releases and the PowerShell Gallery is normally the version baseline. + If Gallery contains exactly the stable version implied by the latest GitHub release and this run's version bump, + Gallery publication succeeded. GitHub release creation did not succeed in this case. + The function returns the Gallery version instead of another version bump so the workflow can resume the missing GitHub release. .OUTPUTS PSSemVer representing the resolved module version. @@ -807,7 +812,7 @@ function Get-ResolvedModuleVersion { function Write-ActionOutput { <# .SYNOPSIS - Emits the resolved version and release type as GitHub Actions step outputs. + Write the resolved version and release type as GitHub Actions step outputs. .EXAMPLE Write-ActionOutput -Decision $decision -NewVersion $newVersion From 46bc0f028a41b80f32d9f2aa787097296010289d Mon Sep 17 00:00:00 2001 From: Marius Storhaug Date: Wed, 4 Nov 2026 15:06:16 +0100 Subject: [PATCH 6/7] Use direct STE verb choices in native help --- .../actions/Publish-PSModule/src/Publish-PSModule.Helpers.psm1 | 2 +- .../src/Resolve-PSModuleVersion.Helpers.psm1 | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/actions/Publish-PSModule/src/Publish-PSModule.Helpers.psm1 b/.github/actions/Publish-PSModule/src/Publish-PSModule.Helpers.psm1 index 81925aee..d935ff9b 100644 --- a/.github/actions/Publish-PSModule/src/Publish-PSModule.Helpers.psm1 +++ b/.github/actions/Publish-PSModule/src/Publish-PSModule.Helpers.psm1 @@ -4,7 +4,7 @@ Build the SemVer version string that identifies the module. .DESCRIPTION - The function combines the module version with the prerelease label, if present. + If a prerelease label is present, the function puts the module version and the label together. The PowerShell Gallery and the module manifest use this string: `Major.Minor.Patch` optionally followed by `-`. The string never includes the repository's version prefix. Neither the manifest's `ModuleVersion` nor a Gallery package version accepts a prefix. diff --git a/.github/actions/Resolve-PSModuleVersion/src/Resolve-PSModuleVersion.Helpers.psm1 b/.github/actions/Resolve-PSModuleVersion/src/Resolve-PSModuleVersion.Helpers.psm1 index 7f99b1bd..fa4b69f2 100644 --- a/.github/actions/Resolve-PSModuleVersion/src/Resolve-PSModuleVersion.Helpers.psm1 +++ b/.github/actions/Resolve-PSModuleVersion/src/Resolve-PSModuleVersion.Helpers.psm1 @@ -211,7 +211,7 @@ function Get-GitHubPullRequest { function Resolve-ReleaseDecision { <# .SYNOPSIS - Determine whether to publish a release and which version bump to apply. + Find whether to publish a release and which version bump to apply. .DESCRIPTION The function evaluates the PR labels against the configured label categories and release type to produce a complete release decision. From 09d209ee07418174c6835cb64b6977c2740ad962 Mon Sep 17 00:00:00 2001 From: Marius Storhaug Date: Wed, 4 Nov 2026 15:07:01 +0100 Subject: [PATCH 7/7] Remove the final consent appeal without changing policy --- .github/zensical.toml | 2 +- docs/zensical.toml | 3 +-- 2 files changed, 2 insertions(+), 3 deletions(-) diff --git a/.github/zensical.toml b/.github/zensical.toml index 650af9f7..12594dcb 100644 --- a/.github/zensical.toml +++ b/.github/zensical.toml @@ -65,5 +65,5 @@ name = "-{{ REPO_OWNER }}- on GitHub" [project.extra.consent] title = "Cookie consent" -description = "We use cookies to recognize your repeated visits and preferences, as well as to measure the effectiveness of our documentation and whether users find what they're searching for. With your consent, you're helping us to make our documentation better." +description = "We use cookies to recognize your repeated visits and preferences, as well as to measure the effectiveness of our documentation and whether users find what they're searching for." actions = ["accept", "reject"] diff --git a/docs/zensical.toml b/docs/zensical.toml index e32fd2d9..6831c24d 100644 --- a/docs/zensical.toml +++ b/docs/zensical.toml @@ -159,8 +159,7 @@ title = "Cookie consent" description = """ We use cookies to recognize your repeated visits and preferences, as well as to measure the effectiveness of our documentation and whether users - find what they're searching for. With your consent, you're helping us to - make our documentation better. + find what they're searching for. """ actions = ["accept", "reject"]