Skip to content

docs: The sixteen $PSBPreference.Sign settings are undocumented in the README #189

Description

@tablackburn

Problem

PowerShellBuild/build.properties.ps1 defines sixteen settings that the README
does not mention at all:

  • Thirteen under $PSBPreference.Sign: Enabled, CertificateSource,
    CertStoreLocation, Thumbprint, CertificateEnvVar,
    CertificatePasswordEnvVar, PfxFilePath, PfxFilePassword, Certificate,
    SkipCertificateValidation, TimestampServer, HashAlgorithm, FilesToSign
  • Three under $PSBPreference.Sign.Catalog: Enabled, Version, FileName

Authenticode signing and catalog support shipped in
0.8.0 (#92) with three
public functions and four tasks, and it is changelogged. The $PSBPreference
settings table in the README, which is where consumers actually look up
configuration, has never covered any of it. The Sign, SignModule,
BuildCatalog, and SignCatalog tasks are likewise absent from the README's
task tables, and $PSBSignModuleDependency, $PSBBuildCatalogDependency,
$PSBSignCatalogDependency, and $PSBSignDependency are absent from the
$PSB{TaskName}Dependency table, which stops at $PSBPublishDependency.

For a shipped feature heading into 1.0.0, that means the only way to discover
how to sign a module is to read build.properties.ps1 and psakeFile.ps1.

Knock-on effect on the drift test

The README drift guard added in
#186
(Describe 'Settings documented in the README' in tests/IBTasks.tests.ps1)
asserts only one direction — that every setting the README lists exists in the
defaults. Its own comment says why the reverse direction is not asserted:

Only the documented-to-defined direction is asserted. The reverse direction
would fail today on the whole Sign section, which the README has never
covered.

So the gap is not just missing prose; it is actively preventing the guard from
catching the next setting that ships undocumented.

Proposed fix

  1. Add the sixteen Sign rows to the README settings table, sourced from the
    inline documentation in build.properties.ps1 and the implementations in
    Get-PSBuildCertificate, Invoke-PSBuildModuleSigning, and
    New-PSBuildFileCatalog.
  2. Add a short "Code signing" section covering the five CertificateSource
    modes, since the setup implications (CI environment variables, PFX files,
    certificate store, pre-resolved certificate object) do not fit in one table
    cell.
  3. Add the four missing signing tasks and the four missing
    $PSB{TaskName}Dependency rows.
  4. Extend the drift test to assert the reverse direction as well, and remove
    the now-stale comment about the Sign section.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions