[release/v7.5.6] Add comment-based help documentation to build.psm1 functions#27221
Conversation
daxian-dbw
added
the
CL-BuildPackaging
There was a problem hiding this comment.
Pull request overview
Backport to release/v7.5.6 of comment-based help (CBH) additions in build.psm1 to improve discoverability of build/test tooling functions for contributors and release engineers.
Changes:
- Added CBH blocks (
.SYNOPSIS,.DESCRIPTION,.PARAMETER,.OUTPUTS) to many functions inbuild.psm1. - Removed/replaced an older inline comment block in
ConvertFrom-PesterLogwith CBH-style help. - Includes a couple of small functional fixes mixed into the documentation update (notably in
Start-PSPesterandStart-UnelevatedProcess).
|
|
||
| if($IncludeCommonTests.IsPresent) | ||
| { | ||
| $path = += "$PSScriptRoot/test/common" | ||
| $path += "$PSScriptRoot/test/common" | ||
| } |
There was a problem hiding this comment.
PR description/testing notes say this backport is documentation-only, but this hunk contains a functional fix (changing an invalid $path = += ... to $Path += ...). There is also another logic change later in Start-UnelevatedProcess (arm64 check). Please update the PR description/testing section to reflect these functional changes (or split them into a separate PR) so release-branch risk/testing expectations are accurate.
| .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 new comment-based help for New-PSOptions says the Framework parameter defaults to 'net11.0', but the implementation defaults to 'net9.0' (and validates only net9.0). Please update the help text so it matches the actual default/allowed framework value.
| The target .NET framework moniker. Defaults to 'net11.0'. | |
| The target .NET framework moniker. Defaults to 'net9.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.
The new comment-based help for New-PSOptionsObject uses 'net11.0' as the example framework moniker, but the build scripts currently use net9.0. Please update the example so the help stays accurate for contributors following it.
| The target .NET framework moniker, e.g. 'net11.0'. | |
| The target .NET framework moniker, e.g. 'net9.0'. |
Backport of #27122 to release/v7.5.6
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
Adds comment-based help to build.psm1 functions used by contributors and release engineers. This improves discoverability and maintenance of build tooling on the release branch but is not required for build correctness.
Customer Impact
Regression
REQUIRED: Check exactly one box.
This is not a regression.
Testing
Cherry-pick applied cleanly to release/v7.5.6. This backport is documentation-only within build.psm1, so verification is limited to successful application and backport PR CI on the release branch.
Risk
REQUIRED: Check exactly one box.
Low risk because the change only adds documentation comments to build tooling functions and does not alter build logic or execution flow.