Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
tablackburn merged 2 commits into from
Aug 27, 2026
Merged

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
8ea8982
docs: Align the README settings table with build.properties.ps1
tablackburn Aug 27, 2026
2aa6c97
docs: Reword the code coverage output file description
tablackburn Aug 27, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 4 additions & 6 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@
> example.

<p align="center">
<img src="media/psaketaskmodule-256x256.png" alt="Logo">

Check warning on line 28 in README.md

View workflow job for this annotation

GitHub Actions / CI / Run Linters 

Unknown word (psaketaskmodule)
</p>

## Status - Work in progress
Expand Down Expand Up @@ -86,12 +86,11 @@
| Setting | Default value | Description |
|-------------------------------------------------------------|---------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| $PSBPreference.General.ProjectRoot | `$env:BHProjectPath` | Root directory for the project |
| $PSBPreference.General.SrcRootDir | `$env:BHPSModulePath` | Root directory for the module |

Check warning on line 89 in README.md

View workflow job for this annotation

GitHub Actions / CI / Run Linters 

Unknown word (BHPS) Suggestions: (baps, bops, bhp, BHP, bps)
| $PSBPreference.General.ModuleName | `$env:BHProjectName` | The name of the module. This should match the basename of the PSD1 file |
| $PSBPreference.General.ModuleVersion | `\<computed>` | The version of the module |
| $PSBPreference.General.ModuleManifestPath | `$env:BHPSModuleManifest` | Path to the module manifest (PSD1) |

Check warning on line 92 in README.md

View workflow job for this annotation

GitHub Actions / CI / Run Linters 

Unknown word (BHPS) Suggestions: (baps, bops, bhp, BHP, bps)
| $PSBPreference.Build.OutDir | `$projectRoot/Output` | Output directory when building the module |
| $PSBPreference.Build.Dependencies | 'StageFiles, 'BuildHelp' | Default task dependencies for the `Build` task |
| $PSBPreference.Build.ModuleOutDir | `$outDir/$moduleName/$moduleVersion` | `For internal use only. Do not overwrite. Use '$PSBPreference.Build.OutDir' to set output directory` |
| $PSBPreference.Build.CompileModule | `$false` | Controls whether to "compile" module into single PSM1 or not |
| $PSBPreference.Build.CompileDirectories | `@('Enum', 'Classes', 'Private', 'Public')` | List of directories to "compile" into monolithic PSM1. Only valid when `$PSBPreference.Build.CompileModule` is `$true`. |
Expand All @@ -103,16 +102,16 @@
| $PSBPreference.Build.Exclude | `<empty>` | Array of files (regular expressions) to exclude when building module |
| $PSBPreference.Test.Enabled | `$true` | Enable/disable Pester tests |
| $PSBPreference.Test.RootDir | `$projectRoot/tests` | Directory containing Pester tests |
| $PSBPreference.Test.OutputFile | `$null` | Output file path Pester will save test results to |
| $PSBPreference.Test.OutputFile | `$projectRoot/testResults.xml` | Output file path Pester will save test results to |
| $PSBPreference.Test.OutputFormat | `NUnitXml` | Test output format to use when saving Pester test results |
| $PSBPreference.Test.ScriptAnalysis.Enabled | `$true` | Enable/disable use of PSScriptAnalyzer to perform script analysis |
| $PSBPreference.Test.ScriptAnalysis.FailBuildOnSeverityLevel | `Error` | PSScriptAnalyzer threshold to fail the build on |
| $PSBPreference.Test.ScriptAnalysis.SettingsPath | `./ScriptAnalyzerSettings.psd1` | Path to the PSScriptAnalyzer settings file |
| $PSBPreference.Test.CodeCoverage.Enabled | `$false` | Enable/disable Pester code coverage reporting |
| $PSBPreference.Test.CodeCoverage.Threshold | `.75` | Fail Pester code coverage test if below this threshold |
| $PSBPreference.Test.CodeCoverage.Files | `*.ps1, *.psm1` | Files to perform code coverage analysis on |
| $PSBPreference.Test.CodeCoverage.OutputFile | `coverage.xml` | Output file path (relative to Pester test directory) where Pester will save code coverage results to |
| $PSBPreference.Test.CodeCoverage.OutputFileFormat | `$null` | Test output format to use when saving Pester code coverage results |
| $PSBPreference.Test.CodeCoverage.Files | `@()` | Files to perform code coverage analysis on |
| $PSBPreference.Test.CodeCoverage.OutputFile | `$projectRoot/codeCoverage.xml` | Output file path where Pester will save code coverage results to. A relative path resolves against the Pester test directory. |
| $PSBPreference.Test.CodeCoverage.OutputFileFormat | `JaCoCo` | Test output format to use when saving Pester code coverage results |
| $PSBPreference.Test.ImportModule | `$false` | Import module from output directory prior to running Pester tests |
| $PSBPreference.Test.SkipRemainingOnFailure | `None` | Skip remaining tests after failure for selected scope. Options are None, Run, Container and Block. |
| $PSBPreference.Test.OutputVerbosity | `Detailed` | Set verbosity of output. Options are None, Normal, Detailed and Diagnostic. |
Expand All @@ -121,11 +120,10 @@
| $PSBPreference.Help.ConvertReadMeToAboutHelp | `$false` | Convert project readme into the module about file |
| $PSBPreference.Docs.RootDir | `$projectRoot/docs` | Directory PlatyPS markdown documentation will be saved to. Other content in this directory, such as a README or an images folder, is left alone. |
| $PSBPreference.Docs.Overwrite | `$false` | Overwrite the markdown files in the docs folder using the comment based help as the source of truth. |
| $PSBPreference.Docs.AlphabeticParamsOrder | `$false` | Order parameters alphabetically by name in PARAMETERS section. There are 5 exceptions: -Confirm, -WhatIf, -IncludeTotalCount, -Skip, and -First parameters will be the last. |
| $PSBPreference.Docs.ExcludeDontShow | `$false` | Exclude the parameters marked with `DontShow` in the parameter attribute from the help content. |

