microsoft / microsoft/aspire

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

Open
#17,513 1 comment 0 reactions 0 assignees View on GitHub
area-app-model area-cli triage:bot-seen
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.