Backchannel version is incremented unnecessarily — should only bump once per release milestone

[JamesNK]

Problem

The auxiliary backchannel version (AuxiliaryBackchannelCapabilities in src/Aspire.Hosting/Backchannel/BackchannelDataTypes.cs) is being incremented by multiple PRs within the same release milestone, when only one new version is needed per release.

For example, in the current milestone:

• V3 (aux.v3) was added on May 13 for batched console log streaming and AppHost startup readiness wait
• V4 (aux.v4) is proposed in Fix remaining issue 17244 items #17507 for JSON-valued resource properties

Both features ship in the same release. From a compatibility standpoint, a single new version (V3) with all the new capabilities would be sufficient. There's no deployed release between these changes that would require distinguishing V3 from V4.

Each unnecessary version increment adds:

• More capability constants to maintain
• More SupportsVN properties on interfaces and implementations
• More conditional branching in both CLI and hosting code
• More test surface area

Proposed solutions

Some options (not mutually exclusive):

1. Add release-version comments to capability constants — annotate each version with which Aspire release it ships in, making it obvious whether a new version is needed:

   /// <summary>
   /// Version 1 capabilities (Aspire 9.1): GetAppHostInformationAsync, ...
   /// </summary>
   public const string V1 = "aux.v1";
   
   /// <summary>
   /// Version 2 capabilities (Aspire 9.2): Request objects, new methods.
   /// </summary>
   public const string V2 = "aux.v2";
   
   /// <summary>
   /// Version 3 capabilities (Aspire 9.3): Batched console log streaming, AppHost startup readiness wait,
   /// JSON-valued resource properties via ClientCapabilities opt-in.
   /// </summary>
   public const string V3 = "aux.v3";

2. Add agent/copilot instructions — add guidance in .github/instructions/hosting-core.instructions.md (or a new backchannel-specific instructions file) telling AI agents and contributors:

   Do not add a new AuxiliaryBackchannelCapabilities version if one has already been added in the current milestone. Instead, add your new capability to the existing newest version. Only increment the version when the previous version has shipped in a release.

3. Add a code comment block directly above the capability constants:

   // IMPORTANT: Only add a new version constant when the previous version has shipped
   // in a released version of Aspire. All new capabilities within a single release
   // milestone should be grouped under the same version number.

4. Document the versioning policy in a docs/backchannel-versioning.md or in the file header, explaining the rule and the reasoning (backward compatibility only matters between released versions, not between PRs in the same milestone).

Context

• AuxiliaryBackchannelCapabilities is defined in src/Aspire.Hosting/Backchannel/BackchannelDataTypes.cs
• The CLI advertises capabilities in src/Aspire.Cli/Backchannel/AppHostAuxiliaryBackchannel.cs
• Related PR: Fix remaining issue 17244 items #17507 (adds V4 unnecessarily when V3 already covers this milestone)

[joperezr]

🤖 Aspire triage pass — 2026-05-26 23:17 UTC

Area: area-app-model, area-cli
Kind: feature-request (process / code-quality)
Repro: yes-minimal — concrete example cited in issue body (V3 added May 13, V4 proposed in #17507 within the same milestone)
Affected version(s): in-flight main (the unnecessary V4 bump lands in the current milestone via #17507)
Severity: S4 — no user-facing behavior change; maintainability / churn reduction in AuxiliaryBackchannelCapabilities and related SupportsVN plumbing.

Urgency: 🟡 vNext — recommend milestone 13.4
Reason: The relevant PR (#17507) is targeted at the current milestone, so collapsing V4→V3 (or adding the guidance to prevent it) is most valuable before 13.4 ships. Not a servicing candidate — no in-market regression.

Suggested owner(s): @adamint (score 3), backup @mitchdenny (score 2)
Evidence:

• @adamint authored Fix remaining issue 17244 items #17507, the PR that introduced the unnecessary V4 bump and is referenced as the immediate trigger for this issue.
• @mitchdenny merged test(cli): quarantine ResourceCommand_FailsWhenInteractionServiceIsRequired (#17485) #17486 in area-cli (last 7d) and owns recent deployment/CLI work; reasonable backup for the CLI-side capability advertisement in AppHostAuxiliaryBackchannel.cs.
• Top contributor in area-app-model and area-cli over the last 90d is @JamesNK (14 and 24 merges respectively), but @JamesNK is excluded as the issue author per triage rules.
• No .github/CODEOWNERS is present to add path-based signal.

Confidence: medium
Needs human?: no — but the chosen mitigation (comment vs. instructions file vs. docs page, and whether to roll V4 back into V3 in #17507) is a design call for the area owner.

Dry-run mode — no labels or milestone applied. Reply /triage apply to promote, or edit and reapply.