Skip to content

Commit 3c5277d

Browse files
tablackburnclaude
tablackburn
and
claude
authored
docs: initialize v0.8 to v1.0 migration guide skeleton (#123)
Phase 1 of [#120](#120). Initializes `docs/migration-v0.8-to-v1.0.md` so Phase 2+ breaking PRs have a defined home for migration entries and the v1.0.0 deliverable AI-assisted migration prompt has a stable, versioned location. ## What's included - **`docs/migration-v0.8-to-v1.0.md`** (new) — empty skeleton with: - **Pre-release banner** — states v1.0.0 has not shipped and there is nothing to migrate yet, linking #120. Keeps the guide from reading as misleading/unfinished to anyone browsing `docs/` before the release. - Scope blurb (audience, non-scope link to `CHANGELOG.md`) - **Quick Start** placeholder ("no breaking changes have landed yet; this list will be populated by Phase 2 PRs") - **AI-assisted migration prompt** — referential style, designed for IDE/CLI agents (Claude Code, Copilot CLI/Chat, Cursor, Aider) that have file-system access. Tells the agent to read this guide + the user's build file and migrate it; flags uncertain spots with `# MIGRATION-REVIEW:` comments. - **Migration entries** section showing a "no entries yet" note. The illustrative example (fictional break) lives in an **HTML comment** as a contributor-only template, so it is not rendered to readers; the first real Phase 2 PR can remove it. - **Adding an entry** spec for PR contributors — loose format conventions modeled on [`psake/psake docs/migration-v4-to-v5.md`](https://github.com/psake/psake/blob/main/docs/migration-v4-to-v5.md): heading + prose + `Before`/`After` code blocks, with the rigid 5-field template downgraded to suggested subsections. - **Related** links to #120 and the sibling-repo convention. - **`CHANGELOG.md`** — one-line entry under `## Unreleased` / `### Added`. ## Org convention alignment Path diverges from #120's original spec: - **#120's original:** `docs/migration/v0.8-to-v1.0.md` (nested in a `migration/` subdirectory) - **This PR:** `docs/migration-v0.8-to-v1.0.md` (flat) Reason: [`psake/psake`](https://github.com/psake/psake) already ships a sibling-pattern migration guide at `docs/migration-v4-to-v5.md`. Matching the org convention reduces cross-repo friction. #120's body has been updated to reference the new path. ## Scope Docs-only — no code, dependency, or workflow changes. The illustrative entry is fictional, kept in an HTML comment as a contributor template, and can be removed by the first real Phase 2 PR. ## Not in this PR - `instructions/git-workflow.instructions.md` — left alone (upstream AIM template). The "Adding an entry" spec for PR authors lives inside the migration file itself. - Real migration entries — added by Phase 2 PRs as breaks land. ## Test plan - [x] CI passes (existing required checks) - [x] Visual review (VS Code Markdown preview): prompt block renders as a code block, entry headings anchor cleanly - [x] Confirm flat path matches the `psake/psake` convention 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
1 parent 7103ced commit 3c5277d

2 files changed

Lines changed: 148 additions & 2 deletions

File tree

‎cspell.json‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -9,10 +9,13 @@
99
"xml",
1010
"markdown"
1111
],
12-
"words": [],
13-
"ignoreWords": [
12+
"words": [
13+
"Authenticode",
1414
"psake",
1515
"MAML"
1616
],
17+
"ignoreWords": [
18+
"ExcludeDontShow"
19+
],
1720
"import": []
1821
}

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

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