From 0e29d85fcfdf940dd7d24359c533fe42d66cd7ce Mon Sep 17 00:00:00 2001 From: Marc Paine Date: Thu, 30 Jul 2026 14:52:35 -0700 Subject: [PATCH 01/13] Proposal for having a single feature band going forward with a central configuration that all tools rely on to get new feature work. --- proposed/single-sdk-feature-band.md | 237 ++++++++++++++++++++++++++++ 1 file changed, 237 insertions(+) create mode 100644 proposed/single-sdk-feature-band.md diff --git a/proposed/single-sdk-feature-band.md b/proposed/single-sdk-feature-band.md new file mode 100644 index 000000000..1ef93a638 --- /dev/null +++ b/proposed/single-sdk-feature-band.md @@ -0,0 +1,237 @@ +# Single SDK Feature Band with Global Feature Channels + +**Owner** [marcpopMSFT](https://github.com/marcpopMSFT) + +Today, SDK feature bands, SDK tools, and Visual Studio are coupled in ways that is complex to manage and confusing for users. The challenge with changing this is users can receive new features or behavior changes without intentionally opting in. This is especially problematic for managed environments and source build partners that prioritize stability. We propose a single SDK feature band strategy, combined with a global feature channel setting that all SDK-loaded components honor. This setting has three states: baseline, stable, and preview. New behavior is always disabled in baseline, and initially enabled only in preview. + +## Scenarios and User Experience + +### Scenario 1: Source build partner requires maximum stability + +A source build partner consumes servicing builds and needs strict behavioral predictability. They configure the global channel to baseline. New features and behavior changes remain off by default across SDK, MSBuild, Roslyn, NuGet, MSTest, and other participating components. Today, these partners stay on the N.0.1xx feature band in order to prioritize stability. + +Outcome: + +- Servicing updates can include security and reliability fixes. +- Existing behavior remains stable unless explicitly opted in. +- Partner validation costs and risk are reduced. +- Customers using source build SDKs can use the same SDK on multiple platforms with the same behavior with a simple environment variable + +### Scenario 2: Visual Studio stable users get curated, stable behavior + +A developer on Visual Studio stable channel receives SDK updates from the internal branch insertion path. They get behavior considered production-ready for the stable channel, while preview-only changes remain off. They get the latest runtime with all security fixes and any tooling security fixes as well. + +Outcome: + +- Stable channel receives deliberate feature lighting. +- Behavior aligns with VS stable expectations. +- Mid-cycle surprises are reduced. + +### Scenario 3: Canary/Insider users validate upcoming behavior + +A developer in VS canary receives the public 11.0.1xx SDK build with preview branding. Their global channel is preview, so new behavior can be enabled early for validation. + +Outcome: + +- Early adopter feedback happens before stable rollout. +- Preview-only changes do not leak into stable/baseline channels by default. +- Reduces the need to worry about the Insider behavior as it'll be the same as Canary + +## Requirements + +### Goals + +- Define a single global configuration that is consumed across all .NET SDK-loaded components. +- Provide three explicit feature channels: baseline, stable, preview. +- Ensure new features or behavior changes default to off for baseline. +- Ensure new features or behavior changes light up first in preview. +- Enable controlled advancement from preview to stable based on explicit promotion. +- Preserve servicing safety: no accidental behavior lights-up in servicing trains. +- Align Visual Studio channel insertion with intended behavior channel semantics. +- Keep .NET optional workload acquisition aligned to latest stable builds across VS channels. +- Reduce branch management costs down to a single feature band sourced from two branches + +### Non-Goals + +- Redesigning component-specific feature-flag systems end-to-end. +- Guaranteeing identical behavior for non-participating tools outside the SDK composition. +- Replacing existing TFM-based compatibility controls. +- Defining every individual feature's rollout criteria in this proposal. +- Changing any rollout or versioning for optional workloads. +- Change how the feature rollout and experience of components loaded into Visual Studio are managed + +## Stakeholders and Reviewers + +- SDK: feature-band ownership and global configuration contract +- MSBuild: engine behavior gating and branch/codeflow model +- Roslyn: compiler/analyzer defaults and compatibility modes +- NuGet: restore/package behavior gating where applicable +- MSTest: test SDK/runtime behavior gating +- Source build partners: default channel semantics and validation guidance +- Visual Studio: channel insertion, branding, and defaults + +## Design + +### Global feature channel + +Introduce one SDK-wide configuration value (`SdkFeatureChannel`) with exactly three allowed values: + +- baseline +- stable +- preview + +All participating components must query this value through a shared contract and use it to gate behavior changes. + +Initial policy for any new feature or behavior change: + +- baseline: off +- stable: off (unless explicitly promoted) +- preview: on (unless explicitly held back) + +Promotion policy: + +- A feature starts as preview-on, stable-off, baseline-off. +- Promotion to stable requires explicit approval and release notes in a planned update. +- Baseline remains off by default, with opt-in available for customers that explicitly choose it. +- Minimum preview soak time before promotion is two months. + +### Configuration sources and precedence + +The final value is provided through environment propagation so all child tools inherit the same channel. The SDK host sets the effective environment variable `DOTNET_SDK_FEATURE_CHANNEL` early in startup (first step in `Program.cs`) before invoking any tool components. + +Default channel behavior is configured at SDK build time: + +- Source-build distributions default to baseline. +- Microsoft SDK distributions default to stable. + +Customers can override with the environment variable if they choose a different risk posture. + +Precedence (highest to lowest): + +1. Command-line explicit override (if introduced) +2. Environment variable explicit value +3. Host-computed default written by SDK startup +4. SDK build-time default + +Global.json integration may be added later, but is not required for the initial design. + +Open questions: + +- How do we ensure this behavior propogates from the SDK to the component tool? +- What should the behavior be inside of .NET components running inside of Visual Studio and how do we coordinate that. + +### Cross-component contract + +Each participating component defines: + +- Behavior identifier (feature or breaking behavior ID) +- First enabled channel +- Promotion history (preview to stable) +- Override mechanism (if any) + +To improve transparency and auditing, components should also publish a machine-readable manifest of gated behaviors and channel thresholds. + +The SDK provides the channel context; each component owns implementation details while following a common policy. + +### Visual Studio channel strategy + +Proposed VS integration model: + +- Public branch 11.0.1xx: + - Preview branding + - Insert into VS canary + - Global channel default: preview + +- Internal branch build: + - Stable branding + - Includes MSRC fixes and latest runtimes + - Insert into VS stable and oobstable + - Global channel default: stable + - Preview behavior remains default-disabled; customer opt-in is allowed + +- VS insiders: + - Do not insert SDK directly + - Consume preview flow from canary + +### Optional workloads strategy + +For optional .NET workloads: + +- Always build workload artifacts from internal SDK version. +- Insert workload artifacts into all VS channels. + +No additional compatibility contract is required for workloads in this proposal. + +### MSBuild and similar component branch flow + +For teams that need behavior alignment with VS stability (example: MSBuild engine): + +- Stable branch codeflow from internal branch for stable alignment. +- Public flow for latest/preview innovation. +- Explicit merge and promotion policy to avoid accidental stable-channel behavior changes. + +This pattern is recommended for all tooling teams that need stable-channel alignment. + +For repositories with public-to-internal mirroring, branch topology must preserve stable and preview intent. A candidate model is: + +- Public default branch mirrors into a public preview branch (source-preferred). Example: flow from 11.0.1xx to 11.0.1xx-featurepreviews. +- Promotion from internal preview branch to internal stable branch is controlled (target-protected, with explicit acceptance gates). +- Stable insertions are produced from the internal stable branch, while canary insertions are produced from preview-aligned flow. + +This model needs validation with engineering systems owners before adoption. + +### Servicing safety rules + +In servicing trains: + +- No new behavior should silently turn on for stable or baseline. +- Security and reliability fixes may ship, but behavior-changing defaults require explicit promotion in a planned update. +- Rollback options are: flip the feature off via hotfix when critical, or fix forward in the next servicing release. + +## Q and A + +### Why a three-state model instead of a binary preview toggle? + +A binary model cannot represent baseline needs independently from mainstream stable users. Three states separate strict stability from normal stable adoption and preview validation. + +## Risks and Unknowns + +- Cross-component adoption lag: not all components may adopt `SdkFeatureChannel` and `DOTNET_SDK_FEATURE_CHANNEL` at the same pace, leading to inconsistent behavior. +- Environment propagation correctness: if the variable is not set early enough in SDK startup, child tools may observe incorrect defaults. +- Host/tooling interaction complexity: IDEs, build servers, and custom hosts may inject conflicting environment values. +- Configuration discoverability: users may not understand why behavior differs by channel without strong diagnostics and documentation. +- Manifest quality risk: machine-readable behavior manifests may drift from implementation if not validated in CI. +- Enforcement consistency risk across repos: without shared policy checks, teams may implement channel gating differently or incompletely. +- Promotion calibration risk: a two-month preview window may be too short or too long depending on feature blast radius. +- Servicing pressure: urgent fixes may tempt channel policy exceptions that undermine trust in stable/baseline promises. +- Branch/codeflow divergence: internal/public flow patterns can create merge debt and delayed fixes if governance is weak. +- Mirror topology risk for split public/internal versions: current one-way public to internal mirroring can accidentally blur stable versus preview intent. +- Cherry-pick debt risk: if internal stable and preview diverge, security and reliability fixes may require manual multi-branch propagation. +- Validation matrix risk: every participating repo may need baseline/stable/preview validation, increasing CI cost and latency. +- Diagnostics burden: support teams may need additional tooling to quickly determine the effective channel in customer environments. + +### Enforcement approach + +Open questions: + +- Do we need an enfrocement bot enabled in every participating repo? +- Do we need the ability to dump all new features into a machine and human readable format for review and comparison against intent/docs/PRs? + +Unknowns to validate during review: + +- Whether `baseline` is intuitive enough for external customers and partners. +- Whether `DOTNET_SDK_FEATURE_CHANNEL` should be the only v1 control surface or paired with a CLI switch immediately. +- Whether all in-scope components can enforce gating with acceptable performance overhead. +- Whether existing per-tool feature flags can be harmonized without migration churn. +- Which minimal cross-repo policy checks are required for v1 to avoid silent non-compliance. +- Whether current public-to-internal mirror infrastructure can support a preview-branch intermediary with controlled internal stable promotion. +- Whether stable/canary insertion branches should be structurally separated in all participating repos. + +### Does this replace existing feature flags? + +No. Component-level flags can remain. This proposal adds a single, global compatibility channel that defines default behavior posture. + +### Open questions to resolve + +1. Whether `DOTNET_SDK_FEATURE_CHANNEL` should be the only v1 control surface or whether a CLI switch should also ship in v1. +2. Minimum schema for the machine-readable behavior manifest. From 1692defac7b24000d2f664de4f83043532d5975c Mon Sep 17 00:00:00 2001 From: Marc Paine Date: Tue, 4 Aug 2026 17:06:31 -0700 Subject: [PATCH 02/13] Update based on PR feedback --- proposed/single-sdk-feature-band.md | 22 ++++++++++++++++++---- 1 file changed, 18 insertions(+), 4 deletions(-) diff --git a/proposed/single-sdk-feature-band.md b/proposed/single-sdk-feature-band.md index 1ef93a638..56e57e433 100644 --- a/proposed/single-sdk-feature-band.md +++ b/proposed/single-sdk-feature-band.md @@ -2,7 +2,7 @@ **Owner** [marcpopMSFT](https://github.com/marcpopMSFT) -Today, SDK feature bands, SDK tools, and Visual Studio are coupled in ways that is complex to manage and confusing for users. The challenge with changing this is users can receive new features or behavior changes without intentionally opting in. This is especially problematic for managed environments and source build partners that prioritize stability. We propose a single SDK feature band strategy, combined with a global feature channel setting that all SDK-loaded components honor. This setting has three states: baseline, stable, and preview. New behavior is always disabled in baseline, and initially enabled only in preview. +Today, SDK feature bands, SDK tools, and Visual Studio are coupled in ways that is complex to manage and confusing for users. The challenge with changing this is users can receive new features or behavior changes without intentionally opting in. This is especially problematic for managed environments and source build partners that prioritize stability. We propose a single SDK feature band strategy, combined with a global feature channel setting that all SDK-loaded components honor. This setting has three states: baseline, stable, and preview. New behavior or new features should never show up in baseline. New features should initially be enabled only in preview. Stable is for features that have gone through some preview validation and make include some behavior changes or new warnings. ## Scenarios and User Experience @@ -27,7 +27,7 @@ Outcome: - Behavior aligns with VS stable expectations. - Mid-cycle surprises are reduced. -### Scenario 3: Canary/Insider users validate upcoming behavior +### Scenario 3: Visual Studio Canary/Insider users validate upcoming behavior A developer in VS canary receives the public 11.0.1xx SDK build with preview branding. Their global channel is preview, so new behavior can be enabled early for validation. @@ -37,6 +37,18 @@ Outcome: - Preview-only changes do not leak into stable/baseline channels by default. - Reduces the need to worry about the Insider behavior as it'll be the same as Canary +### Scenario 4: VS Code user gets flexible feature control + +A developer using VS Code and the .NET SDK can choose their preferred feature channel to match their development needs. They default to stable for a balance of new features and stability. If they want maximum stability, they can set the environment variable to baseline. If they want to try cutting-edge features early, they can opt into preview. + +Outcome: + +- Stable channel is a sensible default for most developers. +- Power users have direct control via environment variable configuration. +- Independent of IDE choice; behavior is consistent across any editor using the SDK. +- Easy to experiment with new features without waiting for broader SDK releases. +- With each major release, VSCode will update the SDK installed to a new band resulting in a new baseline. + ## Requirements ### Goals @@ -50,6 +62,7 @@ Outcome: - Align Visual Studio channel insertion with intended behavior channel semantics. - Keep .NET optional workload acquisition aligned to latest stable builds across VS channels. - Reduce branch management costs down to a single feature band sourced from two branches +- Stable from major version N (eg .NET 11) will automatically be included in baseline of N+1 (eg .NET 12) ### Non-Goals @@ -113,7 +126,7 @@ Precedence (highest to lowest): 3. Host-computed default written by SDK startup 4. SDK build-time default -Global.json integration may be added later, but is not required for the initial design. +global.json integration may be added later, but is not required for the initial design. Open questions: @@ -145,7 +158,7 @@ Proposed VS integration model: - Internal branch build: - Stable branding - Includes MSRC fixes and latest runtimes - - Insert into VS stable and oobstable + - Insert into VS stable and last servicing version. VS typically releases a new GA and a final release of the last minor version on the same day and we would update both. - Global channel default: stable - Preview behavior remains default-disabled; customer opt-in is allowed @@ -235,3 +248,4 @@ No. Component-level flags can remain. This proposal adds a single, global compat 1. Whether `DOTNET_SDK_FEATURE_CHANNEL` should be the only v1 control surface or whether a CLI switch should also ship in v1. 2. Minimum schema for the machine-readable behavior manifest. +3. Is there a change to the versioning schema we could do for the SDK? We could change to match runtime versioning but we sometimes have SDK hotfixes so it might be confusing to release an 11.0.108 that has 11.0.7 runtime in it. \ No newline at end of file From bda793d3c7237a3da91d2cda1c00a04c6cdf2087 Mon Sep 17 00:00:00 2001 From: Marc Paine Date: Wed, 5 Aug 2026 15:26:07 -0700 Subject: [PATCH 03/13] Added some clarification from PR feedback --- proposed/single-sdk-feature-band.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/proposed/single-sdk-feature-band.md b/proposed/single-sdk-feature-band.md index 56e57e433..0b3f35d6c 100644 --- a/proposed/single-sdk-feature-band.md +++ b/proposed/single-sdk-feature-band.md @@ -6,9 +6,9 @@ Today, SDK feature bands, SDK tools, and Visual Studio are coupled in ways that ## Scenarios and User Experience -### Scenario 1: Source build partner requires maximum stability +### Scenario 1: Enterprise Source build partner requires maximum stability -A source build partner consumes servicing builds and needs strict behavioral predictability. They configure the global channel to baseline. New features and behavior changes remain off by default across SDK, MSBuild, Roslyn, NuGet, MSTest, and other participating components. Today, these partners stay on the N.0.1xx feature band in order to prioritize stability. +Some source build partners consume servicing builds and needs strict behavioral predictability. They configure the global channel to baseline. New features and behavior changes remain off by default across SDK, MSBuild, Roslyn, NuGet, MSTest, and other participating components. Today, these partners stay on the N.0.1xx feature band in order to prioritize stability. Outcome: @@ -16,6 +16,7 @@ Outcome: - Existing behavior remains stable unless explicitly opted in. - Partner validation costs and risk are reduced. - Customers using source build SDKs can use the same SDK on multiple platforms with the same behavior with a simple environment variable +- Source build partners can choose additional features through the stable channel and source build customers can even choose to try out previews which has been a long term ask. ### Scenario 2: Visual Studio stable users get curated, stable behavior @@ -227,8 +228,11 @@ A binary model cannot represent baseline needs independently from mainstream sta Open questions: -- Do we need an enfrocement bot enabled in every participating repo? +- How do we enforce this in every contributing repo? + - PR review guidance as a minimum + - What other enforcement can we create? - Do we need the ability to dump all new features into a machine and human readable format for review and comparison against intent/docs/PRs? + - It'd be great to be able to tag issues/PRs on which release they are in as well. Unknowns to validate during review: From 67b23ede56c2d3093b9eb417e2a41589329d9ef5 Mon Sep 17 00:00:00 2001 From: Marc Paine Date: Wed, 5 Aug 2026 15:29:58 -0700 Subject: [PATCH 04/13] add concern about preview versioning --- proposed/single-sdk-feature-band.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/proposed/single-sdk-feature-band.md b/proposed/single-sdk-feature-band.md index 0b3f35d6c..1326ad4f1 100644 --- a/proposed/single-sdk-feature-band.md +++ b/proposed/single-sdk-feature-band.md @@ -194,6 +194,12 @@ For repositories with public-to-internal mirroring, branch topology must preserv This model needs validation with engineering systems owners before adoption. +Concerns: + +- We would have two versions of the .1xx band shipping on the same day. One would be stable branded and one would be preview branded. That would then create 6 different feature combinations depending on the channel setting as well. + - Example: 11.0.103 would ship in VS stable and 11.0.1xx-preview.27053.4 would release in VS canary on Feb patch tuesday. + - Note: 11.0.1xx-preview.27053.4 versioning wouldn't work with workloads as is as we expect a preview version. + ### Servicing safety rules In servicing trains: From 05fe1b50e2227685c33c845b10faa7c292ebf85d Mon Sep 17 00:00:00 2001 From: Marc Paine Date: Thu, 6 Aug 2026 11:58:30 -0700 Subject: [PATCH 05/13] Change the shipping model to only have a single version of the tools shipping in the SDK be stable versions. --- proposed/single-sdk-feature-band.md | 25 +++++++++++-------------- 1 file changed, 11 insertions(+), 14 deletions(-) diff --git a/proposed/single-sdk-feature-band.md b/proposed/single-sdk-feature-band.md index 1326ad4f1..d3b54b2a0 100644 --- a/proposed/single-sdk-feature-band.md +++ b/proposed/single-sdk-feature-band.md @@ -178,27 +178,24 @@ No additional compatibility contract is required for workloads in this proposal. ### MSBuild and similar component branch flow -For teams that need behavior alignment with VS stability (example: MSBuild engine): +We will not ship two SDK/tooling versions in parallel for the same feature band. -- Stable branch codeflow from internal branch for stable alignment. -- Public flow for latest/preview innovation. -- Explicit merge and promotion policy to avoid accidental stable-channel behavior changes. +Rationale: -This pattern is recommended for all tooling teams that need stable-channel alignment. +- Command-line usage of `dotnet` inside VS canary/insiders has not produced enough critical feedback to justify the operational complexity of dual-version shipping. -For repositories with public-to-internal mirroring, branch topology must preserve stable and preview intent. A candidate model is: +Updated branch and insertion policy for MSBuild and similar tooling teams: -- Public default branch mirrors into a public preview branch (source-preferred). Example: flow from 11.0.1xx to 11.0.1xx-featurepreviews. -- Promotion from internal preview branch to internal stable branch is controlled (target-protected, with explicit acceptance gates). -- Stable insertions are produced from the internal stable branch, while canary insertions are produced from preview-aligned flow. +- Preview tooling ships from `main`. +- Those preview bits flow into VS canary and the .NET vNext SDK. +- Released SDKs ship tooling only from stable tooling branches. +- No separate preview-branded/stable-branded split for the same released feature band. -This model needs validation with engineering systems owners before adoption. +This keeps preview validation where it is most useful (canary and vNext) while reducing branch/codeflow complexity and release risk for shipped SDKs. -Concerns: +Risk: -- We would have two versions of the .1xx band shipping on the same day. One would be stable branded and one would be preview branded. That would then create 6 different feature combinations depending on the channel setting as well. - - Example: 11.0.103 would ship in VS stable and 11.0.1xx-preview.27053.4 would release in VS canary on Feb patch tuesday. - - Note: 11.0.1xx-preview.27053.4 versioning wouldn't work with workloads as is as we expect a preview version. +This potentially limits the amount of feedback tooling teams would get on new features before promoting them to stable as they'd only be available in vNext or VS/msbuild.exe. ### Servicing safety rules From 212e3c8095d5685c89d8ba203eb7727159782495 Mon Sep 17 00:00:00 2001 From: Marc Paine Date: Mon, 10 Aug 2026 13:36:02 -0700 Subject: [PATCH 06/13] Add alternative proposal for having minor SDK releases --- proposed/single-sdk-feature-band.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/proposed/single-sdk-feature-band.md b/proposed/single-sdk-feature-band.md index d3b54b2a0..71153c971 100644 --- a/proposed/single-sdk-feature-band.md +++ b/proposed/single-sdk-feature-band.md @@ -50,6 +50,20 @@ Outcome: - Easy to experiment with new features without waiting for broader SDK releases. - With each major release, VSCode will update the SDK installed to a new band resulting in a new baseline. +## Alternatives + +### Monthly SDK minor releases + +Instead of using feature channels within a single SDK feature band, the SDK could adopt monthly minor releases. The .NET 11 GA SDK would be `11.0.0`, followed by `11.1.0`, `11.2.0`, and so on in subsequent months. Each monthly SDK would replace the previous monthly release and contain the latest available runtime, including applicable security and reliability fixes. I considered just having monthly feature bands as an alternative but the feeling was that having 11.0.100 and 11.0.1000 would lead to more confusion. + +Only the latest monthly minor and the original `11.0.x` release line would be serviced. The `11.0.x` line would receive security and reliability fixes but no new features, providing a stability-oriented option for source-build and enterprise partners. Existing `global.json` version selection and roll-forward behavior would allow customers to remain on `11.0.x`, select a particular monthly SDK, or move to newer monthly releases. + +Workload set versions would generally match the SDK version. For example, the workload set for `11.2.0` would use that version, while SDK hotfixes and mid-month workload updates would consume successive patch numbers such as `11.2.1` and `11.2.2`. A patch number could therefore represent either kind of update, avoiding the need for four-part workload set versions. + +This model would likely require three branches: the `11.0` stability branch, stable, and preview. DARC channels would flow monthly releases from preview to stable together with the required branding updates. + +The primary benefit of this approach is avoiding the governance and coordination risk of requiring every SDK-loaded component to implement feature channels correctly. Its primary drawbacks are that source-build customers remaining on `11.0.x` could not opt into new features through a feature-channel update, and the SDK would need to manage additional branching, flow, and branding complexity. This basically takes the feature band model and tries to find a reasonable way of collapsing it into monthly releases. + ## Requirements ### Goals From f352979f3c95adb17cb3996aa16cc4f54cb681e3 Mon Sep 17 00:00:00 2001 From: Marc Paine Date: Wed, 19 Aug 2026 15:28:33 -0700 Subject: [PATCH 07/13] Add additional context to the minor release alternative --- proposed/single-sdk-feature-band.md | 98 +++++++++++++++++++++++++++-- 1 file changed, 93 insertions(+), 5 deletions(-) diff --git a/proposed/single-sdk-feature-band.md b/proposed/single-sdk-feature-band.md index 71153c971..74c9e4b73 100644 --- a/proposed/single-sdk-feature-band.md +++ b/proposed/single-sdk-feature-band.md @@ -54,15 +54,103 @@ Outcome: ### Monthly SDK minor releases -Instead of using feature channels within a single SDK feature band, the SDK could adopt monthly minor releases. The .NET 11 GA SDK would be `11.0.0`, followed by `11.1.0`, `11.2.0`, and so on in subsequent months. Each monthly SDK would replace the previous monthly release and contain the latest available runtime, including applicable security and reliability fixes. I considered just having monthly feature bands as an alternative but the feeling was that having 11.0.100 and 11.0.1000 would lead to more confusion. +Instead of using feature channels within a single SDK feature band, the SDK could adopt monthly minor releases. For example, the .NET 12 GA SDK would be `12.0.0`, followed by `12.1.0`, `12.2.0`, and so on in subsequent months. Each monthly SDK would replace the previous monthly release as the actively supported feature release and contain the latest available runtime, including applicable security and reliability fixes. -Only the latest monthly minor and the original `11.0.x` release line would be serviced. The `11.0.x` line would receive security and reliability fixes but no new features, providing a stability-oriented option for source-build and enterprise partners. Existing `global.json` version selection and roll-forward behavior would allow customers to remain on `11.0.x`, select a particular monthly SDK, or move to newer monthly releases. +Monthly feature bands were also considered, but versions such as `12.0.100` followed by `12.0.200` or `12.0.1000` continue the feature-band concept and do not communicate the monthly release ordering as directly. -Workload set versions would generally match the SDK version. For example, the workload set for `11.2.0` would use that version, while SDK hotfixes and mid-month workload updates would consume successive patch numbers such as `11.2.1` and `11.2.2`. A patch number could therefore represent either kind of update, avoiding the need for four-part workload set versions. +#### Release and branch model -This model would likely require three branches: the `11.0` stability branch, stable, and preview. DARC channels would flow monthly releases from preview to stable together with the required branding updates. +Development would primarily occur in a long-lived preview branch. It could be as simple as a public release/12.x branch with all public codeflow to this branch. Once a month, the preview content intended for release would be promoted to a long-lived stable branch which couild just be internal/release/12.x which has internal codeflow of the runtime version. Each month we'd update the branding in each branch separately. -The primary benefit of this approach is avoiding the governance and coordination risk of requiring every SDK-loaded component to implement feature channels correctly. Its primary drawbacks are that source-build customers remaining on `11.0.x` could not opt into new features through a feature-channel update, and the SDK would need to manage additional branching, flow, and branding complexity. This basically takes the feature band model and tries to find a reasonable way of collapsing it into monthly releases. +The original `12.0.x` release line would remain available as the stability-oriented release for customers that want security and reliability fixes without new features (specifically, enterprise source build partners). This produces at least three logical release paths: + +- The original `12.0.x` stability line. +- The latest stable monthly minor release. +- The next monthly minor release in preview. + +Monthly promotion introduces a risk of drift between preview and stable. We could have codeflow from stable tooling to the stable branch but that would cause mirror conflicts or alternatively, we could require all stable tooling changes be made in the internal/release branch. Any security fixes would have to be ported on release day to the preview branch. + +#### Servicing and security fixes + +Only the latest monthly minor and the original `12.0.x` release line would be serviced. Superseded monthly minors would remain installable but would not receive further fixes. The `12.0.x` line would receive security and reliability fixes but no new features, providing a predictable option for enterprise source-build and other stability-focused customers. + +The servicing policy needs to distinguish among: + +- Runtime security and reliability updates included in an SDK release. +- SDK or tooling hotfixes that do not require a runtime release. +- Workload updates released between monthly SDK releases. +- Fixes required by Visual Studio or source-build consumers that remain on a different SDK release path. + +Security and reliability fixes need an explicit propagation path to the original stability line, the current stable monthly release, the next preview, Visual Studio's supported SDK builds, and any dedicated source-build branch. Stable tooling fixes would need to flow through the VMR or an equivalent internal release process rather than flowing only into the preview branch. + +The policy must also define what happens when a runtime security release is delayed, skipped, or released out of band. A runtime release should not necessarily require a new SDK minor, but supported SDK lines still need a way to acquire that runtime update. + +#### SDK and runtime version relationship + +SDK and runtime versions would intentionally be allowed to differ. For example, an SDK hotfix `12.2.1` might contain runtime `12.0.7`, and a new monthly SDK minor preview would contain the most recently available runtime patch rather than a runtime released on the same day. Release notes would need to make this relationship clear. + +The SDK version components would have the following meaning: + +- Major: the annual .NET release. +- Minor: a monthly SDK feature release. +- Patch: an SDK/tooling hotfix or a release used to carry an updated workload set between monthly feature releases. +- Prerelease label: builds of the next monthly minor before promotion to stable. + +Using the patch component for both SDK hotfixes and workload updates preserves a three-part version but means patch numbers identify release order rather than a particular type of change. Release tooling and documentation must not assume that every patch increment has the same cause. + +#### Visual Studio integration + +The preview SDK would continue to flow to Visual Studio Canary for validation. The stable monthly SDK would be available to supported Visual Studio channels according to their insertion and servicing policies. Visual Studio Insiders could continue to consume the preview flow through Canary rather than requiring a separate SDK build. + + +#### Source-build contract + +Enterprise source-build partners that require maximum stability could remain on `12.0.x` and receive security and reliability fixes without taking monthly feature releases. Other source-build consumers could move to newer monthly minors through their normal distribution update process. + +Unlike the feature-channel proposal, a customer remaining on `12.0.x` could not opt into selected newer SDK features without moving to a newer monthly SDK. This loses a benefit of the feature-channel model for customers that must acquire the SDK from a distribution feed but want newer features. On the other hand, release boundaries provide stronger isolation than relying on every component to gate all behavior correctly. This is particularly important for changes such as analyzer fixes that may introduce new warnings even when the change is otherwise considered a correctness fix. + +#### Workloads, installers, and SDK selection + +Existing workload and SDK infrastructure encodes feature-band identity in workload manifests, workload sets, package IDs, version validation, and selection logic. This model would need to define the monthly minor as the new compatibility boundary and update those systems accordingly. + +Workload set versions would generally match the SDK version. For example, the workload set for `12.2.0` would use that version, while SDK hotfixes and mid-month workload updates would consume successive patch numbers such as `12.2.1` and `12.2.2`. The release process must define ordering when both an SDK hotfix and a workload update are required in the same month and ensure that an SDK can resolve a compatible workload set after either kind of update. + +Existing `global.json` version selection and roll-forward behavior would allow customers to remain on `12.0.x`, select a particular monthly SDK, or move to newer monthly releases. The exact behavior of each roll-forward policy across minor releases needs to be specified, including whether existing feature-band-oriented policies retain their current names and how they map to monthly minors. + +Installer and acquisition behavior also needs an explicit contract: + +- Whether monthly minors install side by side or replace the previous monthly SDK. +- How MSI related-product and upgrade relationships are represented. +- How uninstalling a monthly SDK affects shared runtimes and workload content. +- How Microsoft Update targets standalone SDKs on the original stability line versus later monthly minors. +- How SDKs installed by Visual Studio are detected and serviced separately from standalone SDKs. + +#### Transition + +Adopting this model at the beginning of a major release is simpler than changing versioning after customers and tooling have already consumed feature-band versions. One transition option is to retain the existing feature-band model through .NET 11, including a final feature band if needed, and begin monthly minor releases with .NET 12. + +The transition plan would need to identify and update automation that parses SDK feature bands, including workload tooling, `global.json` handling, installers, Microsoft Update, release pipelines, support tooling, and documentation. Compatibility behavior is required for tools that encounter both the older feature-band scheme and the monthly-minor scheme. + +#### Benefits and drawbacks + +The primary benefits of this approach are: + +- Monthly versions communicate release order directly and align SDK tooling delivery with a monthly Visual Studio cadence. +- Features can reach stable customers monthly rather than waiting for a quarterly feature band. +- Release boundaries provide stronger isolation for stability-focused customers. +- The SDK does not depend on every loaded component implementing, naming, testing, documenting, and honoring a shared feature-channel setting correctly. +- Tooling teams can use normal version and branch boundaries instead of maintaining a growing set of indefinitely supported feature gates. + +The primary drawbacks are: + +- Source-build customers remaining on the original stability line cannot opt into selected newer features. +- Workload, installer, SDK selection, release, and servicing infrastructure require significant changes. +- Preview-to-stable promotion and fix propagation can create branch drift and merge debt. +- Visual Studio and source-build may still require separate servicing paths, limiting the expected branch reduction. +- SDK and runtime versions may differ in ways that require clear diagnostics and documentation. +- Monthly minors increase the number of SDK versions customers and support teams encounter. + +This alternative should be selected if the operational cost of monthly promotion, servicing, installer, workload, and version-selection changes is lower than the governance and compatibility risk of requiring every SDK-loaded component to implement feature channels correctly. Before selecting it, the design needs validated plans for security-fix propagation, Visual Studio servicing, source-build support, workload versioning, installer upgrade behavior, and the transition from feature bands. ## Requirements From c728222b1e65244ff303f158505adb76e3fa74e8 Mon Sep 17 00:00:00 2001 From: Marc Paine Date: Thu, 20 Aug 2026 16:33:00 -0700 Subject: [PATCH 08/13] Update from review today to make the minor version model the primary proposal --- proposed/single-sdk-feature-band.md | 430 +++++++++++----------------- 1 file changed, 171 insertions(+), 259 deletions(-) diff --git a/proposed/single-sdk-feature-band.md b/proposed/single-sdk-feature-band.md index 74c9e4b73..0126422d9 100644 --- a/proposed/single-sdk-feature-band.md +++ b/proposed/single-sdk-feature-band.md @@ -1,360 +1,272 @@ -# Single SDK Feature Band with Global Feature Channels +# Monthly SDK Minor Releases **Owner** [marcpopMSFT](https://github.com/marcpopMSFT) -Today, SDK feature bands, SDK tools, and Visual Studio are coupled in ways that is complex to manage and confusing for users. The challenge with changing this is users can receive new features or behavior changes without intentionally opting in. This is especially problematic for managed environments and source build partners that prioritize stability. We propose a single SDK feature band strategy, combined with a global feature channel setting that all SDK-loaded components honor. This setting has three states: baseline, stable, and preview. New behavior or new features should never show up in baseline. New features should initially be enabled only in preview. Stable is for features that have gone through some preview validation and make include some behavior changes or new warnings. +Today, SDK feature bands, SDK tools, Visual Studio, workloads, and servicing branches are coupled in ways that are complex to manage and confusing for users. New features arrive in quarterly feature bands, while enterprise source build partners remain on the first feature band to preserve behavioral stability. -## Scenarios and User Experience - -### Scenario 1: Enterprise Source build partner requires maximum stability +We propose replacing SDK feature bands with monthly minor SDK releases. For example, the .NET 12 GA SDK would be `12.0.0`, followed by `12.1.0`, `12.2.0`, and so on. Each monthly minor is an explicit feature boundary. The latest minor receives new features, while customers that require maximum stability can remain on the original `12.0.x` line and receive only security and reliability fixes. -Some source build partners consume servicing builds and needs strict behavioral predictability. They configure the global channel to baseline. New features and behavior changes remain off by default across SDK, MSBuild, Roslyn, NuGet, MSTest, and other participating components. Today, these partners stay on the N.0.1xx feature band in order to prioritize stability. +Release boundaries provide stronger isolation than a shared feature-flag system. In particular, analyzer, compiler, and API-shape changes can affect customers even when a tool attempts to gate user-visible behavior. -Outcome: - -- Servicing updates can include security and reliability fixes. -- Existing behavior remains stable unless explicitly opted in. -- Partner validation costs and risk are reduced. -- Customers using source build SDKs can use the same SDK on multiple platforms with the same behavior with a simple environment variable -- Source build partners can choose additional features through the stable channel and source build customers can even choose to try out previews which has been a long term ask. +## Scenarios and User Experience -### Scenario 2: Visual Studio stable users get curated, stable behavior +### Enterprise source-build partner requires maximum stability -A developer on Visual Studio stable channel receives SDK updates from the internal branch insertion path. They get behavior considered production-ready for the stable channel, while preview-only changes remain off. They get the latest runtime with all security fixes and any tooling security fixes as well. +An enterprise source-build partner remains on the original `12.0.x` line. It receives security and reliability fixes without taking new SDK or tooling features. Outcome: -- Stable channel receives deliberate feature lighting. -- Behavior aligns with VS stable expectations. -- Mid-cycle surprises are reduced. +- Servicing updates exclude new features and intentional default changes, although necessary security or reliability fixes can still have observable effects. +- New features do not depend on every SDK-loaded component correctly implementing a shared flag. +- Partner validation cost and risk are reduced. +- The release version clearly identifies the stability boundary. -### Scenario 3: Visual Studio Canary/Insider users validate upcoming behavior +### Visual Studio stable users receive monthly tooling updates -A developer in VS canary receives the public 11.0.1xx SDK build with preview branding. Their global channel is preview, so new behavior can be enabled early for validation. +A developer on a supported Visual Studio stable channel receives the latest stable monthly SDK minor according to Visual Studio insertion and servicing policies. The SDK includes the latest applicable runtime and tooling security fixes. Outcome: -- Early adopter feedback happens before stable rollout. -- Preview-only changes do not leak into stable/baseline channels by default. -- Reduces the need to worry about the Insider behavior as it'll be the same as Canary +- Features can reach stable customers monthly instead of quarterly. +- Preview content is validated before monthly promotion. +- SDK release boundaries align more closely with the Visual Studio release cadence. -### Scenario 4: VS Code user gets flexible feature control +### Visual Studio Canary users validate the next monthly release -A developer using VS Code and the .NET SDK can choose their preferred feature channel to match their development needs. They default to stable for a balance of new features and stability. If they want maximum stability, they can set the environment variable to baseline. If they want to try cutting-edge features early, they can opt into preview. +A developer on Visual Studio Canary receives preview builds of the next SDK minor from the public release branch. Outcome: -- Stable channel is a sensible default for most developers. -- Power users have direct control via environment variable configuration. -- Independent of IDE choice; behavior is consistent across any editor using the SDK. -- Easy to experiment with new features without waiting for broader SDK releases. -- With each major release, VSCode will update the SDK installed to a new band resulting in a new baseline. - -## Alternatives - -### Monthly SDK minor releases - -Instead of using feature channels within a single SDK feature band, the SDK could adopt monthly minor releases. For example, the .NET 12 GA SDK would be `12.0.0`, followed by `12.1.0`, `12.2.0`, and so on in subsequent months. Each monthly SDK would replace the previous monthly release as the actively supported feature release and contain the latest available runtime, including applicable security and reliability fixes. - -Monthly feature bands were also considered, but versions such as `12.0.100` followed by `12.0.200` or `12.0.1000` continue the feature-band concept and do not communicate the monthly release ordering as directly. +- Tooling receives validation before the next monthly promotion. +- Preview behavior does not appear in the current stable monthly release. +- Visual Studio Insiders can consume the Canary flow without requiring a separate SDK build. -#### Release and branch model +### Command-line and VS Code users select an SDK release -Development would primarily occur in a long-lived preview branch. It could be as simple as a public release/12.x branch with all public codeflow to this branch. Once a month, the preview content intended for release would be promoted to a long-lived stable branch which couild just be internal/release/12.x which has internal codeflow of the runtime version. Each month we'd update the branding in each branch separately. +A developer using the .NET CLI or VS Code can use `global.json` and existing SDK acquisition mechanisms to remain on the original stability line, select a monthly minor, or roll forward to newer monthly releases. -The original `12.0.x` release line would remain available as the stability-oriented release for customers that want security and reliability fixes without new features (specifically, enterprise source build partners). This produces at least three logical release paths: - -- The original `12.0.x` stability line. -- The latest stable monthly minor release. -- The next monthly minor release in preview. - -Monthly promotion introduces a risk of drift between preview and stable. We could have codeflow from stable tooling to the stable branch but that would cause mirror conflicts or alternatively, we could require all stable tooling changes be made in the internal/release branch. Any security fixes would have to be ported on release day to the preview branch. - -#### Servicing and security fixes +Outcome: -Only the latest monthly minor and the original `12.0.x` release line would be serviced. Superseded monthly minors would remain installable but would not receive further fixes. The `12.0.x` line would receive security and reliability fixes but no new features, providing a predictable option for enterprise source-build and other stability-focused customers. +- The SDK version communicates the feature set without an additional global configuration. +- SDK selection continues to support projects with different stability requirements; whether monthly minors install side by side remains an installer-design decision. +- Moving to a newer feature set is an explicit SDK version change. -The servicing policy needs to distinguish among: +## Requirements -- Runtime security and reliability updates included in an SDK release. -- SDK or tooling hotfixes that do not require a runtime release. -- Workload updates released between monthly SDK releases. -- Fixes required by Visual Studio or source-build consumers that remain on a different SDK release path. +### Goals -Security and reliability fixes need an explicit propagation path to the original stability line, the current stable monthly release, the next preview, Visual Studio's supported SDK builds, and any dedicated source-build branch. Stable tooling fixes would need to flow through the VMR or an equivalent internal release process rather than flowing only into the preview branch. +- Replace quarterly SDK feature bands with monthly minor SDK releases. +- Make the SDK version an explicit and reliable feature boundary. +- Deliver stable tooling features monthly. +- Preserve the original `N.0.x` line for customers that require security and reliability fixes without new features. +- Maintain a preview path for the next monthly minor through Visual Studio Canary. +- Define predictable branching, branding, promotion, and servicing processes. +- Define how tooling fixes reach both the VMR and Visual Studio without introducing unmanageable mirror conflicts or check-in overhead. +- Update workloads, installers, SDK selection, and release automation for the new compatibility boundary. -The policy must also define what happens when a runtime security release is delayed, skipped, or released out of band. A runtime release should not necessarily require a new SDK minor, but supported SDK lines still need a way to acquire that runtime update. +### Non-goals -#### SDK and runtime version relationship +- Changing runtime versioning to match the SDK's monthly minor. +- Requiring the SDK and runtime contained in it to have the same version. +- Redesigning component-specific experimental feature flags. +- Supporting every superseded monthly minor indefinitely. +- Changing the feature rollout experience of components loaded directly by Visual Studio rather than through the SDK. -SDK and runtime versions would intentionally be allowed to differ. For example, an SDK hotfix `12.2.1` might contain runtime `12.0.7`, and a new monthly SDK minor preview would contain the most recently available runtime patch rather than a runtime released on the same day. Release notes would need to make this relationship clear. +## Versioning Model -The SDK version components would have the following meaning: +The SDK version components have the following meaning: - Major: the annual .NET release. - Minor: a monthly SDK feature release. -- Patch: an SDK/tooling hotfix or a release used to carry an updated workload set between monthly feature releases. +- Patch: an SDK or tooling hotfix, or a release used to carry an updated workload set between monthly feature releases. - Prerelease label: builds of the next monthly minor before promotion to stable. -Using the patch component for both SDK hotfixes and workload updates preserves a three-part version but means patch numbers identify release order rather than a particular type of change. Release tooling and documentation must not assume that every patch increment has the same cause. - -#### Visual Studio integration - -The preview SDK would continue to flow to Visual Studio Canary for validation. The stable monthly SDK would be available to supported Visual Studio channels according to their insertion and servicing policies. Visual Studio Insiders could continue to consume the preview flow through Canary rather than requiring a separate SDK build. - - -#### Source-build contract - -Enterprise source-build partners that require maximum stability could remain on `12.0.x` and receive security and reliability fixes without taking monthly feature releases. Other source-build consumers could move to newer monthly minors through their normal distribution update process. - -Unlike the feature-channel proposal, a customer remaining on `12.0.x` could not opt into selected newer SDK features without moving to a newer monthly SDK. This loses a benefit of the feature-channel model for customers that must acquire the SDK from a distribution feed but want newer features. On the other hand, release boundaries provide stronger isolation than relying on every component to gate all behavior correctly. This is particularly important for changes such as analyzer fixes that may introduce new warnings even when the change is otherwise considered a correctness fix. - -#### Workloads, installers, and SDK selection - -Existing workload and SDK infrastructure encodes feature-band identity in workload manifests, workload sets, package IDs, version validation, and selection logic. This model would need to define the monthly minor as the new compatibility boundary and update those systems accordingly. - -Workload set versions would generally match the SDK version. For example, the workload set for `12.2.0` would use that version, while SDK hotfixes and mid-month workload updates would consume successive patch numbers such as `12.2.1` and `12.2.2`. The release process must define ordering when both an SDK hotfix and a workload update are required in the same month and ensure that an SDK can resolve a compatible workload set after either kind of update. - -Existing `global.json` version selection and roll-forward behavior would allow customers to remain on `12.0.x`, select a particular monthly SDK, or move to newer monthly releases. The exact behavior of each roll-forward policy across minor releases needs to be specified, including whether existing feature-band-oriented policies retain their current names and how they map to monthly minors. - -Installer and acquisition behavior also needs an explicit contract: - -- Whether monthly minors install side by side or replace the previous monthly SDK. -- How MSI related-product and upgrade relationships are represented. -- How uninstalling a monthly SDK affects shared runtimes and workload content. -- How Microsoft Update targets standalone SDKs on the original stability line versus later monthly minors. -- How SDKs installed by Visual Studio are detected and serviced separately from standalone SDKs. - -#### Transition - -Adopting this model at the beginning of a major release is simpler than changing versioning after customers and tooling have already consumed feature-band versions. One transition option is to retain the existing feature-band model through .NET 11, including a final feature band if needed, and begin monthly minor releases with .NET 12. - -The transition plan would need to identify and update automation that parses SDK feature bands, including workload tooling, `global.json` handling, installers, Microsoft Update, release pipelines, support tooling, and documentation. Compatibility behavior is required for tools that encounter both the older feature-band scheme and the monthly-minor scheme. - -#### Benefits and drawbacks - -The primary benefits of this approach are: - -- Monthly versions communicate release order directly and align SDK tooling delivery with a monthly Visual Studio cadence. -- Features can reach stable customers monthly rather than waiting for a quarterly feature band. -- Release boundaries provide stronger isolation for stability-focused customers. -- The SDK does not depend on every loaded component implementing, naming, testing, documenting, and honoring a shared feature-channel setting correctly. -- Tooling teams can use normal version and branch boundaries instead of maintaining a growing set of indefinitely supported feature gates. - -The primary drawbacks are: - -- Source-build customers remaining on the original stability line cannot opt into selected newer features. -- Workload, installer, SDK selection, release, and servicing infrastructure require significant changes. -- Preview-to-stable promotion and fix propagation can create branch drift and merge debt. -- Visual Studio and source-build may still require separate servicing paths, limiting the expected branch reduction. -- SDK and runtime versions may differ in ways that require clear diagnostics and documentation. -- Monthly minors increase the number of SDK versions customers and support teams encounter. - -This alternative should be selected if the operational cost of monthly promotion, servicing, installer, workload, and version-selection changes is lower than the governance and compatibility risk of requiring every SDK-loaded component to implement feature channels correctly. Before selecting it, the design needs validated plans for security-fix propagation, Visual Studio servicing, source-build support, workload versioning, installer upgrade behavior, and the transition from feature bands. - -## Requirements - -### Goals +For example: -- Define a single global configuration that is consumed across all .NET SDK-loaded components. -- Provide three explicit feature channels: baseline, stable, preview. -- Ensure new features or behavior changes default to off for baseline. -- Ensure new features or behavior changes light up first in preview. -- Enable controlled advancement from preview to stable based on explicit promotion. -- Preserve servicing safety: no accidental behavior lights-up in servicing trains. -- Align Visual Studio channel insertion with intended behavior channel semantics. -- Keep .NET optional workload acquisition aligned to latest stable builds across VS channels. -- Reduce branch management costs down to a single feature band sourced from two branches -- Stable from major version N (eg .NET 11) will automatically be included in baseline of N+1 (eg .NET 12) +- `12.0.0-preview.1.`: First preview of .NET 12 SDK +- `12.0.0`: the annual GA and the beginning of the stability-oriented release line. +- `12.0.1`: a security or reliability update to the original stability line. +- `12.1.0`: the first monthly SDK feature release. +- `12.2.0-preview.`: a preview of the next monthly SDK feature release. +- `12.2.1`: a hotfix or workload update after `12.2.0`. -### Non-Goals +The SDK and runtime versions are intentionally independent. An SDK hotfix such as `12.2.1` might contain runtime `12.0.3`. A monthly SDK preview contains the most recently available runtime patch rather than requiring a runtime release on the same day. Release notes and diagnostics must make the relationship clear. -- Redesigning component-specific feature-flag systems end-to-end. -- Guaranteeing identical behavior for non-participating tools outside the SDK composition. -- Replacing existing TFM-based compatibility controls. -- Defining every individual feature's rollout criteria in this proposal. -- Changing any rollout or versioning for optional workloads. -- Change how the feature rollout and experience of components loaded into Visual Studio are managed +Using the patch component for both SDK hotfixes and workload updates means patch numbers identify release order rather than a particular kind of change. Release tooling and documentation must not assume that every patch increment has the same cause. -## Stakeholders and Reviewers +## Release and Branch Model -- SDK: feature-band ownership and global configuration contract -- MSBuild: engine behavior gating and branch/codeflow model -- Roslyn: compiler/analyzer defaults and compatibility modes -- NuGet: restore/package behavior gating where applicable -- MSTest: test SDK/runtime behavior gating -- Source build partners: default channel semantics and validation guidance -- Visual Studio: channel insertion, branding, and defaults +Development occurs primarily in a long-lived public `release/12.x` branch. Public code flow from tooling repositories targets this branch. Preview builds of the next monthly minor are produced from it and flow to Visual Studio Canary. -## Design +Once a month, approved preview content is promoted to a long-lived internal stable branch, such as `internal/release/12.x`. The public preview and internal stable branches are branded independently, with the version update and promotion process automated where possible. -### Global feature channel +The model has three logical release paths: -Introduce one SDK-wide configuration value (`SdkFeatureChannel`) with exactly three allowed values: +- The original `12.0.x` stability line. +- The latest stable monthly minor. +- The next monthly minor in preview. -- baseline -- stable -- preview +Only the original stability line and latest monthly minor are serviced. Superseded monthly minors remain installable but do not receive further fixes. -All participating components must query this value through a shared contract and use it to gate behavior changes. +## Tooling Code Flow -Initial policy for any new feature or behavior change: +Tooling teams continue flowing public development into the public `release/12.x` branch for the next monthly SDK preview. Stable fixes must also reach the internal VMR branch used to produce the stable SDK and, when applicable, Visual Studio. -- baseline: off -- stable: off (unless explicitly promoted) -- preview: on (unless explicitly held back) +It is critical that we reduce the engineering costs that we currently pay for feature band releases: +- Branding +- Branching +- Implicit versions +- Runtime updates +- Workloads releases +- darc subscription and channel maintenance +- VS insertion coordination especially main vs. stable -Promotion policy: +The design must select one of the following models: -- A feature starts as preview-on, stable-off, baseline-off. -- Promotion to stable requires explicit approval and release notes in a planned update. -- Baseline remains off by default, with opt-in available for customers that explicitly choose it. -- Minimum preview soak time before promotion is two months. +### Code flow with mirror conflict resolution -### Configuration sources and precedence +Stable tooling changes flow automatically into the internal stable branch. The mirror and code-flow infrastructure must distinguish public preview content from stable servicing content and provide a supported way to resolve conflicts. -The final value is provided through environment propagation so all child tools inherit the same channel. The SDK host sets the effective environment variable `DOTNET_SDK_FEATURE_CHANNEL` early in startup (first step in `Program.cs`) before invoking any tool components. +Benefits: -Default channel behavior is configured at SDK build time: +- A tooling fix has one authoritative check-in. +- Automated propagation reduces the chance that a required fix is omitted from either the SDK or Visual Studio. +- Tooling repositories retain their normal ownership and validation processes. -- Source-build distributions default to baseline. -- Microsoft SDK distributions default to stable. +Costs and risks: -Customers can override with the environment variable if they choose a different risk posture. +- The current public-to-internal mirror topology may blur preview and stable intent. +- Conflicts between the public preview branch and internal stable branch can block propagation. +- The mirror system becomes part of the release-critical path and needs clear ownership and service-level expectations. -Precedence (highest to lowest): +### Dual check-in by tooling teams -1. Command-line explicit override (if introduced) -2. Environment variable explicit value -3. Host-computed default written by SDK startup -4. SDK build-time default +Tooling teams check stable fixes into both their normal repository or branch and the VMR or internal release branch when the fix is needed by both the SDK and Visual Studio. -global.json integration may be added later, but is not required for the initial design. +Benefits: -Open questions: +- Each destination receives an explicit, independently validated change. +- The model does not depend on solving preview-to-stable mirror conflicts first. +- Tooling teams can tailor a fix to each branch when the branches have diverged. -- How do we ensure this behavior propogates from the SDK to the component tool? -- What should the behavior be inside of .NET components running inside of Visual Studio and how do we coordinate that. +Costs and risks: -### Cross-component contract +- Duplicate check-ins increase tooling-team workload and can diverge. +- Tooling teams typically insert into VS from a build from their repo and into the SDK in the VMR +- A fix can be missed in one destination. +- Security fixes require coordinated validation and disclosure-safe propagation across multiple repositories. -Each participating component defines: +### Decision criteria -- Behavior identifier (feature or breaking behavior ID) -- First enabled channel -- Promotion history (preview to stable) -- Override mechanism (if any) +The code-flow model should be selected with the tooling teams and VMR owners based on: -To improve transparency and auditing, components should also publish a machine-readable manifest of gated behaviors and channel thresholds. +- Whether the mirror can reliably distinguish preview development from stable servicing. +- Whether conflicts can be detected, assigned, and resolved within release timelines. +- Whether one check-in can satisfy the validation requirements for both SDK and Visual Studio. +- The expected frequency of fixes that must reach both destinations. +- The operational cost and omission risk of dual check-ins. +- Ownership of failures in the propagation path. -The SDK provides the channel context; each component owns implementation details while following a common policy. +Until this decision is made, the proposal does not assume that monthly promotion alone solves tooling branch management. The selected model must include a security-fix path and a recovery process for failed or incomplete propagation. -### Visual Studio channel strategy +## Servicing and Security Fixes -Proposed VS integration model: +The servicing policy must distinguish among: -- Public branch 11.0.1xx: - - Preview branding - - Insert into VS canary - - Global channel default: preview +- Runtime security and reliability updates included in an SDK release. +- SDK or tooling hotfixes that do not require a runtime release. +- Workload updates released between monthly SDK releases. +- Fixes required by Visual Studio or source-build consumers on a different SDK release path. -- Internal branch build: - - Stable branding - - Includes MSRC fixes and latest runtimes - - Insert into VS stable and last servicing version. VS typically releases a new GA and a final release of the last minor version on the same day and we would update both. - - Global channel default: stable - - Preview behavior remains default-disabled; customer opt-in is allowed +Security and reliability fixes need an explicit propagation path to the original stability line, the current stable monthly release, the next preview, supported Visual Studio SDK builds, and any dedicated source-build branch. A runtime security release does not necessarily require a new SDK minor, but every supported SDK line still needs a way to acquire the runtime update. -- VS insiders: - - Do not insert SDK directly - - Consume preview flow from canary +The policy must also cover delayed, skipped, and out-of-band runtime releases. Any security fix needed in both stable and preview must be applied through the selected tooling code-flow model rather than waiting for the next monthly promotion. -### Optional workloads strategy +## Visual Studio Integration -For optional .NET workloads: +- The next monthly SDK preview flows to Visual Studio Canary. +- The current stable monthly SDK is available to supported Visual Studio channels according to their insertion and servicing policies. +- Visual Studio Insiders consume the preview flow through Canary rather than requiring a separate SDK build. +- We would try to avoid any insiders insertions unless a blocking bug necessitated an update +- Components loaded directly by Visual Studio continue to follow their existing Visual Studio rollout policies. -- Always build workload artifacts from internal SDK version. -- Insert workload artifacts into all VS channels. +## Source-build Contract -No additional compatibility contract is required for workloads in this proposal. +Enterprise source-build partners that require maximum stability can remain on `12.0.x` and receive security and reliability fixes without taking monthly feature releases. Other source-build consumers can move to newer monthly minors through their normal distribution update process. -### MSBuild and similar component branch flow +A customer remaining on `12.0.x` cannot opt into selected features from later monthly minors without moving to a newer SDK. This tradeoff is intentional: release boundaries provide stronger isolation than relying on every component to gate behavior correctly. It is particularly important for analyzer and compiler fixes that can introduce warnings, change syntax trees or APIs, or otherwise affect downstream tooling. -We will not ship two SDK/tooling versions in parallel for the same feature band. +The next minor preview should be buildable with a prior stable release so 12.4.0 can be built with 12.3.0. The previews of the SDK will have to build with N-2 SDKs as the N-1 will still be unreleased and being worked on. -Rationale: +## Workloads, Installers, and SDK Selection -- Command-line usage of `dotnet` inside VS canary/insiders has not produced enough critical feedback to justify the operational complexity of dual-version shipping. +Existing workload and SDK infrastructure encodes feature-band identity in workload manifests, workload sets, package IDs, version validation, and selection logic. Monthly minors become the new compatibility boundary, and these systems must be updated accordingly. -Updated branch and insertion policy for MSBuild and similar tooling teams: +Workload set versions generally match the SDK version. For example, the workload set for `12.2.0` uses that version, while SDK hotfixes and mid-month workload updates consume successive patch numbers such as `12.2.1` and `12.2.2`. The release process must define ordering when an SDK hotfix and workload update are both required in the same month. -- Preview tooling ships from `main`. -- Those preview bits flow into VS canary and the .NET vNext SDK. -- Released SDKs ship tooling only from stable tooling branches. -- No separate preview-branded/stable-branded split for the same released feature band. +Existing `global.json` version selection and roll-forward behavior must allow customers to remain on `12.0.x`, select a particular monthly SDK, or move to newer monthly releases. The exact behavior of each roll-forward policy across minor releases must be specified, including how feature-band-oriented policy names map to monthly minors. -This keeps preview validation where it is most useful (canary and vNext) while reducing branch/codeflow complexity and release risk for shipped SDKs. +Installer and acquisition behavior also needs an explicit contract: -Risk: +- Whether monthly minors install side by side or replace the previous monthly SDK. +- How MSI related-product and upgrade relationships are represented. +- How uninstalling a monthly SDK affects shared runtimes and workload content. +- How Microsoft Update targets standalone SDKs on the original stability line versus later monthly minors. +- How SDKs installed by Visual Studio are detected and serviced separately from standalone SDKs. -This potentially limits the amount of feedback tooling teams would get on new features before promoting them to stable as they'd only be available in vNext or VS/msbuild.exe. +## Transition -### Servicing safety rules +Adopting this model at the beginning of a major release is simpler than changing versioning after customers and tooling have consumed feature-band versions. The proposed transition is to retain the existing feature-band model through .NET 11, including a final feature band if needed, and begin monthly minor releases with .NET 12. -In servicing trains: +The transition plan must identify and update automation that parses SDK feature bands, including workload tooling, `global.json` handling, installers, Microsoft Update, release pipelines, support tooling, and documentation. Tools that encounter both the old feature-band scheme and the monthly-minor scheme need defined compatibility behavior. -- No new behavior should silently turn on for stable or baseline. -- Security and reliability fixes may ship, but behavior-changing defaults require explicit promotion in a planned update. -- Rollback options are: flip the feature off via hotfix when critical, or fix forward in the next servicing release. +## Benefits and Drawbacks -## Q and A +Benefits: -### Why a three-state model instead of a binary preview toggle? +- Monthly versions communicate release order directly and align SDK tooling delivery with a monthly Visual Studio cadence. +- Features reach stable customers monthly rather than waiting for a quarterly feature band. +- Release boundaries provide stronger isolation for stability-focused customers. +- The SDK does not depend on every loaded component implementing and honoring a shared feature-channel setting. +- Tooling teams use normal version and branch boundaries instead of maintaining an expanding set of feature gates. -A binary model cannot represent baseline needs independently from mainstream stable users. Three states separate strict stability from normal stable adoption and preview validation. +Drawbacks: -## Risks and Unknowns +- Source-build customers on the original stability line cannot opt into selected newer features. +- Workload, installer, SDK selection, release, and servicing infrastructure require significant changes. +- Preview-to-stable promotion and fix propagation can create branch drift and merge debt. +- Visual Studio and source-build may still require separate servicing paths. +- SDK and runtime versions can differ in ways that require clear diagnostics and documentation. +- Monthly minors increase the number of SDK versions encountered by customers and support teams. -- Cross-component adoption lag: not all components may adopt `SdkFeatureChannel` and `DOTNET_SDK_FEATURE_CHANNEL` at the same pace, leading to inconsistent behavior. -- Environment propagation correctness: if the variable is not set early enough in SDK startup, child tools may observe incorrect defaults. -- Host/tooling interaction complexity: IDEs, build servers, and custom hosts may inject conflicting environment values. -- Configuration discoverability: users may not understand why behavior differs by channel without strong diagnostics and documentation. -- Manifest quality risk: machine-readable behavior manifests may drift from implementation if not validated in CI. -- Enforcement consistency risk across repos: without shared policy checks, teams may implement channel gating differently or incompletely. -- Promotion calibration risk: a two-month preview window may be too short or too long depending on feature blast radius. -- Servicing pressure: urgent fixes may tempt channel policy exceptions that undermine trust in stable/baseline promises. -- Branch/codeflow divergence: internal/public flow patterns can create merge debt and delayed fixes if governance is weak. -- Mirror topology risk for split public/internal versions: current one-way public to internal mirroring can accidentally blur stable versus preview intent. -- Cherry-pick debt risk: if internal stable and preview diverge, security and reliability fixes may require manual multi-branch propagation. -- Validation matrix risk: every participating repo may need baseline/stable/preview validation, increasing CI cost and latency. -- Diagnostics burden: support teams may need additional tooling to quickly determine the effective channel in customer environments. +## Risks and Open Questions -### Enforcement approach +- Choose code flow with mirror conflict resolution or dual check-ins for tooling fixes needed by both the SDK and Visual Studio. +- Define ownership and service expectations for the selected tooling propagation path. +- Validate the monthly promotion and branding automation. +- Define security-fix propagation for the stability line, current stable minor, next preview, Visual Studio, and source build. +- Define workload compatibility and patch-number ordering. +- Specify `global.json` roll-forward behavior across monthly minors. +- Define installer, Microsoft Update, and side-by-side installation behavior. +- Confirm the model and operational responsibilities with tooling teams and VMR owners. -Open questions: +## Alternatives Considered -- How do we enforce this in every contributing repo? - - PR review guidance as a minimum - - What other enforcement can we create? -- Do we need the ability to dump all new features into a machine and human readable format for review and comparison against intent/docs/PRs? - - It'd be great to be able to tag issues/PRs on which release they are in as well. +### Continue quarterly feature bands -Unknowns to validate during review: +The SDK could retain versions such as `12.0.100`, `12.0.200`, `12.0.300`, and `12.0.400`. This avoids much of the transition cost, but it preserves the current feature-band concept, delays stable feature delivery, and does not communicate monthly release ordering directly. -- Whether `baseline` is intuitive enough for external customers and partners. -- Whether `DOTNET_SDK_FEATURE_CHANNEL` should be the only v1 control surface or paired with a CLI switch immediately. -- Whether all in-scope components can enforce gating with acceptable performance overhead. -- Whether existing per-tool feature flags can be harmonized without migration churn. -- Which minimal cross-repo policy checks are required for v1 to avoid silent non-compliance. -- Whether current public-to-internal mirror infrastructure can support a preview-branch intermediary with controlled internal stable promotion. -- Whether stable/canary insertion branches should be structurally separated in all participating repos. +### Single feature band with global feature channels -### Does this replace existing feature flags? +We considered retaining one SDK feature band and introducing a global feature channel such as `baseline`, `stable`, or `preview`. Every participating SDK-loaded component would read the channel and gate new features or behavior accordingly. -No. Component-level flags can remain. This proposal adds a single, global compatibility channel that defines default behavior posture. +We did not select this approach because: -### Open questions to resolve +- It requires substantial cross-repository infrastructure, governance, validation, diagnostics, and ongoing feature-gate management. +- It moves complexity into testing without ensuring that every feature or breaking change is correctly gated. +- Analyzer and compiler fixes can introduce warnings or behavioral changes, especially for customers using warnings as errors, and often cannot be practically flag-gated. +- Experimental API and syntax-tree changes can break analyzers even when user-visible behavior is behind a flag. +- A continuously evolving feature band conflicts with the stability expectations of enterprise and source-build customers. +- Release boundaries are easier for customers and support teams to identify than the effective state of many component-level gates. -1. Whether `DOTNET_SDK_FEATURE_CHANNEL` should be the only v1 control surface or whether a CLI switch should also ship in v1. -2. Minimum schema for the machine-readable behavior manifest. -3. Is there a change to the versioning schema we could do for the SDK? We could change to match runtime versioning but we sometimes have SDK hotfixes so it might be confusing to release an 11.0.108 that has 11.0.7 runtime in it. \ No newline at end of file +Component-specific flags can still be used for experiments where appropriate, but they are not the SDK-wide compatibility or release mechanism. \ No newline at end of file From 0eaa3cfa8bd8aa9f9794e114773312b0b802f529 Mon Sep 17 00:00:00 2001 From: Marc Paine Date: Tue, 25 Aug 2026 15:19:31 -0700 Subject: [PATCH 09/13] Update to include a motivation section and include reference to the uninstall tool and releases.json library. --- proposed/single-sdk-feature-band.md | 34 +++++++++++++++++++---------- 1 file changed, 23 insertions(+), 11 deletions(-) diff --git a/proposed/single-sdk-feature-band.md b/proposed/single-sdk-feature-band.md index 0126422d9..b6d864360 100644 --- a/proposed/single-sdk-feature-band.md +++ b/proposed/single-sdk-feature-band.md @@ -2,7 +2,25 @@ **Owner** [marcpopMSFT](https://github.com/marcpopMSFT) -Today, SDK feature bands, SDK tools, Visual Studio, workloads, and servicing branches are coupled in ways that are complex to manage and confusing for users. New features arrive in quarterly feature bands, while enterprise source build partners remain on the first feature band to preserve behavioral stability. +## Motivation + +.NET tooling (MSBuild, NuGet, Roslyn, etc) and Visual Studio already ship on a monthly cadence starting with 18.0, but stable SDK features are delivered through quarterly feature bands. This mismatch creates a release-management problem every month: teams must coordinate monthly tooling and Visual Studio releases with an SDK release model that advances only once per quarter. + +Internally, each feature band requires repeated engineering and coordination work for: + +- Branding and branching. +- Implicit version updates. +- Runtime and workload updates. +- `darc` subscription and channel maintenance. +- Visual Studio insertion coordination, particularly between main and stable branches. + +Many of these we should solve regardless of this proposal but the current state still creates a lot of additional friction and mental load at a minimum. + +Externally, the mismatch makes it harder to explain which tooling features and fixes are available in Visual Studio, in the standalone SDK, and in servicing releases. Customers can receive monthly Visual Studio and tooling updates while the SDK's visible feature boundary remains quarterly. + +Feature bands add another layer of complexity. Versions such as `12.0.100`, `12.0.200`, and `12.0.300` do not clearly communicate release order, support status, or their relationship to the monthly tooling releases. The concept is .NET SDK-specific and requires customers, support teams, and internal tooling to understand special version-selection and servicing rules. + +## Proposal We propose replacing SDK feature bands with monthly minor SDK releases. For example, the .NET 12 GA SDK would be `12.0.0`, followed by `12.1.0`, `12.2.0`, and so on. Each monthly minor is an explicit feature boundary. The latest minor receives new features, while customers that require maximum stability can remain on the original `12.0.x` line and receive only security and reliability fixes. @@ -112,15 +130,6 @@ Only the original stability line and latest monthly minor are serviced. Supersed Tooling teams continue flowing public development into the public `release/12.x` branch for the next monthly SDK preview. Stable fixes must also reach the internal VMR branch used to produce the stable SDK and, when applicable, Visual Studio. -It is critical that we reduce the engineering costs that we currently pay for feature band releases: -- Branding -- Branching -- Implicit versions -- Runtime updates -- Workloads releases -- darc subscription and channel maintenance -- VS insertion coordination especially main vs. stable - The design must select one of the following models: ### Code flow with mirror conflict resolution @@ -211,14 +220,17 @@ Installer and acquisition behavior also needs an explicit contract: - Whether monthly minors install side by side or replace the previous monthly SDK. - How MSI related-product and upgrade relationships are represented. - How uninstalling a monthly SDK affects shared runtimes and workload content. +- How the .NET uninstall tool identifies monthly SDK releases and determines which installations are eligible for removal. - How Microsoft Update targets standalone SDKs on the original stability line versus later monthly minors. - How SDKs installed by Visual Studio are detected and serviced separately from standalone SDKs. +The release library and other compliance, inventory, and support tooling may also encode feature-band assumptions when parsing, classifying, or comparing SDK versions. These tools must be audited and updated so that monthly minors are recognized as SDK feature boundaries and the original `N.0.x` stability line is handled correctly. + ## Transition Adopting this model at the beginning of a major release is simpler than changing versioning after customers and tooling have consumed feature-band versions. The proposed transition is to retain the existing feature-band model through .NET 11, including a final feature band if needed, and begin monthly minor releases with .NET 12. -The transition plan must identify and update automation that parses SDK feature bands, including workload tooling, `global.json` handling, installers, Microsoft Update, release pipelines, support tooling, and documentation. Tools that encounter both the old feature-band scheme and the monthly-minor scheme need defined compatibility behavior. +The transition plan must identify and update automation that parses SDK feature bands, including workload tooling, `global.json` handling, installers, the .NET uninstall tool, the release library, Microsoft Update, release pipelines, compliance and inventory systems, support tooling, and documentation. Tools that encounter both the old feature-band scheme and the monthly-minor scheme need defined compatibility behavior. ## Benefits and Drawbacks From d1bf50e40556cd6e3a961b287024bd3cb48bed05 Mon Sep 17 00:00:00 2001 From: Marc Paine Date: Fri, 4 Sep 2026 14:46:16 -0700 Subject: [PATCH 10/13] Update based on internal review and plan to transition during 11 --- proposed/single-sdk-feature-band.md | 71 ++++++++++++++++++++++++++--- 1 file changed, 64 insertions(+), 7 deletions(-) diff --git a/proposed/single-sdk-feature-band.md b/proposed/single-sdk-feature-band.md index b6d864360..d11230639 100644 --- a/proposed/single-sdk-feature-band.md +++ b/proposed/single-sdk-feature-band.md @@ -1,7 +1,18 @@ # Monthly SDK Minor Releases +Two-band transition in .NET 11 and monthly minor releases beginning in .NET 12 + **Owner** [marcpopMSFT](https://github.com/marcpopMSFT) +## Decision Summary + +We will make this change in two stages: + +- **.NET 11:** Ship exactly two SDK feature bands. `11.0.1xx` is the long-lived servicing band and accepts only security fixes and fixes required to unblock servicing. `11.0.2xx` is the feature-delivery band. +- **.NET 12:** Replace SDK feature-band versions with monthly minor SDK releases, such as `12.1.0`, `12.2.0`, and `12.3.0`. + +We will announce both stages together. During the early .NET 12 previews, we will address the infrastructure and ecosystem gaps required to support minor-version SDK releases. + ## Motivation .NET tooling (MSBuild, NuGet, Roslyn, etc) and Visual Studio already ship on a monthly cadence starting with 18.0, but stable SDK features are delivered through quarterly feature bands. This mismatch creates a release-management problem every month: teams must coordinate monthly tooling and Visual Studio releases with an SDK release model that advances only once per quarter. @@ -22,7 +33,22 @@ Feature bands add another layer of complexity. Versions such as `12.0.100`, `12. ## Proposal -We propose replacing SDK feature bands with monthly minor SDK releases. For example, the .NET 12 GA SDK would be `12.0.0`, followed by `12.1.0`, `12.2.0`, and so on. Each monthly minor is an explicit feature boundary. The latest minor receives new features, while customers that require maximum stability can remain on the original `12.0.x` line and receive only security and reliability fixes. +We propose a phased rollout that reduces the number of release trains in .NET 11 while the ecosystem prepares for monthly minor SDK releases in .NET 12. + +### Phase 1: .NET 11 two-band transition + +.NET 11 ships exactly two SDK feature bands: + +| Version | Purpose | Allowed changes | +| --- | --- | --- | +| `11.0.1xx` | Long-lived servicing baseline | Security fixes and fixes required to unblock servicing | +| `11.0.2xx` | Feature delivery | New SDK and tooling features, plus applicable servicing fixes | + +There will be no `11.0.3xx` or `11.0.4xx` feature bands. Existing feature-band-aware infrastructure remains in place for .NET 11, avoiding a versioning migration before the required host, workload, installer, acquisition, update, and release infrastructure is ready. + +### Phase 2: .NET 12 monthly minor releases + +Beginning with .NET 12, SDK feature bands are replaced with monthly minor SDK releases. The .NET 12 GA SDK is `12.0.0`, followed by `12.1.0`, `12.2.0`, and so on. Each monthly minor is an explicit feature boundary. The latest minor receives new features, while the original `12.0.x` line provides a stability-oriented servicing boundary. Release boundaries provide stronger isolation than a shared feature-flag system. In particular, analyzer, compiler, and API-shape changes can affect customers even when a tool attempts to gate user-visible behavior. @@ -73,6 +99,8 @@ Outcome: ### Goals +- Ship exactly two SDK feature bands in .NET 11, with distinct servicing and feature-delivery roles. +- Preserve existing feature-band-aware infrastructure during the .NET 11 transition. - Replace quarterly SDK feature bands with monthly minor SDK releases. - Make the SDK version an explicit and reliable feature boundary. - Deliver stable tooling features monthly. @@ -228,9 +256,27 @@ The release library and other compliance, inventory, and support tooling may als ## Transition -Adopting this model at the beginning of a major release is simpler than changing versioning after customers and tooling have consumed feature-band versions. The proposed transition is to retain the existing feature-band model through .NET 11, including a final feature band if needed, and begin monthly minor releases with .NET 12. +Adopting monthly minor versions at the beginning of a major release is simpler than changing versioning after customers and tooling have consumed feature-band versions. .NET 11 therefore uses a two-band transition model: + +- `11.0.1xx` remains the rollback and servicing boundary for customers and source-build partners that require maximum stability. It receives only security fixes and fixes required to unblock servicing. +- `11.0.2xx` receives new SDK and tooling features. +- No additional .NET 11 feature bands are produced. + +During the early .NET 12 previews, we will identify, assign, and close the gaps required to use monthly minor versions. This work includes host and SDK resolution, `global.json`, workload tooling, installers, the .NET uninstall tool, the release library, Microsoft Update, WinGet, DNIM, getdotnet, release pipelines, VMR infrastructure, compliance and inventory systems, support tooling, third-party version parsing, and documentation. + +Tools that encounter both the feature-band scheme used through .NET 11 and the monthly-minor scheme beginning in .NET 12 need defined compatibility behavior. Changes that affect the ecosystem should land early enough in the .NET 12 preview cycle to allow validation and correction before stabilization. + +## External Communication -The transition plan must identify and update automation that parses SDK feature bands, including workload tooling, `global.json` handling, installers, the .NET uninstall tool, the release library, Microsoft Update, release pipelines, compliance and inventory systems, support tooling, and documentation. Tools that encounter both the old feature-band scheme and the monthly-minor scheme need defined compatibility behavior. +We will publish a blog post that explains both stages of the plan: + +- Why .NET 11 retains feature-band numbering while reducing the release model to two bands. +- The servicing-only role of `11.0.1xx` and the feature-delivery role of `11.0.2xx`. +- Why monthly minor versions are the intended .NET 12 direction. +- Which infrastructure and ecosystem gaps will be addressed during the .NET 12 previews. +- What customers, partners, and tool authors should expect for SDK selection, workloads, installation, servicing, and version parsing. + +Migration guidance for affected tooling must be available before the first .NET 12 preview that uses the new versioning model. ## Benefits and Drawbacks @@ -251,16 +297,27 @@ Drawbacks: - SDK and runtime versions can differ in ways that require clear diagnostics and documentation. - Monthly minors increase the number of SDK versions encountered by customers and support teams. -## Risks and Open Questions +## Implementation Work and Remaining Questions + +The following decisions are settled: + +- .NET 11 has exactly two SDK feature bands. +- `11.0.1xx` receives only security fixes and fixes required to unblock servicing. +- `11.0.2xx` is the .NET 11 feature-delivery band. +- Monthly minor SDK versions are the intended .NET 12 direction. +- Both stages will be communicated publicly. + +The .NET 12 preview work must: - Choose code flow with mirror conflict resolution or dual check-ins for tooling fixes needed by both the SDK and Visual Studio. - Define ownership and service expectations for the selected tooling propagation path. -- Validate the monthly promotion and branding automation. +- Validate monthly promotion and branding automation. - Define security-fix propagation for the stability line, current stable minor, next preview, Visual Studio, and source build. - Define workload compatibility and patch-number ordering. - Specify `global.json` roll-forward behavior across monthly minors. -- Define installer, Microsoft Update, and side-by-side installation behavior. -- Confirm the model and operational responsibilities with tooling teams and VMR owners. +- Define installer, Microsoft Update, uninstall, acquisition, rollback, and side-by-side installation behavior. +- Audit first-party and third-party systems that parse or compare SDK versions. +- Confirm operational responsibilities with tooling teams and VMR owners. ## Alternatives Considered From e524e3a79208e8cdba7a694f9db27518c66f46ff Mon Sep 17 00:00:00 2001 From: Marc Paine Date: Fri, 4 Sep 2026 16:45:19 -0700 Subject: [PATCH 11/13] Updated based on recent PR feedback --- proposed/single-sdk-feature-band.md | 20 ++++++++++++++++++-- 1 file changed, 18 insertions(+), 2 deletions(-) diff --git a/proposed/single-sdk-feature-band.md b/proposed/single-sdk-feature-band.md index d11230639..953446530 100644 --- a/proposed/single-sdk-feature-band.md +++ b/proposed/single-sdk-feature-band.md @@ -136,10 +136,16 @@ For example: - `12.2.0-preview.`: a preview of the next monthly SDK feature release. - `12.2.1`: a hotfix or workload update after `12.2.0`. +Incrementing the minor resets the patch component to zero. Within the feature-delivery train, `12.(M+1).0` succeeds `12.M.P` and normally contains SDK and tooling content at least as recent as the prior minor, except for an intentional rollback. The `12.0.x` line is a parallel stability-oriented servicing family rather than the predecessor of every monthly minor. + The SDK and runtime versions are intentionally independent. An SDK hotfix such as `12.2.1` might contain runtime `12.0.3`. A monthly SDK preview contains the most recently available runtime patch rather than requiring a runtime release on the same day. Release notes and diagnostics must make the relationship clear. +When a `12.0.P` servicing release and a `12.M.0` feature release ship in the same month, they contain the same runtime servicing level. A preview of the next minor may temporarily contain the runtime servicing level from the preceding month. + Using the patch component for both SDK hotfixes and workload updates means patch numbers identify release order rather than a particular kind of change. Release tooling and documentation must not assume that every patch increment has the same cause. +When regular feature delivery ends, the final minor becomes the servicing line for the feature train. Subsequent updates advance its patch component rather than creating additional minors. + ## Release and Branch Model Development occurs primarily in a long-lived public `release/12.x` branch. Public code flow from tooling repositories targets this branch. Preview builds of the next monthly minor are produced from it and flow to Visual Studio Canary. @@ -237,9 +243,19 @@ The next minor preview should be buildable with a prior stable release so 12.4.0 ## Workloads, Installers, and SDK Selection -Existing workload and SDK infrastructure encodes feature-band identity in workload manifests, workload sets, package IDs, version validation, and selection logic. Monthly minors become the new compatibility boundary, and these systems must be updated accordingly. +Existing workload and SDK infrastructure encodes feature-band identity in workload manifests, workload sets, package IDs, version validation, and selection logic. These systems must recognize monthly SDK minors while continuing to model workload compatibility boundaries independently. + +Workload set package versions generally match the SDK version. For example, SDK `12.2.0` can consume `Microsoft.NET.Workloads.12.2.0`, while SDK hotfixes and mid-month workload updates consume successive patch numbers such as `12.2.1` and `12.2.2`. The release process must define ordering when an SDK hotfix and workload update are both required in the same month. + +Workload manifest package compatibility bands do not need to change for every monthly minor. The initial .NET 12 manifest package could be: + +`Microsoft.NET.Workload.Mono.ToolChain.Current.Manifest-12.0.0` + +SDKs `12.1.0` through `12.6.x` could continue resolving manifests from that compatibility band. If a workload change requires a new compatibility boundary, a later minor can rebaseline it, for example: + +`Microsoft.NET.Workload.Mono.ToolChain.Current.Manifest-12.7.0` -Workload set versions generally match the SDK version. For example, the workload set for `12.2.0` uses that version, while SDK hotfixes and mid-month workload updates consume successive patch numbers such as `12.2.1` and `12.2.2`. The release process must define ordering when an SDK hotfix and workload update are both required in the same month. +SDK `12.7.0` and later releases would then resolve the new manifest band, while earlier SDK minors remain on the original band. Workload commands and Visual Studio select the appropriate band without requiring customers to manage this distinction directly. Existing `global.json` version selection and roll-forward behavior must allow customers to remain on `12.0.x`, select a particular monthly SDK, or move to newer monthly releases. The exact behavior of each roll-forward policy across minor releases must be specified, including how feature-band-oriented policy names map to monthly minors. From c867a36b74d45a993c6ab3f64adb01c1091e4155 Mon Sep 17 00:00:00 2001 From: Marc Paine Date: Thu, 5 Nov 2026 08:31:49 -0800 Subject: [PATCH 12/13] Update based on internal feedback and focus on the 11.0.2xx plan --- INDEX.md | 1 + ...and.md => simplified-sdk-feature-bands.md} | 132 ++++++++++-------- 2 files changed, 71 insertions(+), 62 deletions(-) rename proposed/{single-sdk-feature-band.md => simplified-sdk-feature-bands.md} (73%) diff --git a/INDEX.md b/INDEX.md index 19aca180f..b968d7b56 100644 --- a/INDEX.md +++ b/INDEX.md @@ -110,6 +110,7 @@ Use update-index to regenerate it: | | [Readonly references in C# and IL verification.](proposed/verifiable-ref-readonly.md) | | | | [Ref returns in C# and IL verification.](proposed/verifiable-ref-returns.md) | | | | [SDK Analysis Level Property and Usage](proposed/sdk-analysis-level.md) | (PM) [Chet Husk](https://github.com/baronfel), (Engineering) [Daniel Plaisted](https://github.com/dsplaisted) | +| | [SDK Feature Delivery: .NET 11 Plan and Future Versioning Options](proposed/simplified-sdk-feature-bands.md) | [marcpopMSFT](https://github.com/marcpopMSFT) | | | [Swift Interop](proposed/swift-interop.md) | [Andy Gocke](https://github.com/agocke), [Jeremy Koritzinsky](https://github.com/jkoritzinsky) | | | [Target AVX2 in R2R images](proposed/vector-instruction-set-default.md) | [Richard Lander](https://github.com/richlander) | diff --git a/proposed/single-sdk-feature-band.md b/proposed/simplified-sdk-feature-bands.md similarity index 73% rename from proposed/single-sdk-feature-band.md rename to proposed/simplified-sdk-feature-bands.md index 953446530..4121df6c1 100644 --- a/proposed/single-sdk-feature-band.md +++ b/proposed/simplified-sdk-feature-bands.md @@ -1,17 +1,17 @@ -# Monthly SDK Minor Releases +# SDK Feature Delivery: .NET 11 Plan and Future Versioning Options -Two-band transition in .NET 11 and monthly minor releases beginning in .NET 12 +Monthly feature delivery in .NET 11, with future SDK numbering and branding under discussion **Owner** [marcpopMSFT](https://github.com/marcpopMSFT) ## Decision Summary -We will make this change in two stages: +The committed implementation scope is monthly SDK and tooling feature delivery within the .NET 11 `11.0.2xx` feature band, retaining existing feature-band versioning. - **.NET 11:** Ship exactly two SDK feature bands. `11.0.1xx` is the long-lived servicing band and accepts only security fixes and fixes required to unblock servicing. `11.0.2xx` is the feature-delivery band. -- **.NET 12:** Replace SDK feature-band versions with monthly minor SDK releases, such as `12.1.0`, `12.2.0`, and `12.3.0`. +- **Future versioning:** Changes to SDK numbering and branding for .NET 12, including monthly minor versions, remain under discussion. -We will announce both stages together. During the early .NET 12 previews, we will address the infrastructure and ecosystem gaps required to support minor-version SDK releases. +This document records the monthly-minor proposal but does not approve it or commit its implementation, release timing, or announcement. Any future change requires a separate decision and implementation plan. Completion of the .NET 11 work does not depend on adopting that proposal. ## Motivation @@ -31,11 +31,11 @@ Externally, the mismatch makes it harder to explain which tooling features and f Feature bands add another layer of complexity. Versions such as `12.0.100`, `12.0.200`, and `12.0.300` do not clearly communicate release order, support status, or their relationship to the monthly tooling releases. The concept is .NET SDK-specific and requires customers, support teams, and internal tooling to understand special version-selection and servicing rules. -## Proposal +## .NET 11 Implementation Plan -We propose a phased rollout that reduces the number of release trains in .NET 11 while the ecosystem prepares for monthly minor SDK releases in .NET 12. +The .NET 11 work reduces the number of release trains and enables monthly feature delivery independently of any later SDK numbering or branding decision. -### Phase 1: .NET 11 two-band transition +### Servicing and Feature Delivery .NET 11 ships exactly two SDK feature bands: @@ -44,17 +44,41 @@ We propose a phased rollout that reduces the number of release trains in .NET 11 | `11.0.1xx` | Long-lived servicing baseline | Security fixes and fixes required to unblock servicing | | `11.0.2xx` | Feature delivery | New SDK and tooling features, plus applicable servicing fixes | -There will be no `11.0.3xx` or `11.0.4xx` feature bands. Existing feature-band-aware infrastructure remains in place for .NET 11, avoiding a versioning migration before the required host, workload, installer, acquisition, update, and release infrastructure is ready. +There will be no `11.0.3xx` or `11.0.4xx` feature bands. Existing feature-band-aware infrastructure remains in place for .NET 11; this plan does not require the versioning migration described in the future proposal. -### Phase 2: .NET 12 monthly minor releases +New SDK and tooling features ship through successive `11.0.2xx` patch releases rather than additional feature bands. Unlike the servicing-only `11.0.1xx` line, patch updates within `11.0.2xx` can therefore contain new features. -Beginning with .NET 12, SDK feature bands are replaced with monthly minor SDK releases. The .NET 12 GA SDK is `12.0.0`, followed by `12.1.0`, `12.2.0`, and so on. Each monthly minor is an explicit feature boundary. The latest minor receives new features, while the original `12.0.x` line provides a stability-oriented servicing boundary. +The tentative schedule is to release `11.0.200` in February, followed by `11.0.201` in March and subsequent monthly feature releases. Previews are available ahead of release through Visual Studio Canary/Insiders. Dates and standalone preview acquisition details remain to be finalized. + +### Branching, Code Flow, and Monthly Promotion + +The .NET 11 flow distinguishes three VMR branch roles: + +- A public development/preview branch receives new SDK and tooling features and produces previews for Visual Studio Canary. +- A non-shipping internal preview mirror carries the preview content plus protected fixes required for the next release. +- A monthly release fork supplies the stable release. It aligns with the tooling branches for that release, including Roslyn stable. + +Security fixes needed in both stable and the next release must be applied to the stable release and the internal preview mirror so that monthly promotion preserves them. Security-only SDK changes are made in the VMR rather than requiring a separate SDK-repository stable branch. Protected changes must not backflow into public repositories before disclosure. + +For example, `11.0.201` has already shipped when the release fork for `11.0.202` is created from the internal preview content. That fork aligns with Roslyn stable for `202`; Roslyn insiders and the internal preview then advance toward `11.0.203`. The release fork is distinct from the internal preview branch, not a replacement for an unshipped `201`. + +Use persistent VS Canary and VS Stable channels, updating the versioned producer branches behind them instead of recreating channels and subscriptions each month. Record the branch mappings and promotion operation in the release procedure, and automate the monthly mechanics where practical. + +## Future SDK Versioning Proposal (Not Approved) + +The remaining sections describe a monthly-minor option for future SDK releases, not committed .NET 12 work. Retaining feature-band numbering is also an option. Versions such as `12.0.0` and `12.1.0`, branch names, package names, and release sequences below are illustrative and do not establish approved .NET 12 branding, support policy, implementation scope, or rollout timing. + +Requirements expressed below apply only if this option is separately approved. Its scope, owners, migration schedule, and communication plan would need to be agreed before implementation. + +### Monthly Minor Releases + +Under this option, SDK feature bands would be replaced with monthly minor SDK releases. The annual GA SDK would be `12.0.0`, followed by `12.1.0`, `12.2.0`, and so on. Each monthly minor would be an explicit feature boundary. The latest minor would receive new features, while the original `12.0.x` line would provide a stability-oriented servicing boundary. Release boundaries provide stronger isolation than a shared feature-flag system. In particular, analyzer, compiler, and API-shape changes can affect customers even when a tool attempts to gate user-visible behavior. -## Scenarios and User Experience +### Scenarios and User Experience -### Enterprise source-build partner requires maximum stability +#### Enterprise source-build partner requires maximum stability An enterprise source-build partner remains on the original `12.0.x` line. It receives security and reliability fixes without taking new SDK or tooling features. @@ -65,7 +89,7 @@ Outcome: - Partner validation cost and risk are reduced. - The release version clearly identifies the stability boundary. -### Visual Studio stable users receive monthly tooling updates +#### Visual Studio stable users receive monthly tooling updates A developer on a supported Visual Studio stable channel receives the latest stable monthly SDK minor according to Visual Studio insertion and servicing policies. The SDK includes the latest applicable runtime and tooling security fixes. @@ -75,7 +99,7 @@ Outcome: - Preview content is validated before monthly promotion. - SDK release boundaries align more closely with the Visual Studio release cadence. -### Visual Studio Canary users validate the next monthly release +#### Visual Studio Canary users validate the next monthly release A developer on Visual Studio Canary receives preview builds of the next SDK minor from the public release branch. @@ -85,7 +109,7 @@ Outcome: - Preview behavior does not appear in the current stable monthly release. - Visual Studio Insiders can consume the Canary flow without requiring a separate SDK build. -### Command-line and VS Code users select an SDK release +#### Command-line and VS Code users select an SDK release A developer using the .NET CLI or VS Code can use `global.json` and existing SDK acquisition mechanisms to remain on the original stability line, select a monthly minor, or roll forward to newer monthly releases. @@ -95,12 +119,10 @@ Outcome: - SDK selection continues to support projects with different stability requirements; whether monthly minors install side by side remains an installer-design decision. - Moving to a newer feature set is an explicit SDK version change. -## Requirements +### Requirements -### Goals +#### Goals -- Ship exactly two SDK feature bands in .NET 11, with distinct servicing and feature-delivery roles. -- Preserve existing feature-band-aware infrastructure during the .NET 11 transition. - Replace quarterly SDK feature bands with monthly minor SDK releases. - Make the SDK version an explicit and reliable feature boundary. - Deliver stable tooling features monthly. @@ -110,7 +132,7 @@ Outcome: - Define how tooling fixes reach both the VMR and Visual Studio without introducing unmanageable mirror conflicts or check-in overhead. - Update workloads, installers, SDK selection, and release automation for the new compatibility boundary. -### Non-goals +#### Non-goals - Changing runtime versioning to match the SDK's monthly minor. - Requiring the SDK and runtime contained in it to have the same version. @@ -118,7 +140,7 @@ Outcome: - Supporting every superseded monthly minor indefinitely. - Changing the feature rollout experience of components loaded directly by Visual Studio rather than through the SDK. -## Versioning Model +### Versioning Model The SDK version components have the following meaning: @@ -146,7 +168,7 @@ Using the patch component for both SDK hotfixes and workload updates means patch When regular feature delivery ends, the final minor becomes the servicing line for the feature train. Subsequent updates advance its patch component rather than creating additional minors. -## Release and Branch Model +### Release and Branch Model Development occurs primarily in a long-lived public `release/12.x` branch. Public code flow from tooling repositories targets this branch. Preview builds of the next monthly minor are produced from it and flow to Visual Studio Canary. @@ -160,13 +182,13 @@ The model has three logical release paths: Only the original stability line and latest monthly minor are serviced. Superseded monthly minors remain installable but do not receive further fixes. -## Tooling Code Flow +### Tooling Code Flow Tooling teams continue flowing public development into the public `release/12.x` branch for the next monthly SDK preview. Stable fixes must also reach the internal VMR branch used to produce the stable SDK and, when applicable, Visual Studio. The design must select one of the following models: -### Code flow with mirror conflict resolution +#### Code flow with mirror conflict resolution Stable tooling changes flow automatically into the internal stable branch. The mirror and code-flow infrastructure must distinguish public preview content from stable servicing content and provide a supported way to resolve conflicts. @@ -182,7 +204,7 @@ Costs and risks: - Conflicts between the public preview branch and internal stable branch can block propagation. - The mirror system becomes part of the release-critical path and needs clear ownership and service-level expectations. -### Dual check-in by tooling teams +#### Dual check-in by tooling teams Tooling teams check stable fixes into both their normal repository or branch and the VMR or internal release branch when the fix is needed by both the SDK and Visual Studio. @@ -199,7 +221,7 @@ Costs and risks: - A fix can be missed in one destination. - Security fixes require coordinated validation and disclosure-safe propagation across multiple repositories. -### Decision criteria +#### Decision criteria The code-flow model should be selected with the tooling teams and VMR owners based on: @@ -212,7 +234,7 @@ The code-flow model should be selected with the tooling teams and VMR owners bas Until this decision is made, the proposal does not assume that monthly promotion alone solves tooling branch management. The selected model must include a security-fix path and a recovery process for failed or incomplete propagation. -## Servicing and Security Fixes +### Servicing and Security Fixes The servicing policy must distinguish among: @@ -225,7 +247,7 @@ Security and reliability fixes need an explicit propagation path to the original The policy must also cover delayed, skipped, and out-of-band runtime releases. Any security fix needed in both stable and preview must be applied through the selected tooling code-flow model rather than waiting for the next monthly promotion. -## Visual Studio Integration +### Visual Studio Integration - The next monthly SDK preview flows to Visual Studio Canary. - The current stable monthly SDK is available to supported Visual Studio channels according to their insertion and servicing policies. @@ -233,7 +255,7 @@ The policy must also cover delayed, skipped, and out-of-band runtime releases. A - We would try to avoid any insiders insertions unless a blocking bug necessitated an update - Components loaded directly by Visual Studio continue to follow their existing Visual Studio rollout policies. -## Source-build Contract +### Source-build Contract Enterprise source-build partners that require maximum stability can remain on `12.0.x` and receive security and reliability fixes without taking monthly feature releases. Other source-build consumers can move to newer monthly minors through their normal distribution update process. @@ -241,7 +263,7 @@ A customer remaining on `12.0.x` cannot opt into selected features from later mo The next minor preview should be buildable with a prior stable release so 12.4.0 can be built with 12.3.0. The previews of the SDK will have to build with N-2 SDKs as the N-1 will still be unreleased and being worked on. -## Workloads, Installers, and SDK Selection +### Workloads, Installers, and SDK Selection Existing workload and SDK infrastructure encodes feature-band identity in workload manifests, workload sets, package IDs, version validation, and selection logic. These systems must recognize monthly SDK minors while continuing to model workload compatibility boundaries independently. @@ -270,31 +292,19 @@ Installer and acquisition behavior also needs an explicit contract: The release library and other compliance, inventory, and support tooling may also encode feature-band assumptions when parsing, classifying, or comparing SDK versions. These tools must be audited and updated so that monthly minors are recognized as SDK feature boundaries and the original `N.0.x` stability line is handled correctly. -## Transition - -Adopting monthly minor versions at the beginning of a major release is simpler than changing versioning after customers and tooling have consumed feature-band versions. .NET 11 therefore uses a two-band transition model: - -- `11.0.1xx` remains the rollback and servicing boundary for customers and source-build partners that require maximum stability. It receives only security fixes and fixes required to unblock servicing. -- `11.0.2xx` receives new SDK and tooling features. -- No additional .NET 11 feature bands are produced. +### Readiness and Migration -During the early .NET 12 previews, we will identify, assign, and close the gaps required to use monthly minor versions. This work includes host and SDK resolution, `global.json`, workload tooling, installers, the .NET uninstall tool, the release library, Microsoft Update, WinGet, DNIM, getdotnet, release pipelines, VMR infrastructure, compliance and inventory systems, support tooling, third-party version parsing, and documentation. +Adopting monthly minor versions at the beginning of a major release would be simpler than changing versioning after customers and tooling have consumed feature-band versions. That consideration does not commit a change for .NET 12 or make the .NET 11 plan a transition to this option. -Tools that encounter both the feature-band scheme used through .NET 11 and the monthly-minor scheme beginning in .NET 12 need defined compatibility behavior. Changes that affect the ecosystem should land early enough in the .NET 12 preview cycle to allow validation and correction before stabilization. +If a future versioning change is approved, its implementation plan must identify affected systems, owners, compatibility requirements, and a validated migration schedule. The impact inventory includes host and SDK resolution, `global.json`, workload tooling, installers, the .NET uninstall tool, the release library, Microsoft Update, WinGet, DNIM, getdotnet, release pipelines, VMR infrastructure, compliance and inventory systems, support tooling, third-party version parsing, and documentation. -## External Communication +Tools that encounter both feature-band and monthly-minor schemes would need defined compatibility behavior. The migration schedule must allow ecosystem validation and correction before stabilization; no .NET 12 preview deadline is committed here. -We will publish a blog post that explains both stages of the plan: +### Communication for a Future Versioning Change -- Why .NET 11 retains feature-band numbering while reducing the release model to two bands. -- The servicing-only role of `11.0.1xx` and the feature-delivery role of `11.0.2xx`. -- Why monthly minor versions are the intended .NET 12 direction. -- Which infrastructure and ecosystem gaps will be addressed during the .NET 12 previews. -- What customers, partners, and tool authors should expect for SDK selection, workloads, installation, servicing, and version parsing. +If a numbering change is approved, its communication plan must explain the chosen versioning model, migration timing, ecosystem impact, and customer guidance. Guidance for affected tooling must be available before the first preview that uses the new model. -Migration guidance for affected tooling must be available before the first .NET 12 preview that uses the new versioning model. - -## Benefits and Drawbacks +### Benefits and Drawbacks Benefits: @@ -313,17 +323,11 @@ Drawbacks: - SDK and runtime versions can differ in ways that require clear diagnostics and documentation. - Monthly minors increase the number of SDK versions encountered by customers and support teams. -## Implementation Work and Remaining Questions - -The following decisions are settled: +### Open Decisions and Preconditions -- .NET 11 has exactly two SDK feature bands. -- `11.0.1xx` receives only security fixes and fixes required to unblock servicing. -- `11.0.2xx` is the .NET 11 feature-delivery band. -- Monthly minor SDK versions are the intended .NET 12 direction. -- Both stages will be communicated publicly. +The monthly-minor option requires a separate decision on SDK numbering and branding, including whether to adopt it for .NET 12 or retain feature-band versions. Neither the destination nor its implementation schedule is settled by this document. -The .NET 12 preview work must: +Before a future numbering change can ship, its approved implementation plan must: - Choose code flow with mirror conflict resolution or dual check-ins for tooling fixes needed by both the SDK and Visual Studio. - Define ownership and service expectations for the selected tooling propagation path. @@ -335,13 +339,17 @@ The .NET 12 preview work must: - Audit first-party and third-party systems that parse or compare SDK versions. - Confirm operational responsibilities with tooling teams and VMR owners. -## Alternatives Considered +### Alternatives Considered + +#### Retain feature-band numbering with monthly feature delivery + +Future SDK releases could retain a servicing baseline such as `12.0.1xx` and deliver monthly features through `12.0.2xx` patch releases, following the .NET 11 model. This would avoid the monthly-minor versioning migration while preserving monthly feature delivery, but would retain feature-band-specific version interpretation and selection rules. -### Continue quarterly feature bands +#### Continue quarterly feature bands The SDK could retain versions such as `12.0.100`, `12.0.200`, `12.0.300`, and `12.0.400`. This avoids much of the transition cost, but it preserves the current feature-band concept, delays stable feature delivery, and does not communicate monthly release ordering directly. -### Single feature band with global feature channels +#### Single feature band with global feature channels We considered retaining one SDK feature band and introducing a global feature channel such as `baseline`, `stable`, or `preview`. Every participating SDK-loaded component would read the channel and gate new features or behavior accordingly. From 77f4dd392294601f6f38544643a18607248126ad Mon Sep 17 00:00:00 2001 From: Marc Paine Date: Thu, 5 Nov 2026 13:25:29 -0800 Subject: [PATCH 13/13] Add guidance for microsoft update, new features, and source build --- proposed/simplified-sdk-feature-bands.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/proposed/simplified-sdk-feature-bands.md b/proposed/simplified-sdk-feature-bands.md index 4121df6c1..f19e21f5f 100644 --- a/proposed/simplified-sdk-feature-bands.md +++ b/proposed/simplified-sdk-feature-bands.md @@ -64,6 +64,24 @@ For example, `11.0.201` has already shipped when the release fork for `11.0.202` Use persistent VS Canary and VS Stable channels, updating the versioned producer branches behind them instead of recreating channels and subscriptions each month. Record the branch mappings and promotion operation in the release procedure, and automate the monthly mechanics where practical. +### Microsoft Update + +Microsoft Update continues servicing standalone SDKs by feature band. Customers with `11.0.1xx` receive updates within that band; installing `11.0.2xx` enables updates within the feature-delivery band. Microsoft Update does not move customers from `1xx` to `2xx`. If both bands are installed, both receive applicable updates. + +SDKs installed by Visual Studio continue to be serviced through Visual Studio. Standalone SDK updates include their bundled runtime updates. + +### Guidance for Tooling Teams + +New features from MSBuild, Roslyn, NuGet, analyzers, and other SDK components ship through `11.0.2xx`. Where practical, teams should initially ship a feature disabled by default, allow customers to opt in and provide feedback in a stable release, and enable it by default in a later release. + +This uses component-specific controls, not a new SDK-wide feature-channel setting. Features spanning multiple components must coordinate their dependencies, validation, and rollout. Release notes should identify when a feature becomes available and when its default changes. + +### Source-build Bootstrapping + +Source-build guidance should allow successive `11.0.2xx` releases to build using a previously released stable SDK and the required source-built inputs. Later releases may depend on tooling features from earlier released `2xx` SDKs; they are not required to remain buildable with `11.0.1xx`. + +Preview builds should use released bootstrap inputs rather than depend on SDK features available only in an unreleased SDK. The supported bootstrap inputs must be recorded and validated for each release. + ## Future SDK Versioning Proposal (Not Approved) The remaining sections describe a monthly-minor option for future SDK releases, not committed .NET 12 work. Retaining feature-band numbering is also an option. Versions such as `12.0.0` and `12.1.0`, branch names, package names, and release sequences below are illustrative and do not establish approved .NET 12 branding, support policy, implementation scope, or rollout timing.