Restructure Package Support Framework docs into a step-by-step workflow - #503
Open
Roy (RDMacLachlan) wants to merge 3 commits into
Open
Restructure Package Support Framework docs into a step-by-step workflow#503Roy (RDMacLachlan) wants to merge 3 commits into
Roy (RDMacLachlan) wants to merge 3 commits into
Conversation
Split the monolithic "Get started with the Package Support Framework" article into four step articles, turn the get-started article into a workflow hub, and add a releases section plus links to the step-by-step guidance in the overview. - Add "Step 1: Identify compatibility issues in an MSIX container" - Add "Step 2: Find a runtime fix" - Add "Step 3: Apply a runtime fix to your MSIX package" - Add "Step 4: Debug or extend a runtime fix" - Rewrite the get-started article as a hub with prerequisites, the four-step workflow, and shortcuts for common failures - Rewrite the overview with the component and runtime fix inventory, a Package Support Framework releases table, fixup metadata and upgrade guidance, corrected limitations, and links to each step - Correct the workingDirectory description: the launcher resolves a relative path against the package root and uses the package root when the value is omitted or empty - Update the TOC and retarget the config.json deep link in the scripts article AB#26009108 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 8c8ebcee-56c3-4dda-8689-ec59a4e2e87a
Contributor
|
Learn Build status updates of commit 90d2c2b: 💡 Validation status: suggestions
msix-src/psf/psf-apply-a-runtime-fix.md
msix-src/psf/psf-debug-a-runtime-fix.md
msix-src/psf/psf-find-a-runtime-fix.md
msix-src/psf/psf-identify-issues.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. |
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 4b5b11f6-6bf8-4401-90b8-68f710728c8e
Contributor
|
Learn Build status updates of commit 5904e0b: 💡 Validation status: suggestions
msix-src/psf/psf-apply-a-runtime-fix.md
msix-src/psf/psf-debug-a-runtime-fix.md
msix-src/psf/psf-find-a-runtime-fix.md
msix-src/psf/psf-identify-issues.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. |
Contributor
There was a problem hiding this comment.
Pull request overview
This PR restructures the Package Support Framework (PSF) documentation into a step-by-step workflow, turning the former “Get started” content into a hub and splitting detailed guidance into focused step articles. It also refreshes the PSF overview to include release history and clearer navigation across the workflow.
Changes:
- Adds a new “Step-by-step workflow” doc set (Steps 1–4) and wires it into the PSF TOC navigation.
- Converts the existing get-started article into a workflow hub that routes readers to the new steps and common-failure walkthroughs.
- Updates PSF overview content (including release history) and retargets related cross-links (e.g., config.json references).
Reviewed changes
Copilot reviewed 9 out of 9 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| msix-src/toc.yml | Adds a “Step-by-step workflow” node and links to the new step articles. |
| msix-src/psf/run-scripts-with-package-support-framework.md | Updates wrapper guidance and retargets config.json link to the new Step 3 article. |
| msix-src/psf/psf-identify-issues.md | New Step 1 article covering ProcMon/Trace Fixup-based diagnosis. |
| msix-src/psf/psf-find-a-runtime-fix.md | New Step 2 article mapping common failures to PSF fixes and resources. |
| msix-src/psf/psf-apply-a-runtime-fix.md | New Step 3 article describing packaging, config.json authoring, and validation. |
| msix-src/psf/psf-debug-a-runtime-fix.md | New Step 4 article describing debugging/extending fixes with VS/WinDbg. |
| msix-src/psf/package-support-framework.md | Replaces the monolithic get-started content with a workflow hub and “common failures” links. |
| msix-src/psf/package-support-framework-vs.md | Updates workingDirectory documentation to match the corrected behavior. |
| msix-src/psf/package-support-framework-overview.md | Rewrites overview; adds releases section, components table, workflow links, and expanded limitations/telemetry notes. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Comment on lines
37
to
38
| 🚩 Make sure to also include the __StartingScriptWrapper.ps1__ file in your package, in the same folder as the PSF launcher executable, which is normally the package root. The PSF launcher runs this wrapper for every start and end script: it looks for the wrapper next to itself first, and, in release 1.0.220926.1 and later, then searches the rest of the package for it. You can copy this file from the [PSF NuGet package](https://www.nuget.org/packages/Microsoft.PackageSupportFramework/) or from the [Package Support Framework repository](https://github.com/microsoft/MSIX-PackageSupportFramework/blob/main/PsfLauncher/StartingScriptWrapper.ps1). | ||
|
|
Collaborator
Author
There was a problem hiding this comment.
The current revision already replaces the flag-emoji callout with a standard > [!IMPORTANT] block and splits the guidance into shorter sentences, so this is addressed.
| ## Enable scripts | ||
|
|
||
| To specify what scripts will run for each packaged application executable, you need to modify the [config.json file](package-support-framework.md#create-a-configuration-file). To tell PSF to run a script before the execution of the packaged application, add a configuration item called `startScript`. To tell PSF to run a script after the packaged application finishes add a configuration item called `endScript`. | ||
| To specify what scripts will run for each packaged application executable, you need to modify the [config.json file](psf-apply-a-runtime-fix.md#create-a-configuration-file). To tell PSF to run a script before the execution of the packaged application, add a configuration item called `startScript`. To tell PSF to run a script after the packaged application finishes add a configuration item called `endScript`. |
Collaborator
Author
There was a problem hiding this comment.
Addressed in the current revision: the sentence now reads "...after the packaged application finishes, add a configuration item called endScript" with the comma after "finishes".
Use an accessible IMPORTANT callout and correct the script configuration sentence. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Contributor
|
Learn Build status updates of commit 6604d73: 💡 Validation status: suggestions
msix-src/psf/psf-apply-a-runtime-fix.md
msix-src/psf/psf-debug-a-runtime-fix.md
msix-src/psf/psf-find-a-runtime-fix.md
msix-src/psf/psf-identify-issues.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. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Restructures the Package Support Framework (PSF) documentation per Azure DevOps bug 26009108.
The bug asked to revisit the PSF doc structure so the overview includes the releases and links to step-by-step guidance, with the individual steps broken out into multiple docs (modeled on the ConfigMgr Apps docs).
What changed
toc.ymlwith a Step-by-step workflow node and retargeted cross-links.Technical review
Content was reviewed with an SME docs agent and verified against PSF source (
PsfLauncher/main.cpp, PsfRuntime readme, release history). Notably corrected the documentedworkingDirectorydefault, which was previously wrong: the launcher resolves a relative path against the package root and uses the package root when the value is omitted — not System32.AB#26009108