Repository navigation
Release: finalize the migration guide, test the AI prompt, write the 1.0.0 changelog #159
Description
Activity
- added a parent issue
on Aug 20, 2026 Unblocked. This is now the only thing between the repository and 1.0.0.
Its gate read "blocked on
1.0.0-preview2— the break surface must be complete before the guide can be called finished." That condition is satisfied, but by scope rather than by a release: #83 and #156 are deferred to 1.1.0, so Phase 3 is empty and nothing further is going into 1.0.0 that breaks anything. #157 and #158 are closed as superseded; the cycle cuts one prerelease, therc1in #160.So the guide can be finished now, and it should be — the prerelease goes out after this, so soakers get finished documentation telling them what changed rather than an unfinished one.
Current state of the work:
docs/migration-v0.8-to-v1.0.mdis 747 lines across 12 sections. As this issue anticipated, the per-PR entries accumulated through the cycle, so this is a coherence and completeness pass rather than a writeup.- The AI migration prompt has still never been run. That is the substantive item here: it is a v1.0.0 deliverable that rewrites a consumer's
build.ps1, and shipping it untested is worse than shipping no prompt at all. - The 1.0.0 changelog entry is unwritten.
## Unreleasedhas accumulated the full break surface and needs summarizing.
One addition to the completeness pass, since the guide predates them: the cycle picked up several changes after most of those entries were written — the Pester 6.0.0 floor (#172), the psake 5.0.4 floor (#166),
Sign.SkipCertificateValidationactually working (#193), and the localized-string fix (#185). Worth checking each has an entry if it can require action on upgrade.- added a commit that references this issue
on Aug 28, 2026 PR #200 is merged, but this stays open deliberately.
Done
- Guide coherence pass. 12 entries → 17. Four the changelog carried and the guide did not (README examples assign a setting that does not exist: $PSBPreference.Test.ScriptAnalysisEnabled #191, Test-PSBuildPester coverage threshold math truncates every percentage to zero #138, IB.tasks.ps1 reads a nonexistent CodeCoverage.OutputFormat setting, so Invoke-Build users get $null #178, $PSBPreference.Sign.SkipCertificateValidation has no effect on the Store and Thumbprint sources it is documented for #193), plus two the prompt test proved were missing: exact-version pinning (the guide speaks in floors while
requirements.psd1takes exact pins, andplatyPSis replaced rather than upgraded) and the consumer's own manifest floor now being an untested claim. Table of contents verified programmatically — 17 headings, 17 links, no dangling anchors. - The AI prompt has been tested, four runs across two sample consumers and two model families. It found three defects that reading could never have surfaced, the worst being that agent web-fetch tools commonly return a summary rather than the document — one run lost three entries silently. Details in docs: Finalize the migration guide and test the AI migration prompt #200.
- Changelog 1.0.0 summary written, under
## Unreleasedfor Release: bump to 1.0.0 and publish to PSGallery #160 to rename.
Why this is not closed
The gate on this issue was that the break surface must be complete before the guide can be called finished. That was true this morning. It stopped being true this afternoon, when #98 and #103 came back into the 1.0.0 milestone.
Those are test-writing tickets, and on this project test-writing has found a defect every single time: #169 (updatable help had never worked — three of them), the
Get-PSBuildCertificatemocks that never reached the module, #197 (22 tests silently skipped on 5.1), #201 (found by accident). #98's own scope says to expect more. Any of those fixes that are user-facing need a guide entry, and #201 already looks like one.What is left here
A final coherence pass once #98 and #103 close:
- Re-check the changelog's
## Unreleasedentries against the guide's entries, the same way the first pass did — anything that can require action on upgrade needs an entry. - Re-verify the table of contents against the headings.
- Re-check the 1.0.0 changelog summary's "breaks that require action" table, since it was written against today's surface.
That is a short pass, not a rewrite. It exists so that #160's "blocked on the release documentation being final" means something.
- Guide coherence pass. 12 entries → 17. Four the changelog carried and the guide did not (README examples assign a setting that does not exist: $PSBPreference.Test.ScriptAnalysisEnabled #191, Test-PSBuildPester coverage threshold math truncates every percentage to zero #138, IB.tasks.ps1 reads a nonexistent CodeCoverage.OutputFormat setting, so Invoke-Build users get $null #178, $PSBPreference.Sign.SkipCertificateValidation has no effect on the Store and Thumbprint sources it is documented for #193), plus two the prompt test proved were missing: exact-version pinning (the guide speaks in floors while
Candidates for the coherence pass, not changes to make now — recording them so they are not
lost while the break surface settles.Testing the AI migration prompt against four real public consumer builds turned up three things
the guide covers nowhere. Each is verified against this repository's source and against the
consumer's own build file; I have said which parts I confirmed and which I did not.1. A consumer task that calls a platyPS 0.14.x cmdlet has nowhere to land
Confirmed. The guide explains the
YamlDotNetclash twice — under therequirements.psd1
entry and under "Help generation now uses Microsoft.PowerShell.PlatyPS 1.x" — but both times as
a reason to removeplatyPSfrom a dependency manifest. Neither addresses a consumer whose
own task body calls a 0.14.x cmdlet. Grepping the guide forNew-YamlHelp,
New-ExternalHelp,New-MarkdownHelp,Update-MarkdownHelpandNew-ExternalHelpCabreturns
nothing: no 0.14.x cmdlet is named anywhere in it.jimbrig/PSUtilsis the concrete case (psakeFile.ps1, lines 39-43):Task GenerateYAMLHelp -depends GenerateMarkdown { If (-not (Get-Command New-YamlHelp -CommandType Function -ErrorAction SilentlyContinue)) { Install-Module -Name platyPS -Repository PSGallery -Scope CurrentUser -Force } New-YamlHelp -Path './Docs/en-US' -OutputFolder './Docs/en-US' -Force
The task installs and imports
platyPS0.14.x on demand, into the same session where
GenerateMarkdownhas already importedMicrosoft.PowerShell.PlatyPS1.x — exactly the
collision the guide warns about, arriving from a direction the guide does not describe.
Following therequirements.psd1advice to the letter does not fix it; the task itself has to
change.There is a landing place worth mentioning: 1.x ships
Export-YamlCommandHelpand
Export-YamlModuleFile. Whether the guide should name the replacement or only flag the hazard
is a coherence-pass call.2. An Invoke-Build consumer can override
Task Testand lose script analysisConfirmed — and narrower than first described: it is an Invoke-Build-only hazard.
PowerShellBuild/IB.tasks.ps1line 201 defines:Task Test Analyze, Pesterpauby/PSTodoWarrior's.pstodowarrior.build.ps1dot-sourcesPowerShellBuild.IB.Taskson
line 2, sets these on lines 26-27:$PSBPreference.Test.ScriptAnalysis.Enabled = $true $PSBPreference.Test.ScriptAnalysis.FailBuildOnSeverityLevel = 'Error'
and then, on line 66, defines its own:
Task Test Pester
Reproduced against InvokeBuild 5.14.23 with a stand-in tasks file of the same shape: without the
redefinitionTestrunsAnalyzethenPester; with it, onlyPesterruns. The build reports
success and0 warningseither way. Invoke-Build does printRedefined task 'Test'.in the
build log, so "silently" is a little too strong — but that is a log line rather than a warning,
and it does not say thatAnalyzeis what got dropped. Those twoScriptAnalysissettings have
never taken effect and will not after migrating.The asymmetry seems worth the guide's while: psake refuses the same move. psake 5.0.4 throws
Task test has already been defined.frompublic/Task.ps1, so a psake consumer finds out
immediately. Only Invoke-Build consumers can carry this quietly.This is not a 1.0.0 break — it is pre-existing, and migrating neither causes it nor fixes it.
But the migration is the moment a consumer reads their build file closely, which may make it the
right moment to tell them to check.3. A task that rewrites
online version:stops matching anythingConfirmed on both sides, with a caveat: the guide is not silent on the key change, only on the
consequence.The rename is already documented, under "What the front matter becomes" (lines 726-727):
"schema:becomesPlatyPS schema version:,online version:becomesHelpUri:". I confirmed
the generated output independently — a document produced byNew-MarkdownCommandHelpon 1.0.3
carriesHelpUri: ''and noonline version:key at all.What is missing is the consequence for a consumer post-processing that front matter.
milestonesys/MilestonePSTools(psakefile.ps1) wires a task into the pipeline on line 81:$psake.context.tasks.GenerateMAML.DependsOn += @('SetOnlineHelpUrls', 'AddCommandRequirementsToDocs')
and that task matches on the old key, line 283:
if ($_ -match '^online version:.*$') {
A regular expression that matches nothing rewrites nothing and reports nothing. The task keeps
running, keeps succeeding, and the online help URLs quietly stop being set. A reader who reaches
the front-matter table has the fact they need; a reader who greps their own build file for
things the guide named does not, because the guide never connects the rename to the
pattern-matching a consumer may be doing against it.Known limitation of the prompt testing itself
Recording this as a limitation rather than a defect: every run of the prompt test fetched the
guide withcurl, so the guide's own warning — that a summarizing fetch tool drops entries —
was never exercised. An agent without shell access, which is precisely the case the warning is
written for, remains untested.Relatedly, the claim on lines 150-151 that "We measured three entries lost that way in testing"
was not re-verified by this work. It may well still hold; it is simply not among the things I
checked.
Part of #120 (Phase 5 — Release).
Scope
Finalize the consumer-facing release documentation, once the full break surface is known and soaking.
docs/migration-v0.8-to-v1.0.md— review end to end. Per-PR entries have been accumulating throughout the cycle by design, so this is a coherence and completeness pass, not a writeup from scratch. Confirm the scope decision holds: breaking changes plus behavioral changes that can require action on upgrade.build.ps1with an agent and fix what it gets wrong. An untested prompt that produces a brokenbuild.ps1is worse than no prompt.CHANGELOG.md— write the 1.0.0 entry, summarizing the breaks and linking to the migration guide.Gate
Blocked on every other v1.0.0 pull request being merged — the break surface must be complete before the guide can be called finished. Re-gated 2026-09-04: the preview and rc were dropped from the plan, so the gate is now the merge of #224, #225, #226, #227 and #228. This issue must close before 1.0.0 is tagged.
Done when
The migration guide is complete, the AI prompt has been verified against a sample consumer build, and the changelog entry is written.