[Tracking] PowerShellBuild v1.0.0 roadmap

[tablackburn]

[Tracking] PowerShellBuild v1.0.0 roadmap

Goal: ship PowerShellBuild 1.0.0 — the first version with a stable public-API contract per SemVer. Treats the 0.x line as initial development per SemVer §4; 1.0.0 defines the public API per SemVer §5.

Status: planning → execution
Current version: 0.8.0
Target version: 1.0.0
Prerelease cadence: 1.0.0-preview.N to PSGallery after each phase
Branching: PRs land directly on main (allowed under 0.x); 1.0.0 cuts when scope is complete

Why 1.0.0 and not 2.0.0: there has never been a stable 1.x. Jumping to 2.0.0 would imply a prior stable 1.x existed. SemVer says go to 1.0.0.

---

Locked-in decisions

Decision	Choice
Version	1.0.0 (not 2.0.0)
Tracking	This issue + v1.0.0 milestone + GitHub Project board
AIM deployment	Phase 0 (first PR)
Branching	PRs to main + 1.0.0-preview.N prereleases
Breaking changes	Hard cut + migration guide
Migration guide	docs/migration/v0.8-to-v1.0.md; per-PR entries; AI-assisted prompt at top
Auto-migration tool	None
Deprecation cycle	None (skip 0.9.0)
psake 5.x	In scope for 1.0.0
Minimum PS version	TBD — Phase 1 investigation

---

Migration guide

Lives at docs/migration/v0.8-to-v1.0.md. Every breaking-change PR must add an entry using the standard structure (What changed / Why / Detection / Migration / Notes). Enforced via PR template checkbox. Top-of-file section includes a canonical AI prompt users can paste into their agent to migrate their build.ps1 automatically.

---

Phase 0 — Foundation

• Deploy AIM to the repo
  • Add AGENTS.md, aim.config.json, instructions/
  • Migrate CLAUDE.md content → instructions/repository-specific.instructions.md
  • Modules to include: agent-workflow, shorthand, git-workflow, testing, powershell, markdown, releases, github-cli, readme, contributing, update, repository-specific
  • Fix stale version reference (CLAUDE.md says 0.7.3; actual is 0.8.0)

Phase 1 — Conventions & guardrails

• Add PR template (requires migration-guide entry checkbox for breaking changes)
• Initialize docs/migration/v0.8-to-v1.0.md skeleton
• Create v1.0.0 milestone, link this issue
• Create GitHub Project board (Now / Next / Later / Done)
• Investigate minimum PowerShell version for v1.0.0 — gated by Microsoft.PowerShell.PlatyPS 1.x and psake 5.x requirements. Record decision here.
• Audit PowerShellVersion in PowerShellBuild.psd1 (currently '3.0', almost certainly wrong) and CI matrix
• Confirm branch protection on main (PR + 1 review + CI green)
• Cut 1.0.0-preview.1 after Phase 1 completes

Phase 2 — Breaking dependency upgrades

#105 — PlatyPS migration

Split into focused PRs so each is independently reviewable:

