From 85842951990e698e1656cd20e811d3905de452cc Mon Sep 17 00:00:00 2001 From: Trent Blackburn Date: Mon, 18 May 2026 23:06:17 -0400 Subject: [PATCH 1/5] 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) --- CHANGELOG.md | 8 ++ docs/migration-v0.8-to-v1.0.md | 139 +++++++++++++++++++++++++++++++++ 2 files changed, 147 insertions(+) create mode 100644 docs/migration-v0.8-to-v1.0.md diff --git a/CHANGELOG.md b/CHANGELOG.md index b74bd8f..0b7fea5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,14 @@ and this project adheres to [Semantic Versioning](http://semver.org/). ## Unreleased +### Added + +- Initialize v0.8 → v1.0 migration guide skeleton at + `docs/migration-v0.8-to-v1.0.md`. Includes an AI-assisted migration + prompt (referential style for IDE/CLI agents) and a format spec for + per-break entries that Phase 2 PRs will populate. Phase 1 of + [#120](https://github.com/psake/PowerShellBuild/issues/120). + ## [0.8.1] 2026-06-03 ### Fixed diff --git a/docs/migration-v0.8-to-v1.0.md b/docs/migration-v0.8-to-v1.0.md new file mode 100644 index 0000000..9d1b5e3 --- /dev/null +++ b/docs/migration-v0.8-to-v1.0.md @@ -0,0 +1,139 @@ +# Migrating from PowerShellBuild v0.8 to v1.0 + +This guide helps you upgrade a consumer `build.ps1` (or equivalent) from +PowerShellBuild **0.8.x** to **1.0.0**. + +It only covers **breaking changes**. For new features and bug fixes that +do not require user action, see [`CHANGELOG.md`](../CHANGELOG.md). + +## Quick Start + +> **Status:** no breaking changes have landed yet. This list will be +> populated by Phase 2 PRs as the migration to Microsoft.PowerShell.PlatyPS +> 1.x and psake 5.x progresses. +> +> Once entries exist, this section will summarize each break in one line +> with a link into the body below — so you can scan what's likely to +> affect you before reading the details. + +## AI-assisted migration + +If you use an IDE or CLI agent (Claude Code, GitHub Copilot in VS Code, +Copilot CLI, Cursor, Aider, etc.), you can ask it to migrate your build +file for you. From inside the repository you are migrating, paste this +prompt: + +```text +You are migrating a PowerShellBuild consumer's build configuration from +0.8.x to 1.0.0. + +Inputs: +- This migration guide: docs/migration-v0.8-to-v1.0.md in the + psake/PowerShellBuild repository on GitHub. Fetch and read it if you + have web or repo access; otherwise ask me to paste it. +- My build file (default: ./build.ps1; ask if it lives elsewhere or has + a different name). +- Any psake or Invoke-Build files my build file references. + +Task: +1. Read the migration guide's "Migration entries" section. +2. For each entry, check whether it applies to my file(s). +3. Apply applicable entries' migration steps. Preserve all customizations + not directly affected by the migration. +4. If you are uncertain how to apply an entry, leave the original code + in place and add a `# MIGRATION-REVIEW: ` comment on the + relevant line. +5. After editing, run my test suite if one is configured. If you don't + know how, ask. +6. Output: a summary of the changes you applied and any review flags + you raised. + +PowerShellBuild conventions worth knowing: +- The module is imported with `Import-Module PowerShellBuild`. +- Configuration goes through `$PSBPreference`, a hashtable populated in + build.ps1 before tasks are invoked. +- Invoke-Build users dot-source the alias after import: + `. PowerShellBuild.IB.Tasks`. +- psake users invoke via `-FromModule PowerShellBuild`. +``` + +**Notes on the workflow:** + +- The agent reads the migration guide and your build file directly. You + do not need to paste either into the prompt. +- If you are using a web chatbot (Claude.ai, ChatGPT, etc.) without + file-system access, paste the relevant entries from this guide and + your build file into the conversation alongside the prompt. +- Always review the agent's output before committing. The + `# MIGRATION-REVIEW:` markers (if any) flag lines that need a human + decision. + +## Migration entries + + + +### Example: `Invoke-PSBuildPlaceholder` renamed its `-LegacyOption` parameter + +> **This is an illustrative example only — not a real break.** + +The hypothetical function `Invoke-PSBuildPlaceholder` renamed its +`-LegacyOption` parameter to `-StandardOption`. The behavior is +otherwise unchanged. + +**Before (0.8.x):** + +```powershell +Invoke-PSBuildPlaceholder -LegacyOption 'value' +``` + +**After (1.0.0):** + +```powershell +Invoke-PSBuildPlaceholder -StandardOption 'value' +``` + +You will see a parameter-binding error referencing `LegacyOption` if you +do not migrate. + +Tracked in hypothetical PR #999. + +## Adding an entry (for PR contributors) + +Every breaking-change PR that lands in v1.0.0 must add an entry here for +each distinct user-visible break. + +Format conventions (loose — match what's useful for the specific break, +modeled on [`psake/psake docs/migration-v4-to-v5.md`](https://github.com/psake/psake/blob/main/docs/migration-v4-to-v5.md)): + +- `###` heading describing the change in user terms (not internal + terms — e.g. "`Build-PSBuildMarkdown` now requires a module page + path", not "PlatyPS 1.x signature change") +- A short prose paragraph: what changed and why +- A `**Before (0.8.x):**` / `**After (1.0.0):**` PowerShell code-block + pair, when the migration is a concrete code change +- A sentence on detection when not obvious from the code (the error + message a user will see, or a `grep` pattern to find affected code) +- A closing reference to the PR and any related issues + +Also: + +- Add a one-line summary to the **Quick Start** section above, linking + to your new entry's heading. +- Reference this guide from your PR description (the entry it adds). + +The illustrative example entry above can be deleted by the first real +entry's PR — it exists only to show the format. + +## Related + +- Tracking issue: [#120 — PowerShellBuild v1.0.0 roadmap](https://github.com/psake/PowerShellBuild/issues/120) +- Changelog (non-breaking changes and complete release history): + [`CHANGELOG.md`](../CHANGELOG.md) +- Sibling convention reference: + [`psake/psake docs/migration-v4-to-v5.md`](https://github.com/psake/psake/blob/main/docs/migration-v4-to-v5.md) From 133ff1cb47a5df162e0358593e48882fa58d14c8 Mon Sep 17 00:00:00 2001 From: Trent Blackburn Date: Sun, 28 Jun 2026 15:39:51 -0400 Subject: [PATCH 2/5] docs: name Invoke-Build's .build.ps1 default in migration prompt The AI-assisted migration prompt listed only ./build.ps1 as the default consumer build file. Invoke-Build users conventionally use ./.build.ps1 (as the repo's own README example does), so name both defaults to reduce agent back-and-forth. Addresses Copilot review feedback on #123. Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_015cqAkNY5JkcoroyEAmbeVj --- docs/migration-v0.8-to-v1.0.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/migration-v0.8-to-v1.0.md b/docs/migration-v0.8-to-v1.0.md index 9d1b5e3..d388849 100644 --- a/docs/migration-v0.8-to-v1.0.md +++ b/docs/migration-v0.8-to-v1.0.md @@ -31,8 +31,8 @@ Inputs: - This migration guide: docs/migration-v0.8-to-v1.0.md in the psake/PowerShellBuild repository on GitHub. Fetch and read it if you have web or repo access; otherwise ask me to paste it. -- My build file (default: ./build.ps1; ask if it lives elsewhere or has - a different name). +- My build file (default: ./build.ps1 for psake, or ./.build.ps1 for + Invoke-Build; ask if it lives elsewhere or has a different name). - Any psake or Invoke-Build files my build file references. Task: From 0a152c6c9e747d7845bb60fabcfda3b01d2aa0c8 Mon Sep 17 00:00:00 2001 From: Trent Blackburn Date: Sun, 28 Jun 2026 20:32:47 -0400 Subject: [PATCH 3/5] docs: make migration skeleton read sensibly pre-release Browsing docs/ before v1.0.0 ships, the migration guide implied either that there were no breaking changes or that it was unfinished, and the fictional example entry could be mistaken for a real break. - Add a pre-release banner stating v1.0.0 has not shipped and there is nothing to migrate yet, linking the roadmap (#120). - Replace the rendered fictional example with a "no entries yet" note and move the example into an HTML comment as a contributor-only template. No change to the entry format or AI-assisted prompt. Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_015cqAkNY5JkcoroyEAmbeVj --- docs/migration-v0.8-to-v1.0.md | 46 ++++++++++++++++++---------------- 1 file changed, 25 insertions(+), 21 deletions(-) diff --git a/docs/migration-v0.8-to-v1.0.md b/docs/migration-v0.8-to-v1.0.md index d388849..4bc90a7 100644 --- a/docs/migration-v0.8-to-v1.0.md +++ b/docs/migration-v0.8-to-v1.0.md @@ -1,5 +1,12 @@ # Migrating from PowerShellBuild v0.8 to v1.0 +> 🚧 **Pre-release.** v1.0.0 has not shipped yet, and no breaking changes +> have been documented here. This guide is being prepared alongside the +> v1.0.0 work; entries are added by each breaking-change PR as it lands. +> Track progress in +> [#120 — PowerShellBuild v1.0.0 roadmap](https://github.com/psake/PowerShellBuild/issues/120). +> If you are on 0.8.x today, there is nothing to migrate yet. + This guide helps you upgrade a consumer `build.ps1` (or equivalent) from PowerShellBuild **0.8.x** to **1.0.0**. @@ -70,38 +77,34 @@ PowerShellBuild conventions worth knowing: ## Migration entries - +_No breaking changes documented yet._ Each breaking-change PR adds its +entry here as it lands; see [Adding an entry](#adding-an-entry-for-pr-contributors) +below for the format. -### Example: `Invoke-PSBuildPlaceholder` renamed its `-LegacyOption` parameter + ## Adding an entry (for PR contributors) @@ -127,8 +130,9 @@ Also: to your new entry's heading. - Reference this guide from your PR description (the entry it adds). -The illustrative example entry above can be deleted by the first real -entry's PR — it exists only to show the format. +A commented-out template entry lives in the **Migration entries** section +above (visible only in the raw Markdown) — copy it as a starting point. +The first real entry's PR can remove that comment block. ## Related From 0b6f4be05466a94262156da0aa55fb540729d951 Mon Sep 17 00:00:00 2001 From: Trent Blackburn Date: Fri, 3 Jul 2026 10:05:42 -0400 Subject: [PATCH 4/5] docs: update cspell configuration to include specific words and ignore list --- cspell.json | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/cspell.json b/cspell.json index a8959d9..d136d00 100644 --- a/cspell.json +++ b/cspell.json @@ -9,10 +9,13 @@ "xml", "markdown" ], - "words": [], - "ignoreWords": [ + "words": [ + "Authenticode", "psake", "MAML" ], + "ignoreWords": [ + "ExcludeDontShow" + ], "import": [] } From f7288c13c1659ad5dba7f934c515717c0fabdd35 Mon Sep 17 00:00:00 2001 From: Trent Blackburn Date: Fri, 3 Jul 2026 10:18:41 -0400 Subject: [PATCH 5/5] docs: Drop changelog entry for migration guide skeleton The changelog is kept to user-facing changes (see 0.8.1 trim in #127), and the skeleton is contributor-facing scaffolding. The completed guide will get a single changelog line in the v1.0.0 release section instead. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01ABKBMXAzzrA7QY9XkLnYU7 --- CHANGELOG.md | 8 -------- 1 file changed, 8 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 0b7fea5..b74bd8f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,14 +7,6 @@ and this project adheres to [Semantic Versioning](http://semver.org/). ## Unreleased -### Added - -- Initialize v0.8 → v1.0 migration guide skeleton at - `docs/migration-v0.8-to-v1.0.md`. Includes an AI-assisted migration - prompt (referential style for IDE/CLI agents) and a format spec for - per-break entries that Phase 2 PRs will populate. Phase 1 of - [#120](https://github.com/psake/PowerShellBuild/issues/120). - ## [0.8.1] 2026-06-03 ### Fixed