snap

Branch Snap

Perform a branch snap (release branch cut) for dotnet repositories. A snap shifts the content of named branches forward by one VS minor version in a cascade.

IMPORTANT: This skill makes destructive changes (creates branches, opens PRs, updates subscriptions, moves milestones). Always gather info first, present the full plan, and get explicit user confirmation before executing any modifications.

NOTE: This skill works for multiple dotnet repos (e.g., dotnet/roslyn). Do not assume dotnet/roslyn — always confirm the repo.

SKILL MAINTENANCE: If you deviate from this skill during execution (e.g., a step doesn't work as described, a new step is needed, or the process has changed), remind the user to update this skill file so future snaps benefit from the fix.

SESSION: A snap spans multiple days (initial snap, then a follow-up after the scheduled VS snap). Recommend the user reuse the same chat session throughout one snap cycle so context (PR numbers, branch names, channel IDs, schedule dates, etc.) is preserved. If starting a new session, review session memory for prior snap state.

Branch Model

Roslyn (and similar repos) use three named branches that cascade during a snap:

A "snap for 18.6" means: main is currently at 18.6 and that content moves to insiders. The cascade is:

1. Merge release/insiders → release/stable: stable gets the old insiders content (18.5)
2. Merge main → release/insiders: insiders gets main's content (18.6) up to a specific commit
3. Bump main version to 18.7

After the snap, the old stable VS version (18.4 in this example) is retired from the named-branch cascade. If that content must continue servicing an SDK band, preserve it first by creating a long-lived branch such as release/10.0.4xx directly from the pre-snap release/stable commit. The previous SDK servicing branch can then be retired if its flow is no longer needed.

Older release/dev{version} branches (e.g., release/dev18.3 and below) remain for servicing only.

Prerequisites

Before starting, verify these CLI tools are available:

• gh — GitHub CLI, authenticated (gh auth status). The user may need to switch accounts via gh auth switch to one with push access to their fork.
• darc — .NET Arcade/BAR CLI for subscription management (darc authenticate must have been run)

Test with:

gh --version
darc get-subscriptions --exact --source-repo https://github.com/dotnet/roslyn --target-repo https://github.com/dotnet/dotnet

Fork-based workflow

Snap PRs are typically opened from a user's fork. Ask the user for their fork (e.g., {username}/roslyn). Branches are created in the fork via the GitHub API, and PRs are opened cross-fork with --head {forkOwner}:{branchName}. Verify the gh account has push access to the fork (gh api repos/{forkOwner}/{repo} --jq '.permissions').

Workflow

The snap process has three phases: Gather, Plan, Execute.

Phase 1: Gather Information

Collect all relevant state before proposing any changes:

1.1 Determine repo

• Ask which repo (default: the current repo via gh repo set-default --view). Note that if working in the Roslyn repo (dotnet/roslyn), then the snap will apply to Roslyn and Razor, as they are both in the repo, so multiple version updates will be necessary.

1.2 Discover branches and versions automatically

Use darc default channels and version files to infer the branch structure. Do not ask the user for branches or versions — infer them and present for confirmation.

Step A — List source-repository default channels to discover active branches and the build channels they publish to:

darc get-default-channels --source-repo https://github.com/{owner}/{repo}

Identify the three named branches (main, release/insiders, release/stable), current servicing branches, and their VS and SDK source channels.

Do not use this list alone to populate the email's SDK columns. A source channel selects builds for subscriptions; it does not identify every SDK destination consuming those builds. One source channel can feed multiple VMR branches and therefore multiple SDK versions. Determine actual SDK destinations from subscriptions in step 1.3.

Step B — Read versions and configs from all three branches:

• Fetch eng/Versions.props from each branch to get the current version.
  • For roslyn: VS version = Major + 13.Minor (e.g., Roslyn 5.6 → VS 18.6).
• Razor versions are also in eng/Versions.props (same file as Roslyn's version), using Razor-prefixed property names. Razor has two independent versions:
  • Razor VSIX/Addin version: use <RazorVsixVersionPrefix> directly (e.g., 18.8.1). Tracks the Visual Studio version like the rest of the snap cascade. <RazorAddinMajorVersion> tracks the major.minor (e.g., 18.8).
  • Razor SDK version: read <RazorMajorVersion> and <RazorMinorVersion> (e.g., 10.4). Tracks the .NET SDK band Razor ships into, not the VS version. The mapping is .NET <Major>.0.<Band>xx SDK <-> Razor <Major>.<Band> (e.g., .NET 10.0.4xx SDK <-> Razor 10.4, .NET 11.0.1xx SDK <-> Razor 11.1).
  • Note: src/Razor/Directory.Build.props maps these Razor-prefixed properties to the standard MSBuild properties (MajorVersion, MinorVersion, etc.) for Razor projects. During a snap, only edit eng/Versions.props — the Razor props file should not need changes.
• Fetch eng/config/PublishData.json from each branch to get insertion config (vsBranch, insertionCreateDraftPR, insertionTitlePrefix).
  • The JSON key is branchInfo (roslyn).

Step B.1 -- Detect Razor SDK version drift for each branch (roslyn only):

• For each branch, find the SDK default-channels assigned to it from Step A (e.g., .NET 10.0.4xx SDK).
• Among those, locate the channel whose major matches the branch's current Razor RazorMajorVersion. If multiple channels of the same major are temporarily assigned (e.g., both .NET 10.0.4xx SDK and .NET 10.0.5xx SDK), pick the lowest band -- Razor is versioned to the lowest SDK band it ships into, since higher bands roll forward and can consume the same package.
• Apply the mapping .NET <Major>.0.<Band>xx SDK -> expected Razor <Major>.<Band>.
• If no matching SDK channel exists for that branch (common on main immediately after a previous snap, before the next SDK band channel has been created), record the branch as "no matching SDK channel -- Razor SDK version bump deferred".
• If the expected version differs from the branch's current RazorMajorVersion.RazorMinorVersion, flag it as a drift to fix (during snap, see Phase 2 step 5b; during follow-up, see Phase 3 step 3.9).

Step C — Infer the snap cascade from the discovered state:

• The snap version is whatever main currently targets (e.g., 18.6).
• After snap: main bumps +1 minor, insiders gets main's current version, stable gets insiders' current version.
• Record the pre-snap release/stable commit as the candidate source for a new SDK servicing branch.
• Do not infer SDK flow changes yet. Determine them from the subscription topology in step 1.3; SDK flows do not necessarily move one-to-one with the VS branch cascade.

Present a summary like:

Snap for VS 18.6 on dotnet/roslyn:
  main:              18.6 -> 18.7
  release/insiders:  18.5 -> 18.6 (receives current main content)
  release/stable:    18.4 -> 18.5 (receives current insiders content)
  Old stable 18.4:   preserve in an SDK servicing branch or retire
  SDK destinations:  pending subscription analysis in step 1.3

If Step B.1 detected any Razor SDK version drift on the branches as they exist today (e.g., main already flows to .NET 10.0.4xx SDK but eng/Versions.props still says RazorMajorVersion=10, RazorMinorVersion=0), call it out explicitly -- it likely means a previous snap missed the bump and should be fixed in the same snap PR. Confirm with the user before proceeding.

1.3 Check darc subscriptions and determine SDK destinations

List existing forward flows, backflows, and VMR default channels:

darc get-subscriptions --exact --source-repo https://github.com/{owner}/{repo} --target-repo https://github.com/dotnet/dotnet
darc get-subscriptions --exact --source-repo https://github.com/dotnet/dotnet --target-repo https://github.com/{owner}/{repo}
darc get-default-channels --source-repo https://github.com/{owner}/{repo}
darc get-default-channels --source-repo https://github.com/dotnet/dotnet

Also check flows to SDK and runtime if relevant:

darc get-subscriptions --exact --source-repo https://github.com/{owner}/{repo} --target-repo https://github.com/dotnet/sdk
darc get-subscriptions --exact --source-repo https://github.com/{owner}/{repo} --target-repo https://github.com/dotnet/runtime

Build the current SDK-flow matrix as follows:

1. For each enabled forward subscription from the source repository to dotnet/dotnet, record its source channel and VMR target branch.
2. Map the target branch to its SDK name using the VMR default channels (for example, VMR main -> .NET 12.0.1xx SDK, release/11.0.1xx -> .NET 11.0.1xx SDK).
3. Associate the subscription's source channel with the source branches that publish to that channel.
4. Preserve every distinct SDK destination. A branch may legitimately feed multiple SDKs; do not collapse the list to one channel or assume the newest SDK replaces the previous one.

Then propose the after-snap flow matrix from the actual servicing requirements:

• P

Content truncated.