Skip to content

docs: add prerelease (staging) testing walkthrough to upgrade guide - #2182

Merged
David Pine (IEvangelist) merged 2 commits into
release/17.0from
docs-staging-walkthrough
Nov 17, 2026
Merged

David Pine (IEvangelist) merged 2 commits into
release/17.0from
docs-staging-walkthrough

Conversation

@maddymontaquila

Copy link
Copy Markdown
Contributor

Summary

Adds a Try a prerelease build section to the upgrade guide. It walks through testing an app against a staging build from start to finish. Each piece was already documented on a different page, so the section links back to those references:

  1. Update the CLI with aspire update --self --channel staging; in CI, use install-script --quality staging.
  2. Run aspire update --channel staging --migrate. The section explains what this writes: the channel entry in aspire.config.json, the NuGet.config staging feed and Aspire* source mapping, and the repo-local .nugetpackages folder to add to .gitignore. It also notes that --migrate doesn't apply approval-gated changes such as ASPIRE012.
  3. Point aspire docs at the prerelease docs (aka.ms/aspire/vnext) by setting both docs.llmsTxtUrl and docs.api.sitemapUrl.
  4. Verify the switch.
  5. Check what the updater skips: inactive central package pins, other AppHosts, and pinned CI or dev container CLI versions.
  6. Switch back to stable, including the stale NuGet.config entries that aspire update can leave behind.

Each step reflects what happened when maddymontaquila/aspirifridays was upgraded from 13.5.3 to 17.0 staging.

The section uses a <prerelease-host> placeholder because the aka.ms/aspire/vnext link doesn't pass paths through; for example, /llms-full.txt redirects to Bing.

Fixes #2181. Related: #2133, #2177, #1880, #2180, and microsoft/aspire#22335.

Third-party links and affiliations

None

Validation

  • Checked each statement against an actual staging upgrade:
    • aspire.config.json contained "channel": "staging".
    • NuGet.config had the darc feed, the Aspire* mapping, and globalPackagesFolder=.nugetpackages.
    • Both docs keys were exercised against vnext.
  • Content-only change to an existing page. It adds no new routes and links only to pages that already exist on release/17.0. CI covers the build and link checks.

Fixes #2181

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

The upgrade guide still gives misleading staging-update and NuGet configuration guidance across installation types and AppHost languages, and its diagnostics link lacks the highlighted warning’s migration instructions.

4 open issues
What changed in this PR

Adds a prerelease-testing walkthrough to the existing Aspire upgrade guide, bringing previously scattered staging guidance into one place.

Changes:

  • Covers switching the CLI and app to staging and checking updater changes.
  • Explains prerelease documentation configuration and verification.
  • Lists settings to check manually and steps for returning to stable.
File Description
src/​frontend/​src/​content/​docs/​whats-new/​upgrade-aspire.mdx Adds the six-step prerelease testing walkthrough.

Review effort: Balanced

@aspire-repo-bot

Copy link
Copy Markdown
Contributor

Frontend HTML artifact ready

The latest frontend build uploaded the frontend-dist artifact for PR #2182. Use the VS Code button below to open this PR with GitHub Artifacts Explorer and browse the built HTML locally.

VS Code: Open PR #2182 artifacts

This comment updates automatically when a new frontend build artifact is uploaded.

…guage

Address review feedback: npm/.NET tool CLIs don't switch channels via --self, C# AppHosts follow NuGet policy without --channel, NuGet side effects are C#-only and conditional, and link ASPIRE012 help directly.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@IEvangelist
David Pine (IEvangelist) merged commit 3755a97 into release/17.0 Nov 17, 2026
17 checks passed
@IEvangelist
David Pine (IEvangelist) deleted the docs-staging-walkthrough branch November 17, 2026 02:12
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants