Skip to content

docs: Correct dead paths and stale claims in repository instructions #188

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 1 commit into from
Aug 27, 2026
Merged

docs: Correct dead paths and stale claims in repository instructions #188

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
54 changes: 37 additions & 17 deletions instructions/repository-specific.instructions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,8 @@
— decided in the v1.0.0 roadmap (psake/PowerShellBuild#120). The support floor is Windows
PowerShell 5.1 or PowerShell 7.4+; CI runs Windows PowerShell 5.1 and the runners' current
PowerShell 7 release across Linux/Windows/macOS
- Cross-platform: Windows, Linux, macOS (CI matrix in `.github/workflows/test.yml`)
- Cross-platform: Windows, Linux, macOS (`.github/workflows/test.yml` delegates to the psake
organization's shared `ModuleCI.yml`, which holds the matrix)
- The module is **psake/PowerShellBuild** on PSGallery and GitHub; maintained by the psake org

## Repository Layout
Expand Down Expand Up @@ -137,7 +138,10 @@
| `Invoke-PSBuildModuleSigning` | Signs module files with an Authenticode certificate |
| `New-PSBuildFileCatalog` | Generates a `.cat` file catalog for the module |

Private helper: `Remove-ExcludedItem` — filters file system items by regex patterns during builds.
Private helpers in `PowerShellBuild/Private/`:

- `Remove-ExcludedItem` — filters file system items by regular expression patterns during builds
- `Get-PSBuildHelpLocale` — resolves the locale used for help generation

### Invoke-Build alias

Expand Down Expand Up @@ -247,28 +251,44 @@
- `tests/TestModule/` is a complete example module used to exercise PowerShellBuild's tasks.
It has its own `build.ps1`, `psakeFile.ps1`, `.build.ps1` (Invoke-Build), and Pester tests.

| Test file | Tests |
| ---------------------- | ----------------------------------------------------------------------- |
| `build.tests.ps1` | Module compilation, file staging, exclusion, header/footer injection |
| `Help.tests.ps1` | Help documentation completeness |
| `IBTasks.tests.ps1` | Invoke-Build task definitions |
| `Manifest.tests.ps1` | Module manifest validity |
| `Meta.tests.ps1` | Script analysis, best practices across module source |
| Test file | Tests |
| ---------------------------------------- | -------------------------------------------------------------------- |
| `build.tests.ps1` | Module compilation, file staging, exclusion, header/footer injection |
| `Build-PSBuildHelp.tests.ps1` | Markdown and MAML help generation (skipped without PlatyPS) |
| `Clear-PSBuildOutputFolder.tests.ps1` | Output directory removal |
| `Fixtures.tests.ps1` | The shared test fixture helpers themselves |
| `Get-PSBuildCertificate.tests.ps1` | Signing certificate resolution |
| `Get-PSBuildHelpLocale.tests.ps1` | Help locale resolution |
| `Help.tests.ps1` | Help documentation completeness |
| `IBTasks.tests.ps1` | Invoke-Build task definitions and the settings they reference |
| `Initialize-PSBuild.tests.ps1` | Build environment initialization |
| `Invoke-PSBuildModuleSigning.tests.ps1` | Authenticode signing of module files |
| `Manifest.tests.ps1` | Module manifest validity |
| `Meta.tests.ps1` | Text file formatting across the repository |
| `New-PSBuildFileCatalog.tests.ps1` | Catalog (`.cat`) file creation |
| `Test-PSBuildPester.tests.ps1` | Pester invocation and the Pester version floor |
| `Test-PSBuildScriptAnalysis.tests.ps1` | PSScriptAnalyzer invocation and severity handling |

Supporting files: `tests/MetaFixers.psm1` (helpers for `Meta.tests.ps1`) and `tests/fixtures/`
(`FixtureHelpers.psm1` plus the `PSBuildTestFixture` sample module it copies).

## CI / CD (GitHub Actions)

### Test workflow (`.github/workflows/test.yml`)

- Triggers: push to default branch, pull requests, manual dispatch
- Matrix: `ubuntu-latest`, `windows-latest`, `macOS-latest`
- Command: `./build.ps1 -Task Test -Bootstrap`
- Supports a `DEBUG` runner flag for verbose output
- Triggers: push to `main`, pull requests, manual dispatch
- The workflow itself defines no jobs of its own — it delegates to the psake organization's
shared workflow, `psake/.github/.github/workflows/ModuleCI.yml@main`. Change the shared
workflow, not `test.yml`, to change what CI runs
- The shared workflow lints (cspell plus PSScriptAnalyzer fix suggestions), then runs
`./build.ps1 -Task Test -Bootstrap` across a `ubuntu-latest`, `windows-latest`, `macOS-latest`
matrix on PowerShell 7 and again on Windows PowerShell 5.1, and publishes the test results

### Publish workflow (`.github/workflows/publish.yaml`)

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

Check warning on line 291 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 @@ -300,8 +320,8 @@
properties {
# These settings overwrite values supplied from the PowerShellBuild
# module and govern how those tasks are executed
$PSBPreference.Test.ScriptAnalysisEnabled = $false
$PSBPreference.Test.CodeCoverage.Enabled = $true
$PSBPreference.Test.ScriptAnalysis.Enabled = $false
$PSBPreference.Test.CodeCoverage.Enabled = $true
}

task default -depends Build
Expand Down Expand Up @@ -349,9 +369,9 @@
| ------------------------- | ---------------------------------------------------- |
| `$env:BHProjectPath` | Repository root directory |
| `$env:BHProjectName` | Module name (from directory structure) |
| `$env:BHPSModulePath` | Path to module source directory |

Check warning on line 372 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 373 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 374 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 All @@ -363,7 +383,7 @@
```text
Output/
└── PowerShellBuild/
└── 0.8.0/
└── <ModuleVersion>/ # the manifest's ModuleVersion, e.g. 0.8.2
├── Public/ # (when CompileModule = $false)
├── Private/
├── en-US/
Expand All @@ -384,7 +404,7 @@
hard cut + migration guide (no deprecation cycle), psake 5.x in scope. Phase-by-phase
breakdown lives in the tracking issue.

Migration guide path (created in Phase 1): `docs/migration/v0.8-to-v1.0.md`.
Migration guide path (created in Phase 1): `docs/migration-v0.8-to-v1.0.md`.

## Notes for AI Agents

Expand Down
Loading