Skip to content

Commit bbd2e08

Browse files
tablackburnclaude
tablackburn
and
claude
committed
docs: initialize v0.8 -> v1.0 migration guide skeleton
Phase 1 of #120. Creates docs/migration-v0.8-to-v1.0.md (matching the psake/psake docs/migration-v4-to-v5.md convention) with: - Scope blurb and Quick Start placeholder - AI-assisted migration prompt (referential style for IDE/CLI agents) - One labeled illustrative entry showing the loose format - "Adding an entry" spec for future breaking-change PRs Adds a one-line CHANGELOG entry under Unreleased. No code or dependency changes. Path diverges from #120's original spec (docs/migration/v0.8-to-v1.0.md) to match the org-level convention established by psake/psake. #120's body has been updated to reference the new flat path. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
1 parent 08b191a commit bbd2e08

2 files changed

Lines changed: 147 additions & 0 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,14 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
77

88
## Unreleased
99

10+
### Added
11+
12+
- Initialize v0.8 → v1.0 migration guide skeleton at
13+
`docs/migration-v0.8-to-v1.0.md`. Includes an AI-assisted migration
14+
prompt (referential style for IDE/CLI agents) and a format spec for
15+
per-break entries that Phase 2 PRs will populate. Phase 1 of
16+
[#120](https://github.com/psake/PowerShellBuild/issues/120).
17+
1018
## [0.8.0] 2026-02-20
1119

1220
### Added

‎docs/migration-v0.8-to-v1.0.md‎

Lines changed: 139 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,139 @@
1+
# Migrating from PowerShellBuild v0.8 to v1.0
2+
3+
This guide helps you upgrade a consumer `build.ps1` (or equivalent) from
4+
PowerShellBuild **0.8.x** to **1.0.0**.
5+
6+
It only covers **breaking changes**. For new features and bug fixes that
7+
do not require user action, see [`CHANGELOG.md`](../CHANGELOG.md).
8+
9+
## Quick Start
10+
11+
> **Status:** no breaking changes have landed yet. This list will be
12+
> populated by Phase 2 PRs as the migration to Microsoft.PowerShell.PlatyPS
13+
> 1.x and psake 5.x progresses.
14+
>
15+
> Once entries exist, this section will summarize each break in one line
16+
> with a link into the body below — so you can scan what's likely to
17+
> affect you before reading the details.
18+
19+
## AI-assisted migration
20+
21+
If you use an IDE or CLI agent (Claude Code, GitHub Copilot in VS Code,
22+
Copilot CLI, Cursor, Aider, etc.), you can ask it to migrate your build
23+
file for you. From inside the repository you are migrating, paste this
24+
prompt:
25+
26+
```text
27+
You are migrating a PowerShellBuild consumer's build configuration from
28+
0.8.x to 1.0.0.
29+
30+
Inputs:
31+
- This migration guide: docs/migration-v0.8-to-v1.0.md in the
32+
psake/PowerShellBuild repository on GitHub. Fetch and read it if you
33+
have web or repo access; otherwise ask me to paste it.
34+
- My build file (default: ./build.ps1; ask if it lives elsewhere or has
35+
a different name).
36+
- Any psake or Invoke-Build files my build file references.
37+
38+
Task:
39+
1. Read the migration guide's "Migration entries" section.
40+
2. For each entry, check whether it applies to my file(s).
41+
3. Apply applicable entries' migration steps. Preserve all customizations
42+
not directly affected by the migration.
43+
4. If you are uncertain how to apply an entry, leave the original code
44+
in place and add a `# MIGRATION-REVIEW: <reason>` comment on the
45+
relevant line.
46+
5. After editing, run my test suite if one is configured. If you don't
47+
know how, ask.
48+
6. Output: a summary of the changes you applied and any review flags
49+
you raised.
50+
51+
PowerShellBuild conventions worth knowing:
52+
- The module is imported with `Import-Module PowerShellBuild`.
53+
- Configuration goes through `$PSBPreference`, a hashtable populated in
54+
build.ps1 before tasks are invoked.
55+
- Invoke-Build users dot-source the alias after import:
56+
`. PowerShellBuild.IB.Tasks`.
57+
- psake users invoke via `-FromModule PowerShellBuild`.
58+
```
59+
60+
**Notes on the workflow:**
61+
62+
- The agent reads the migration guide and your build file directly. You
63+
do not need to paste either into the prompt.
64+
- If you are using a web chatbot (Claude.ai, ChatGPT, etc.) without
65+
file-system access, paste the relevant entries from this guide and
66+
your build file into the conversation alongside the prompt.
67+
- Always review the agent's output before committing. The
68+
`# MIGRATION-REVIEW:` markers (if any) flag lines that need a human
69+
decision.
70+
71+
## Migration entries
72+
73+
<!--
74+
EXAMPLE ENTRY — REPLACE OR REMOVE WHEN THE FIRST REAL ENTRY LANDS.
75+
76+
This entry uses a FICTIONAL change to demonstrate the format. Real
77+
entries are added by Phase 2 PRs as breaking changes land. See
78+
"Adding an entry" below for the spec.
79+
-->
80+
81+
### Example: `Invoke-PSBuildPlaceholder` renamed its `-LegacyOption` parameter
82+
83+
> **This is an illustrative example only — not a real break.**
84+
85+
The hypothetical function `Invoke-PSBuildPlaceholder` renamed its
86+
`-LegacyOption` parameter to `-StandardOption`. The behavior is
87+
otherwise unchanged.
88+
89+
**Before (0.8.x):**
90+
91+
```powershell
92+
Invoke-PSBuildPlaceholder -LegacyOption 'value'
93+
```
94+
95+
**After (1.0.0):**
96+
97+
```powershell
98+
Invoke-PSBuildPlaceholder -StandardOption 'value'
99+
```
100+
101+
You will see a parameter-binding error referencing `LegacyOption` if you
102+
do not migrate.
103+
104+
Tracked in hypothetical PR #999.
105+
106+
## Adding an entry (for PR contributors)
107+
108+
Every breaking-change PR that lands in v1.0.0 must add an entry here for
109+
each distinct user-visible break.
110+
111+
Format conventions (loose — match what's useful for the specific break,
112+
modeled on [`psake/psake docs/migration-v4-to-v5.md`](https://github.com/psake/psake/blob/main/docs/migration-v4-to-v5.md)):
113+
114+
- `###` heading describing the change in user terms (not internal
115+
terms — e.g. "`Build-PSBuildMarkdown` now requires a module page
116+
path", not "PlatyPS 1.x signature change")
117+
- A short prose paragraph: what changed and why
118+
- A `**Before (0.8.x):**` / `**After (1.0.0):**` PowerShell code-block
119+
pair, when the migration is a concrete code change
120+
- A sentence on detection when not obvious from the code (the error
121+
message a user will see, or a `grep` pattern to find affected code)
122+
- A closing reference to the PR and any related issues
123+
124+
Also:
125+
126+
- Add a one-line summary to the **Quick Start** section above, linking
127+
to your new entry's heading.
128+
- Reference this guide from your PR description (the entry it adds).
129+
130+
The illustrative example entry above can be deleted by the first real
131+
entry's PR — it exists only to show the format.
132+
133+
## Related
134+
135+
- Tracking issue: [#120 — PowerShellBuild v1.0.0 roadmap](https://github.com/psake/PowerShellBuild/issues/120)
136+
- Changelog (non-breaking changes and complete release history):
137+
[`CHANGELOG.md`](../CHANGELOG.md)
138+
- Sibling convention reference:
139+
[`psake/psake docs/migration-v4-to-v5.md`](https://github.com/psake/psake/blob/main/docs/migration-v4-to-v5.md)

0 commit comments

Comments
 (0)