• PR 2a — add Microsoft.PowerShell.PlatyPS 1.x to requirements.psd1 alongside old platyPS (parallel install); update CI workflows
• PR 2b — migrate Build-PSBuildMarkdown to New-MarkdownCommandHelp; add tests (Tests: Build-PSBuildMarkdown #99) against new API
• PR 2c — migrate Build-PSBuildMAMLHelp to Import-MarkdownCommandHelp | Export-MamlCommandHelp; add tests (Tests: Build-PSBuildMAMLHelp #100) against new API
• PR 2d — migrate Build-PSBuildUpdatableHelp to new cab pipeline; add tests (Tests: Build-PSBuildUpdatableHelp #101, Windows-only) against new API
• PR 2e — one-shot migrate existing docs/ markdown via Measure-PlatyPSMarkdown | Import-MarkdownCommandHelp | Export-MarkdownCommandHelp
• PR 2f — remove old platyPS from requirements.psd1; clean up references

psake 5.x bump

• Spike PR — assess what actually breaks in this repo's psakeFile.ps1 and the consumer-facing PowerShellBuild/psakeFile.ps1 under psake 5.x. Document findings here before committing to a migration approach.
• Migration PR(s) — number depends on spike findings
• Cut 1.0.0-preview.2 after Phase 2 completes

Phase 3 — API improvements

• Add support for passing a PesterConfiguration object to PowerShellBuild #83 — PesterConfiguration object support via parameter set + $PSBPreference.Test.Configuration (per joshooaj's design in Add support for configuring Pester's SkipRemainingOnFailure and Verbosity options #80)
• Close Add support for configuring Pester's SkipRemainingOnFailure and Verbosity options #80 as superseded by Add support for passing a PesterConfiguration object to PowerShellBuild #83
• Cut 1.0.0-preview.3 after Phase 3 completes

Phase 4 — Test infrastructure

In v1.0.0:

• Tests: Create shared fixture module #97 — shared fixture module at tests/fixtures/TestModule/ (prerequisite)
• Tests: Build-PSBuildMarkdown #99 — Build-PSBuildMarkdown tests (folded into PR 2b)
• Tests: Build-PSBuildMAMLHelp #100 — Build-PSBuildMAMLHelp tests (folded into PR 2c)
• Tests: Build-PSBuildUpdatableHelp #101 — Build-PSBuildUpdatableHelp tests (folded into PR 2d)

Tracked but not blocking 1.0.0 (welcome contributions during the cycle):

• Tests: Clear-PSBuildOutputFolder #94 Clear-PSBuildOutputFolder (good first issue)
• Tests: Initialize-PSBuild #95 Initialize-PSBuild (good first issue)
• Tests: Test-PSBuildScriptAnalysis #96 Test-PSBuildScriptAnalysis (good first issue)

Deferred to 1.1.0:

• Tests: Build-PSBuildModule #98, Tests: Test-PSBuildPester #102, Tests: Publish-PSBuildModule #103, Additional Pester tests needed #17 umbrella

Phase 5 — Release

• Finalize docs/migration/v0.8-to-v1.0.md
• Write CHANGELOG.md 1.0.0 entry (summarizes breaks, links to migration guide)
• Bump ModuleVersion to 1.0.0
• Cut 1.0.0-rc.1; soak for ~1 week with announcement
• Cut 1.0.0 GitHub Release; publish to PSGallery

---

Definition of done

• All "in v1.0.0" checkboxes above are checked
• Migration guide is complete and AI-prompt-tested against a sample consumer build.ps1
• 1.0.0-rc.N has soaked for ≥ 7 days with no blocker reports
• CHANGELOG and README updated
• AIM Last sync field current

---

AI-assisted-development notes

• Keep PRs small (≤ ~400 lines diff where feasible) so they fit in agent context
• Each PR description should reference this tracking issue and the relevant phase
• The AIM instructions/ files are the canonical guide for any agent working in this repo — agents must read agent-workflow.instructions.md first
• Conventional commit prefixes (feat:, fix:, docs:, chore:, BREAKING CHANGE:) to keep history machine-parseable

[tablackburn]

Phase 0 PR opened (draft): #122

Status of Phase 0 checklist (boxes to tick in the issue body once #122 merges):

• Add AGENTS.md, aim.config.json, instructions/
• Migrate CLAUDE.md content → instructions/repository-specific.instructions.md
• Modules included: agent-workflow, shorthand, git-workflow, testing, powershell, markdown, releases, github-cli (plus readme, contributing, update, repository-specific — flagged in the PR description; happy to drop any if the 8-module list here was intentional)
• Fix stale version reference (CLAUDE.md said 0.7.3; actual is 0.8.0; public function count corrected 9 → 12)

After this lands, Phase 1 (Conventions & guardrails) begins.