docs: Align the README settings table with build.properties.ps1 - #186
Merged
Conversation
`$PSBPreference.Docs.AlphabeticParamsOrder` was removed in #105 when help generation moved to Microsoft.PowerShell.PlatyPS 1.x, which always sorts parameters alphabetically. The removal was recorded in the changelog and the migration guide, but the README settings table and the `Docs` row in `instructions/repository-specific.instructions.md` still advertised it as a setting a consumer could set. Auditing the rest of the same table against the defaults turned up more of the same. `$PSBPreference.Build.Dependencies` was replaced by the `$PSB{TaskName}Dependency` variables in #72, back in 0.7.0 - it no longer exists in the defaults, and IB.tasks.ps1 now throws a NotSupportedException if a consumer sets it. Four `Test` defaults documented the parameter defaults of `Test-PSBuildPester` rather than the `$PSBPreference` values that actually reach it: `Test.OutputFile` and `Test.CodeCoverage.OutputFile` both default to absolute paths under the project root, `Test.CodeCoverage.Files` defaults to an empty array, and `Test.CodeCoverage.OutputFileFormat` defaults to JaCoCo. Nothing checked the README against the defaults, which is how this survived several releases, so this adds the drift guard next to the one that covers the task files. It resolves every `$PSBPreference` path in the README table against `build.properties.ps1`, allowing the four optional `Compile*` settings that are deliberately absent from the defaults. Only the documented-to-defined direction is asserted; the reverse would fail today on the Sign section, which the README has never covered. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01U1Jhu7fgTRJq7LK5MuKteE
Correcting `Test.CodeCoverage.OutputFile`'s default to the absolute `$projectRoot/codeCoverage.xml` left the description contradicting the column beside it: a parenthetical claiming the path is relative to the Pester test directory, next to a default that plainly is not relative. The parenthetical was incomplete rather than wrong. `Test-PSBuildPester` does `Push-Location -LiteralPath $Path` into the test directory before assigning `$configuration.CodeCoverage.OutputPath`, so a relative value does resolve against the test directory - but the shipped default is absolute. State both facts instead of only the one that does not describe the default. `Test.OutputFile` has the same absolute default and the same relative-path behaviour, but its README description makes no relativity claim, so it needed no change. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01U1Jhu7fgTRJq7LK5MuKteE
This was referenced Aug 27, 2026
README examples assign a setting that does not exist: $PSBPreference.Test.ScriptAnalysisEnabled
#191
Closed
tablackburn
added a commit
that referenced
this pull request
Aug 27, 2026
Authenticode signing and catalog support shipped in 0.8.0 (#92), but none of the sixteen settings it added to build.properties.ps1 ever reached the README settings table. The only way to discover how to sign a module was to read build.properties.ps1 and psakeFile.ps1, which is not a reference a consumer should have to reconstruct for themselves on the way to 1.0.0. The defaults are read from build.properties.ps1 rather than from the function parameters, which is the mistake #186 was opened to correct in four existing rows. The descriptions are condensed from the inline documentation there, with two exceptions taken from the implementation instead: - Sign.SkipCertificateValidation is documented as applying to the EnvVar and PfxFile sources, because that is what Get-PSBuildCertificate does. Its inline comment claims Store and Thumbprint, where the query already filters on private key and expiry and there is nothing left to skip. - Sign.Catalog.FileName documents the computed <ModuleName>.cat fallback, which lives in the tasks rather than in the defaults. A short "Code signing" section covers the five CertificateSource modes. The choice between them is a setup decision about where a pipeline keeps its certificate, and the Auto fallback chain in particular cannot be explained in a table cell. Also adds what the table rows imply exist: the Sign, SignModule, BuildCatalog, and SignCatalog tasks, and the four $PSB{TaskName}Dependency variables the dependency table stopped short of. With the gap closed, the README drift guard now asserts both directions. The reverse assertion needs no allow-list: every leaf of the defaults is in the table, Build.ModuleOutDir included, which is documented with a note that it is for internal use rather than hidden from the readers the table exists for. Closes #189 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01U1Jhu7fgTRJq7LK5MuKteE
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
$PSBPreference.Docs.AlphabeticParamsOrderfrom the README settings table and fromthe
Docsrow ininstructions/repository-specific.instructions.md. It was removed from themodule in Update PlatyPS dependency from platyPS v0.14.x to Microsoft.PowerShell.PlatyPS v1.x #105 (issue Update PlatyPS dependency from platyPS v0.14.x to Microsoft.PowerShell.PlatyPS v1.x #105 / PR feat!: Migrate markdown and MAML help to Microsoft.PowerShell.PlatyPS 1.x #173) when help generation moved to
Microsoft.PowerShell.PlatyPS 1.x, which always sorts parameters alphabetically. It is gone
from
PowerShellBuild/build.properties.ps1and there is noAlphabeticParamsOrderparameteron
Build-PSBuildMarkdown, so both files were advertising a setting a consumer cannot set.$PSBPreference.Build.Dependencies, found while auditing the rest of the same table.It was replaced by the
$PSB{TaskName}Dependencyvariables in Loosen Dependencies #72 (0.7.0), it is absent fromthe defaults, and
IB.tasks.ps1throws aNotSupportedExceptionif a consumer sets it — theREADME already documents the replacement in its own "Modifying task dependencies" section.
Testdefaults that documented the parameter defaults ofTest-PSBuildPesterrather than the
$PSBPreferencevalues that are actually passed to it, and rewordsTest.CodeCoverage.OutputFile's description, which claimed the path was relative to thePester test directory and so contradicted its own corrected absolute default.
docs/migration-v0.8-to-v1.0.mdis untouched — it documents the removal deliberately.Corrected defaults
build.properties.ps1Test.OutputFile$null[IO.Path]::Combine($env:BHProjectPath, 'testResults.xml')Test.CodeCoverage.Files*.ps1, *.psm1@()Test.CodeCoverage.OutputFilecoverage.xml[IO.Path]::Combine($env:BHProjectPath, 'codeCoverage.xml')Test.CodeCoverage.OutputFileFormat$nullJaCoCoTest.CodeCoverage.OutputFile's description read "Output file path (relative to Pester testdirectory) where Pester will save code coverage results to", which the corrected absolute
default contradicted. The parenthetical was incomplete rather than wrong —
Test-PSBuildPesterdoes
Push-Location -LiteralPath $Pathinto the test directory before assigning$configuration.CodeCoverage.OutputPath, so a relative value does resolve against the testdirectory — so the cell now states both facts.
Test.OutputFilehas the same absolute defaultand the same behaviour for relative values, but its description makes no relativity claim and
was left alone.
Every row keeps its existing fixed-width column alignment; no untouched row was reflowed.
The drift guard
tests/IBTasks.tests.ps1already resolves every$PSBPreferencepath the two task filesreference against the defaults (
Describe 'Settings referenced by the task files', added for#178). Nothing did the equivalent for the README, which is why a setting removed in #105 and one
removed in #72 both survived there. The new
Describe 'Settings documented in the README'parses
$PSBPreference.*out of the table rows and resolves each one the same way.Verified in both directions: with the table as it stands the test passes in isolation
(
-FullNameFilter '*README*'), and re-adding theAlphabeticParamsOrderrow fails it withExpected $null or empty, but got 'Docs.AlphabeticParamsOrder'.Two structural notes:
$script:defaultPreferenceandTest-PreferencePath) moved from the firstdrift
Describeinto a file-levelBeforeAllso both blocks can run under a filterindependently. Nothing else in the existing tests changed.
Build.CompileHeader,Build.CompileFooter,Build.CompileScriptHeader,Build.CompileScriptFooter. These are documented butdeliberately absent from the defaults: both task files forward them to
Build-PSBuildModuleonly when the consumer has added the key, so defining them would inject empty strings into
every compiled PSM1.
Not fixed here, reported instead
Signsection is undocumented in the README.build.properties.ps1defines 13Sign.*settings plus 3 underSign.Catalog, and the README settings table covers none ofthem. That is a section to write, not a row to fix, so the new test only asserts the
documented-to-defined direction; the reverse would fail today. The signing settings are
covered in
instructions/repository-specific.instructions.md.$PSBPublishDependencyand omits$PSBSignModuleDependency,$PSBBuildCatalogDependency,$PSBSignCatalogDependency, and$PSBSignDependency. Same root cause as the above; thosefour are listed in
instructions/repository-specific.instructions.md.instructions/repository-specific.instructions.mdnames the migration guide asdocs/migration/v0.8-to-v1.0.md; the file on disk isdocs/migration-v0.8-to-v1.0.md. Not asettings drift, so left out of this diff.
No CHANGELOG entry: the removal is already logged under #105, and this is a correction to the
documentation of an already-logged change.
Test plan
./build.ps1 -Task Test— 484 passed, 0 failed, 3 skipped (483/0/3 onmain, plus theone test added here).
Analyzeclean.grep -rn AlphabeticParamsOrderleaves matches only inCHANGELOG.mdanddocs/migration-v0.8-to-v1.0.md, both of which document the removal on purpose, plus thenew test's explanatory comment.
Breaking changes
None. Documentation and tests only.
🤖 Generated with Claude Code
https://claude.ai/code/session_01U1Jhu7fgTRJq7LK5MuKteE