Skip to content

docs: Align the README settings table with build.properties.ps1 - #186

Merged
tablackburn merged 2 commits into
mainfrom
docs/readme-alphabeticparamsorder-drift
Aug 27, 2026
Merged

docs: Align the README settings table with build.properties.ps1#186
tablackburn merged 2 commits into
mainfrom
docs/readme-alphabeticparamsorder-drift

Conversation

@tablackburn

@tablackburn tablackburn commented Aug 27, 2026

Copy link
Copy Markdown
Contributor

Summary

  • Removes $PSBPreference.Docs.AlphabeticParamsOrder from the README settings table and from
    the Docs row in instructions/repository-specific.instructions.md. It was removed from the
    module 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.ps1 and there is no AlphabeticParamsOrder parameter
    on Build-PSBuildMarkdown, so both files were advertising a setting a consumer cannot set.
  • Removes $PSBPreference.Build.Dependencies, found while auditing the rest of the same table.
    It was replaced by the $PSB{TaskName}Dependency variables in Loosen Dependencies #72 (0.7.0), it is absent from
    the defaults, and IB.tasks.ps1 throws a NotSupportedException if a consumer sets it — the
    README already documents the replacement in its own "Modifying task dependencies" section.
  • Corrects four Test defaults that documented the parameter defaults of Test-PSBuildPester
    rather than the $PSBPreference values that are actually passed to it, and rewords
    Test.CodeCoverage.OutputFile's description, which claimed the path was relative to the
    Pester test directory and so contradicted its own corrected absolute default.
  • Adds a drift guard for the README table, alongside the existing one for the task files.

docs/migration-v0.8-to-v1.0.md is untouched — it documents the removal deliberately.

Corrected defaults

Setting Documented build.properties.ps1
Test.OutputFile $null [IO.Path]::Combine($env:BHProjectPath, 'testResults.xml')
Test.CodeCoverage.Files *.ps1, *.psm1 @()
Test.CodeCoverage.OutputFile coverage.xml [IO.Path]::Combine($env:BHProjectPath, 'codeCoverage.xml')
Test.CodeCoverage.OutputFileFormat $null JaCoCo

Test.CodeCoverage.OutputFile's description read "Output file path (relative to Pester test
directory) where Pester will save code coverage results to", which the corrected absolute
default contradicted. 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 — so the cell now states both facts. Test.OutputFile has the same absolute default
and 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.ps1 already resolves every $PSBPreference path the two task files
reference 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 the AlphabeticParamsOrder row fails it with
Expected $null or empty, but got 'Docs.AlphabeticParamsOrder'.

Two structural notes:

  • The shared setup ($script:defaultPreference and Test-PreferencePath) moved from the first
    drift Describe into a file-level BeforeAll so both blocks can run under a filter
    independently. Nothing else in the existing tests changed.
  • The guard has an allow list of four settings — Build.CompileHeader, Build.CompileFooter,
    Build.CompileScriptHeader, Build.CompileScriptFooter. These are documented but
    deliberately absent from the defaults: both task files forward them to Build-PSBuildModule
    only when the consumer has added the key, so defining them would inject empty strings into
    every compiled PSM1.

Not fixed here, reported instead

  • The whole Sign section is undocumented in the README. build.properties.ps1 defines 13
    Sign.* settings plus 3 under Sign.Catalog, and the README settings table covers none of
    them. 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.
  • The README's task-dependency table is missing the signing chain. It stops at
    $PSBPublishDependency and omits $PSBSignModuleDependency, $PSBBuildCatalogDependency,
    $PSBSignCatalogDependency, and $PSBSignDependency. Same root cause as the above; those
    four are listed in instructions/repository-specific.instructions.md.
  • instructions/repository-specific.instructions.md names the migration guide as
    docs/migration/v0.8-to-v1.0.md; the file on disk is docs/migration-v0.8-to-v1.0.md. Not a
    settings 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 on main, plus the
    one test added here). Analyze clean.
  • New guard passes in isolation and fails when the removed row is re-added.
  • grep -rn AlphabeticParamsOrder leaves matches only in CHANGELOG.md and
    docs/migration-v0.8-to-v1.0.md, both of which document the removal on purpose, plus the
    new test's explanatory comment.

Breaking changes

None. Documentation and tests only.

🤖 Generated with Claude Code

https://claude.ai/code/session_01U1Jhu7fgTRJq7LK5MuKteE

`$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
Copilot AI lite review requested due to automatic review settings August 27, 2026 18:37

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

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
@github-actions

Copy link
Copy Markdown

Test Results

    4 files  ±0    764 suites  +4   2m 42s ⏱️ +23s
  486 tests +1    483 ✅ +1   3 💤 ±0  0 ❌ ±0 
1 948 runs  +4  1 881 ✅ +4  67 💤 ±0  0 ❌ ±0 

Results for commit 2aa6c97. ± Comparison against base commit a64ebc8.

@tablackburn
tablackburn merged commit 687fc1b into main Aug 27, 2026
9 checks passed
@tablackburn
tablackburn deleted the docs/readme-alphabeticparamsorder-drift branch August 27, 2026 22:26
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
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants