[release/v7.6.1] Add comment-based help documentation to build.psm1 functions#27216
Conversation
daxian-dbw
added
the
CL-BuildPackaging
There was a problem hiding this comment.
Pull request overview
Backport of PR #27122 to release/v7.6.1, primarily adding comment-based help (CBH) across build.psm1 functions to improve discoverability of build tooling.
Changes:
- Added CBH blocks (.SYNOPSIS/.DESCRIPTION/.PARAMETER/.OUTPUTS) to many
build.psm1functions. - Removed/replaced an old inline comment block in
ConvertFrom-PesterLogwith proper CBH. - Includes a couple of non-doc functional edits in the Pester path handling and unelevated-process arm64 gating.
| .PARAMETER Configuration | ||
| The build configuration: Debug (default), Release, CodeCoverage, or StaticAnalysis. | ||
| .PARAMETER Framework | ||
| The target .NET framework moniker. Defaults to 'net11.0'. |
There was a problem hiding this comment.
The comment-based help for New-PSOptions says the default framework is 'net11.0', but the parameter ValidateSet/default value below is 'net10.0'. This makes the help inaccurate; update the help text to match the actual default/framework options.
| The target .NET framework moniker. Defaults to 'net11.0'. | |
| The target .NET framework moniker. Defaults to 'net10.0'. |
| .PARAMETER PSModuleRestore | ||
| Whether Gallery modules should be restored to the build output. | ||
| .PARAMETER Framework | ||
| The target .NET framework moniker, e.g. 'net11.0'. |
There was a problem hiding this comment.
New-PSOptionsObject help uses 'net11.0' as the example framework moniker, but New-PSOptions currently constrains the Framework parameter to 'net10.0'. Update this example so the help reflects the actual supported/expected framework value for this branch.
| The target .NET framework moniker, e.g. 'net11.0'. | |
| The target .NET framework moniker, e.g. 'net10.0'. |
| } | ||
|
|
||
| if($IncludeCommonTests.IsPresent) | ||
| { | ||
| $path = += "$PSScriptRoot/test/common" | ||
| $path += "$PSScriptRoot/test/common" | ||
| } |
There was a problem hiding this comment.
The PR description states this is a documentation-only backport, but this hunk includes a functional code fix (updating the test path list when -IncludeCommonTests is set). If these behavior changes are intended, please update the PR description and testing notes accordingly; otherwise, consider reverting/splitting the code changes from the documentation backport.
| if (-not $environment.IsWindows) | ||
| { | ||
| throw "Start-UnelevatedProcess is currently not supported on non-Windows platforms" | ||
| } | ||
|
|
||
| if (-not $environment.OSArchitecture -eq 'arm64') | ||
| if ($environment.OSArchitecture -eq 'arm64') | ||
| { | ||
| throw "Start-UnelevatedProcess is currently not supported on arm64 platforms" |
There was a problem hiding this comment.
The PR description says the change is documentation-only, but this hunk changes behavior for Start-UnelevatedProcess by altering the arm64 architecture check. If this fix is intentional, please call it out in the PR description/testing notes; otherwise, consider reverting/splitting it from the documentation backport.
Backport of #27122 to release/v7.6.1
Triggered by @daxian-dbw on behalf of @powercode
Original CL Label: CL-BuildPackaging
/cc @PowerShell/powershell-maintainers
Impact
REQUIRED: Choose either Tooling Impact or Customer Impact (or both). At least one checkbox must be selected.
Tooling Impact
Backports comment-based help for build.psm1 module functions to improve maintainability and discoverability of the release build tooling without changing the tooling behavior itself.
Customer Impact
Regression
REQUIRED: Check exactly one box.
This is not a regression.
Testing
Verified by cherry-picking onto release/v7.6.1 without conflicts. This is a documentation-only tooling change; no local test run was necessary, and CI on the backport PR will validate that no unintended formatting or syntax issues were introduced.
Risk
REQUIRED: Check exactly one box.
Low risk because the change only adds comment-based help to existing PowerShell build module functions and does not alter functional behavior.