Overhaul migration guide: phased playbook + 7 deep-dive articles#12949
Overhaul migration guide: phased playbook + 7 deep-dive articles#12949SufficientDaikon wants to merge 2 commits into
Conversation
Restructure the migration story from a feature overview into an actionable, phased migration playbook (assess → install → migrate → validate → rollback). Add 7 new deep-dive articles covering the top community pain points: script auditing, module compatibility, encoding changes, profile migration, enterprise deployment, scheduled task automation, and testing/rollback. Hub-and-spoke architecture: the rewritten migration guide links to deep-dive articles for details, and every deep-dive links to the existing differences-from-windows-powershell.md for technical reference rather than duplicating it. Fixes MicrosoftDocs#12948 New files: - whats-new/migration/script-compatibility-audit.md - whats-new/migration/module-compatibility-strategy.md - whats-new/migration/encoding-changes.md - whats-new/migration/profile-migration.md - whats-new/migration/enterprise-deployment.md - whats-new/migration/scheduled-tasks-automation.md - whats-new/migration/testing-and-rollback.md Updated files: - whats-new/Migrating-from-Windows-PowerShell-51-to-PowerShell-7.md - whats-new/differences-from-windows-powershell.md - whats-new/module-compatibility.md - whats-new/overview.yml - toc.yml Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
PoliCheck Scan ReportThe following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans. ✅ No issues foundMore information about PoliCheckInformation: PoliCheck | Severity Guidance | Term |
PoliCheck Scan ReportThe following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans. ✅ No issues foundMore information about PoliCheckInformation: PoliCheck | Severity Guidance | Term |
There was a problem hiding this comment.
Pull request overview
This PR restructures the Windows PowerShell 5.1 → PowerShell 7 migration documentation into a phased, actionable playbook and adds a set of focused migration deep-dive articles, with TOC/landing-page integration and cross-links from existing reference docs.
Changes:
- Rewrites the main migration guide into a phased migration playbook (assess → install → migrate → validate/rollback).
- Adds 7 new migration deep-dive articles (scripts, modules, encoding, profiles, enterprise deployment, scheduled tasks, testing/rollback).
- Updates navigation and cross-links (TOC, landing page, differences/module-compat docs) to point to the new content.
Reviewed changes
Copilot reviewed 12 out of 12 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| reference/docs-conceptual/whats-new/Migrating-from-Windows-PowerShell-51-to-PowerShell-7.md | Rewritten into a phased migration playbook that links out to deep dives. |
| reference/docs-conceptual/whats-new/migration/script-compatibility-audit.md | New deep dive on auditing scripts and common breaking changes/removals. |
| reference/docs-conceptual/whats-new/migration/module-compatibility-strategy.md | New deep dive on module testing and the WinPS compatibility layer. |
| reference/docs-conceptual/whats-new/migration/encoding-changes.md | New deep dive on encoding default changes and mitigation strategies. |
| reference/docs-conceptual/whats-new/migration/profile-migration.md | New deep dive on profile path differences and sharing strategies. |
| reference/docs-conceptual/whats-new/migration/enterprise-deployment.md | New deep dive on enterprise deployment options and constrained-network considerations. |
| reference/docs-conceptual/whats-new/migration/scheduled-tasks-automation.md | New deep dive on migrating Task Scheduler/PSScheduledJob-style automation. |
| reference/docs-conceptual/whats-new/migration/testing-and-rollback.md | New deep dive on validation approach, checklist, and rollback procedures. |
| reference/docs-conceptual/whats-new/differences-from-windows-powershell.md | Adds a TIP box pointing readers to the phased migration guide. |
| reference/docs-conceptual/whats-new/module-compatibility.md | Adds a Windows management module compatibility table and links to the module strategy deep dive. |
| reference/docs-conceptual/whats-new/overview.yml | Adds a “Migration deep dives” landing card linking into the new articles. |
| reference/docs-conceptual/toc.yml | Adds the new migration deep-dive articles under the migration guide in the TOC. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| - text: Profile migration | ||
| url: ./migration/profile-migration.md | ||
| - text: Enterprise deployment | ||
| url: ./migration/enterprise-deployment.md |
| if ($bytes[0] -eq 0xEF -and $bytes[1] -eq 0xBB) { | ||
| Write-Host 'UTF-8 with BOM' | ||
| } | ||
| elseif ($bytes[0] -eq 0xFF -and $bytes[1] -eq 0xFE) { | ||
| Write-Host 'UTF-16 LE' | ||
| } | ||
| else { | ||
| Write-Host 'UTF-8 without BOM (PowerShell 7 default)' | ||
| } |
|
Learn Build status updates of commit 2807a2a: 💡 Validation status: suggestions
reference/docs-conceptual/whats-new/migration/testing-and-rollback.md
For more details, please refer to the build report. Note: Your PR may contain errors or warnings or suggestions unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them. |
PR Summary
Restructure the Windows PowerShell 5.1 → PowerShell 7 migration story from
a feature overview into an actionable, phased migration playbook with
7 new deep-dive articles covering the top community pain points.
Addresses #12948.
PR Checklist
it proposes.
change.
At a glance
The existing migration doc (
Migrating-from-Windows-PowerShell-51-to-PowerShell-7.md)tells readers what PowerShell 7 offers but not how to migrate.
The differences doc is a thorough technical reference but is not
actionable. This PR creates a hub-and-spoke model:
(assess → install → migrate → validate → rollback)
backed by community issue data
(no duplication)
Pain points covered (with issue evidence)
module-compatibility-strategy.mdmodule-compatibility-strategy.mdencoding-changes.mdenterprise-deployment.mdprofile-migration.mdscript-compatibility-audit.mdscheduled-tasks-automation.mdFiles changed
Migrating-from-Windows-PowerShell-51-to-PowerShell-7.mdmigration/script-compatibility-audit.mdmigration/module-compatibility-strategy.mdmigration/encoding-changes.mdmigration/profile-migration.mdmigration/enterprise-deployment.mdmigration/scheduled-tasks-automation.mdmigration/testing-and-rollback.mddifferences-from-windows-powershell.mdmodule-compatibility.mdoverview.ymltoc.ymlTotal: 12 files, +2,209/-246 lines
Design principles
the differences doc
markdownlintwith repo config (100-charlines, ATX headers, backtick fences, dash lists, proper name
capitalization)
Scope and limitations
unix-support.md. DSC migration — extensive enough for a separate PR. PowerShell 5.1 end-of-life policy — owned by Microsoft product team.differences-from-windows-powershell.mdis left as-is except for a TIP box cross-link. It serves as the canonical technical reference; deep-dive articles link into it by section anchor rather than duplicating content.