Skip to content

[docs] Document mixed-quality staging package discovery in aspire add #1505

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
aspire-repo-bot wants to merge 1 commit into
base: release/13.5
Choose a base branch
from
+10 −0
Open

[docs] Document mixed-quality staging package discovery in aspire add #1505

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions src/frontend/src/content/docs/reference/cli/commands/aspire-add.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,10 @@ The `aspire add` command searches for an integration package and adds it to the

<Include relativePath="reference/cli/includes/project-search-logic-description.md" />

:::note[Integration discovery on prerelease CLI builds]
When you're running a `staging` or `dev` quality CLI (see [`-Quality|--quality`](/reference/cli/install-script/#options)), `aspire add` discovers both stable and prerelease integration packages, because some integrations — such as `Aspire.Hosting.Azure.Kubernetes` — intentionally ship as prerelease even during a stable-shaped staging build. A `release` quality CLI continues to search stable packages only, but can still add a specific prerelease integration version with the `-v, --version` option.

@IEvangelist David Pine (IEvangelist) Aug 17, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Contradicted (behavior) — release/13.5 @ 45f7776. This note says a release quality CLI "continues to search stable packages only," but on release/13.5 the aspire add discovery path does not gate on CLI quality. IntegrationPackageSearchService.GetSearchChannelsAsync always includes the implicit channel, and PackageChannel.CreateImplicitChannel(...) is hard-coded to PackageChannelQuality.Both (src/Aspire.Cli/Packaging/PackageChannel.cs:740-748). Its own comment: the implicit Quality.Both channel "must always participate so prerelease packages are reachable even when the explicit pin is Stable-quality" (IntegrationPackageSearchService.cs:97-100). A Both channel issues both prerelease:false and prerelease:true queries (PackageChannel.cs:321-328), so a release CLI still discovers prerelease packages from the ambient feed — "stable packages only" is inaccurate on this branch.

Also: the source PR this documents (microsoft/aspire#19426, milestone 13.6) is not present on release/13.5, which this PR targets. The staging/dev-vs-release split may hold on 13.6 but not on 13.5. Consider re-scoping to 13.5 behavior (prerelease integrations are discoverable via the always-present implicit Both channel; a release CLI typically selects the stable version by default) or retargeting once a 13.6 branch exists.

@IEvangelist David Pine (IEvangelist) Aug 17, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Contradicted (CLI surface) — release/13.5 @ 45f7776. --version is correct, but the -v short form is not. aspire add's version option is registered as new("--version") with no -v alias (src/Aspire.Cli/Commands/AddCommand.cs:42 and :69; contrast --source, -s on the next line). -v is the root CLI's print-version flag (RootCommand.cs:271 versionOption.Aliases.Add("-v"); CommonOptionNames.cs:12 VersionShort = "-v"), so aspire add <name> -v <version> would not pin a package version. Suggest writing just --version. (Heads-up: the page's existing Options list also uses -v, --version for this option — out of scope here, but worth reconciling.)

:::

## Arguments

The following arguments are available:
Expand Down Expand Up @@ -81,3 +85,9 @@ The following options are available:
```bash title="Aspire CLI"
aspire add redis --apphost './apphost.mts'
```

- Add the **azure-kubernetes** integration from a stable-shaped `staging` quality CLI, where the integration remains prerelease even though most other packages are stable:

```bash title="Aspire CLI"
aspire add azure-kubernetes
```
Loading