Optimize SPFx release pages for agentic upgrade workflows#10921
Optimize SPFx release pages for agentic upgrade workflows#10921garrytrinder wants to merge 12 commits into
Conversation
Replace the TIP recommending CLI for Microsoft 365 for upgrades with a WARNING explaining that upgrading from a previous minor version requires changes across package versions, build configuration files, and toolchain settings. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Add a TIP after the WARNING on each release page showing the exact npx command to run for upgrading to that specific version using CLI for Microsoft 365's spfx project upgrade command. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…warning The snippet now contains a WARNING, so the filename should reflect that. Updated all references across release pages and the template. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
|
Learn Build status updates of commit 90e3802: ❌ Validation status: errorsPlease follow instructions here which may help to resolve issue.
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. |
|
Learn Build status updates of commit 90e3802: ❌ Validation status: errorsPlease follow instructions here which may help to resolve issue.
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. |
Replace the TIP recommending CLI for Microsoft 365 for upgrades with a WARNING explaining that upgrading from a previous minor version requires changes across package versions, build configuration files, and toolchain settings. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Add a TIP after the WARNING on each release page showing the exact npx command to run for upgrading to that specific version using CLI for Microsoft 365's spfx project upgrade command. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…warning The snippet now contains a WARNING, so the filename should reflect that. Updated all references across release pages and the template. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…nder-replace-cli-upgrade-tips-with-warning
garrytrinder
force-pushed
the
garrytrinder-replace-cli-upgrade-tips-with-warning
branch
from
90e3802 to
1dd128e
Compare
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 |
|
Learn Build status updates of commit 1dd128e:
|
Include the existing pnp-o365cli NOTE snippet after the upgrade TIP on each SPFx release page and the template. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.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 |
|
Learn Build status updates of commit f2ddca8:
|
Update anchor from Azure AD to Entra ID to match the renamed heading in use-aadhttpclient.md. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.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 |
These pages were missing the warning snippet, version-specific TIP, and community disclaimer that were added to all other release pages. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.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 |
|
Learn Build status updates of commit c9853a9: 💡 Validation status: suggestions
This comment lists only the first 25 files in the pull request. docs/spfx/release-1.22.0.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. |
|
Set to draft, found some inconsistencies that I need to investigate. |
- Update TIP description across all release pages to mention the single script output - Rewrite migrate-gulptoolchain-hefttoolchain.md to direct users to CLI for Microsoft 365 instead of manual step-by-step instructions - Update release-1.22.0 upgrade section to reference migration page after the warning/tip/disclaimer block - Remove redundant 'See more details' section from release-1.22.0 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.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 |
|
Learn Build status updates of commit 520e4c6: 💡 Validation status: suggestions
This comment lists only the first 25 files in the pull request. docs/spfx/release-1.22.0.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. |
Replace absolute learn.microsoft.com URL with relative path and remove pinned view parameter. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.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 |
|
Learn Build status updates of commit 1d58183: ✅ Validation status: passed
This comment lists only the first 25 files in the pull request. |
garrytrinder
changed the title
andrewconnell
left a comment
andrewconnell
left a comment
There was a problem hiding this comment.
WRT one file in this PR: docs/spfx/toolchain/migrate-gulptoolchain-hefttoolchain.md ...
While there is value in providing the CLI upgrade steps, but want to get approval from @VesaJuvonen about removing all detailed steps & documentation on what changed.
Some companies can't use open source/community tools, while others can't unless it goes through a rigorous security review. Only providing instructions for a tool that some people might not be allowed to use removes a resource. IMHO, both options should be present, not just the CLI option.
Flagging & requesting @VesaJuvonen review to make the decsision.
| description: In this article, you'll learn how to migrate an existing SharePoint Framework v1.21.1 project based on the legacy Gulp-based build toolchain to the Heft-based build toolchain introduced in SPFx v1.22.\*. | ||
| ms.date: 12/30/2025 | ||
| description: Learn what changes when migrating a SharePoint Framework project from the Gulp-based build toolchain to the Heft-based build toolchain introduced in SPFx v1.22, and how to perform the migration using CLI for Microsoft 365. | ||
| ms.date: 05/21/2026 |
There was a problem hiding this comment.
Please revert this change to the ms.date as it shouldn't be modified. This is the date the article was published.
The rendering engine uses the git history for the file to indicate when it was last updated.
|
|
||
| ## Upgrading projects from the SPFx v1.21.1 to v1.22.0 version | ||
|
|
||
| The upgrade steps required to convert a [gulp-based toolchain](toolchain/sharepoint-framework-toolchain.md) SPFx project to the [Heft-based toolchain](toolchain/sharepoint-framework-toolchain-rushstack-heft.md) are detailed in the following article: [Migrate from the Gulp Toolchain to Heft Toolchain](toolchain/migrate-gulptoolchain-hefttoolchain.md). |
There was a problem hiding this comment.
Pending peer review by @VesaJuvonen, if we keep the detailed steps in the migration doc, linking to the migration doc with a callout that it covers detailed steps should remain.
| [!INCLUDE [pnp-o365cli](../../includes/snippets/open-source/pnp-o365cli.md)] | ||
|
|
||
| Starting with SPFx v1.22.0, new projects use Heft as the build task orchestrator instead of a [gulp-based toolchain](./toolchain/sharepoint-framework-toolchain.md) used in SPFx v1.0 - v1.21.1 releases. This change represents a fundamental shift in how SPFx projects are built, configured, and customized, though the underlying bundling technology (webpack) remains the same. | ||
| For an overview of what changes during this migration from the [Gulp-based toolchain](toolchain/sharepoint-framework-toolchain.md) to the [Heft-based toolchain](toolchain/sharepoint-framework-toolchain-rushstack-heft.md), see: [Migrate from the Gulp Toolchain to Heft Toolchain](toolchain/migrate-gulptoolchain-hefttoolchain.md). |
There was a problem hiding this comment.
Pending peer review by @VesaJuvonen for the big change in the migration doc, if we keep the detailed steps, this should be reverted as the previous edit in this file will make this repetitive.
andrewconnell
added
pr:awaiting-peer-reviews
2 participants
Summary
Updates all SPFx release notes pages and the Gulp-to-Heft migration guide to improve upgrade guidance by directing developers to use CLI for Microsoft 365.
Changes
All release pages (40 files)
package.jsonalone will cause build failures.npxcommand to runm365 spfx project upgrade --toVersion <version>for each release page.pnp-o365clisnippet) clarifying CLI for Microsoft 365 is open-source with no Microsoft SLA.spfx-release-upgrade-tip.md→spfx-release-upgrade-warning.mdto reflect its new content.docs/spfx/release-1.22.0.mddocs/spfx/toolchain/migrate-gulptoolchain-hefttoolchain.mdm365 spfx project upgradeto generate the full set of changes automatically.