Backchannel version is incremented unnecessarily — should only bump once per release milestone
- Dominant language
- C#
- Stars
- 6.3k
- Forks
- 991
- Avg merge
- 2d 15h
- Merged PRs (30d)
- 196
Description
## 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 #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:
```csharp
///
/// Version 1 capabilities (Aspire 9.1): GetAppHostInformationAsync, ...
///
public const string V1 = "aux.v1";
///
/// Version 2 capabilities (Aspire 9.2): Request objects, new methods.
///
public const string V2 = "aux.v2";
///
/// Version 3 capabilities (Aspire 9.3): Batched console log streaming, AppHost startup readiness wait,
/// JSON-valued resource properties via ClientCapabilities opt-in.
///
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:
```csharp
// 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: #17507 (adds V4 unnecessarily when V3 already covers this milestone)
Contributor guide
Assessment
This issue has not been assessed yet.