Check warning on line 123 in README.md

View workflow job for this annotation

GitHub Actions / CI / Run Linters 

Unknown word (Dont) Suggestions: (dent, dint, doit, dolt, dona)
| $PSBPreference.Docs.UseFullTypeName | `$false` | Indicates that the target document will use a full type name instead of a short name for parameters. |
| $PSBPreference.Publish.PSRepository | `PSGallery` | PowerShell repository name to publish |
| $PSBPreference.Publish.PSRepositoryApiKey | `$env:PSGALLERY_API_KEY` | API key to authenticate to PowerShell repository with |

Check warning on line 126 in README.md

View workflow job for this annotation

GitHub Actions / CI / Run Linters 

Unknown word (PSGALLERY) Suggestions: (psaltery, spaller, psaltry, psalter, psalters)
| $PSBPreference.Publish.PSRepositoryCredential | `$null` | Credential to authenticate to PowerShell repository with. Overrides `$psRepositoryApiKey` if defined |

## Modifying Task Dependencies
Expand Down
2 changes: 1 addition & 1 deletion instructions/repository-specific.instructions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -72,7 +72,7 @@
| `Build` | OutDir, ModuleOutDir, CompileModule, CompileDirectories, CopyDirectories, Exclude |
| `Test` | Enabled, RootDir, OutputFile/Format, ScriptAnalysis, CodeCoverage, ImportModule, etc. |
| `Help` | UpdatableHelpOutDir, DefaultLocale, ConvertReadMeToAboutHelp |
| `Docs` | RootDir, Overwrite, AlphabeticParamsOrder, ExcludeDontShow, UseFullTypeName |
| `Docs` | RootDir, Overwrite, ExcludeDontShow, UseFullTypeName |
| `Publish` | PSRepository, PSRepositoryApiKey, PSRepositoryCredential |
| `Sign` | Enabled, CertificateSource, CertStoreLocation, Thumbprint, EnvVar/PfxFile sources, TimestampServer, HashAlgorithm, FilesToSign, Catalog |
| `Sign.Catalog` | Enabled, Version, FileName |
Expand Down Expand Up @@ -268,7 +268,7 @@

- Triggers: manual dispatch, GitHub release published
- Runs on: `ubuntu-latest`
- Reads `PSGALLERY_API_KEY` secret, converts to `PSCredential`, runs

Check warning on line 271 in instructions/repository-specific.instructions.md

View workflow job for this annotation

GitHub Actions / CI / Run Linters 

Unknown word (PSGALLERY) Suggestions: (psaltery, spaller, psaltry, psalter, psalters)
`./build.ps1 -Task Publish -PSGalleryApiKey $cred -Bootstrap`

## Repo-Specific Conventions
Expand Down Expand Up @@ -349,9 +349,9 @@
| ------------------------- | ---------------------------------------------------- |
| `$env:BHProjectPath` | Repository root directory |
| `$env:BHProjectName` | Module name (from directory structure) |
| `$env:BHPSModulePath` | Path to module source directory |

Check warning on line 352 in instructions/repository-specific.instructions.md

View workflow job for this annotation

GitHub Actions / CI / Run Linters 

Unknown word (BHPS) Suggestions: (baps, bops, bhp, BHP, bps)
| `$env:BHPSModuleManifest` | Path to `.psd1` manifest |

Check warning on line 353 in instructions/repository-specific.instructions.md

View workflow job for this annotation

GitHub Actions / CI / Run Linters 

Unknown word (BHPS) Suggestions: (baps, bops, bhp, BHP, bps)
| `$env:BHModulePath` | Same as `BHPSModulePath` |

Check warning on line 354 in instructions/repository-specific.instructions.md

View workflow job for this annotation

GitHub Actions / CI / Run Linters 

Unknown word (BHPS) Suggestions: (baps, bops, bhp, BHP, bps)
| `$env:BHBuildSystem` | Detected CI system (e.g., `GitHubActions`, `Unknown`)|
| `$env:BHBranchName` | Current git branch |
| `$env:BHCommitMessage` | Latest git commit message |
Expand Down
80 changes: 62 additions & 18 deletions tests/IBTasks.tests.ps1
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,29 @@
#requires -module InvokeBuild,Psake

# Shared by both of the drift guards below, so each stays runnable on its own filter.
BeforeAll {
$script:moduleSourcePath = [IO.Path]::Combine(
(Split-Path -Path $PSScriptRoot -Parent), 'PowerShellBuild'
)
$script:defaultPreference = . ([IO.Path]::Combine($script:moduleSourcePath, 'build.properties.ps1'))

function script:Test-PreferencePath {
param($Root, [string[]]$Segment)
$node = $Root
foreach ($name in $Segment) {
if ($node -is [System.Collections.IDictionary] -and $node.Contains($name)) {
$node = $node[$name]
} else {
return $false
}
}
$true
}
}

Describe 'Invoke-Build Tasks' {
BeforeAll {
$manifest = Import-PowerShellDataFile -Path $env:BHPSModuleManifest

Check warning on line 26 in tests/IBTasks.tests.ps1

View workflow job for this annotation

GitHub Actions / CI / Run Linters 

Unknown word (BHPS) Suggestions: (baps, bops, bhp, BHP, bps)
$outputDir = [IO.Path]::Combine($ENV:BHProjectPath, 'Output')
$outputModDir = [IO.Path]::Combine($outputDir, $env:BHProjectName)
$outputModVerDir = [IO.Path]::Combine($outputModDir, $manifest.ModuleVersion)
Expand Down Expand Up @@ -54,24 +75,6 @@
# task NAME, which cannot see a divergence inside a task body.

BeforeAll {
$script:moduleSourcePath = [IO.Path]::Combine(
(Split-Path -Path $PSScriptRoot -Parent), 'PowerShellBuild'
)
$script:defaultPreference = . ([IO.Path]::Combine($script:moduleSourcePath, 'build.properties.ps1'))

function script:Test-PreferencePath {
param($Root, [string[]]$Segment)
$node = $Root
foreach ($name in $Segment) {
if ($node -is [System.Collections.IDictionary] -and $node.Contains($name)) {
$node = $node[$name]
} else {
return $false
}
}
$true
}

# Two references are expected not to resolve, both deliberately:
# Build.Keys - the hashtable's own Keys property, used to enumerate it
# Build.Dependencies - removed from the defaults on purpose; IB.tasks.ps1 reads it
Expand Down Expand Up @@ -99,3 +102,44 @@
$unresolvable -join ', ' | Should -BeNullOrEmpty
}
}

Describe 'Settings documented in the README' {

# The README settings table is what consumers actually read, and until now nothing tied it
# back to the defaults. $PSBPreference.Docs.AlphabeticParamsOrder survived its removal in
# psake/PowerShellBuild#105 there, and $PSBPreference.Build.Dependencies survived being
# replaced by the $PSB{TaskName}Dependency variables in #72, back in 0.7.0.
#
# 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.

BeforeAll {
# Documented settings that are deliberately absent from the defaults. Both task files
# forward these to Build-PSBuildModule only when the consumer has added the key, so
# defining them in build.properties.ps1 would inject empty strings into every
# compiled PSM1 instead of leaving the parameter defaults alone.
$script:documentedWithoutDefault = @(
'Build.CompileHeader'
'Build.CompileFooter'
'Build.CompileScriptHeader'
'Build.CompileScriptFooter'
)
}

It 'every setting the README table lists resolves against build.properties.ps1' {
$readMePath = [IO.Path]::Combine((Split-Path -Path $PSScriptRoot -Parent), 'README.md')
$documentedPath = [regex]::Matches(
(Get-Content -Path $readMePath -Raw),
'(?m)^\|\s*\$PSBPreference((?:\.[A-Za-z_][A-Za-z0-9_]*)+)'
).ForEach({ $_.Groups[1].Value.TrimStart('.') }) | Sort-Object -Unique

$documentedPath | Should -Not -BeNullOrEmpty -Because 'the regex must still match the table'

$undefined = $documentedPath.Where({
$_ -notin $script:documentedWithoutDefault -and
-not (Test-PreferencePath -Root $script:defaultPreference -Segment ($_ -split '\.'))
})

$undefined -join ', ' | Should -BeNullOrEmpty
}
}
Loading