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 post-VS-snap follow-up ~1 week later). Recommend the user reuse the same chat session throughout one snap cycle so context (PR numbers, branch names, channel IDs, 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. In some cases, a long-lived servicing branch like release/sdk10.0.3xx may be created from the old stable content to continue SDK-only flows (not VS insertion).

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 darc default channels to discover active branches and their channel mappings:

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

Identify the three named branches (main, release/insiders, release/stable) and their current VS channels. Also note any SDK channels (e.g., .NET 10.0.3xx SDK, .NET 11.0.1xx SDK) assigned to each branch — these will need to shift during the snap.

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.8).

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.
• The old stable version is retired (unless the user says otherwise, e.g., creating a release/sdk* branch).
• SDK channels shift to follow the content: any SDK channel on main that corresponds to the current VS version moves to release/insiders (since insiders now carries that content). SDK channels for the next major (e.g., .NET 11.0.1xx SDK) stay on main. If the next SDK band channel doesn't exist yet, note it as a follow-up.

Present a summary like:

Snap for VS 18.6 on dotnet/roslyn:
  main:              18.6 (VS main, .NET 10.0.3xx SDK, Razor SDK 10.3)  -> 18.7 (VS main, .NET 10.0.4xx SDK*, Razor SDK 10.4*)
  release/insiders:  18.5 (VS 18.5)                                     -> 18.6 (VS 18.6, .NET 10.0.3xx SDK, Razor SDK 10.3 from main)
  release/stable:    18.4 (VS 18.4)                                     -> 18.5 (VS 18.5)
  Old 18.4:          retired
  * .NET 10.0.4xx SDK channel may not exist yet -- follow up when created (Razor SDK bump deferred until then)

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 Draft pre-snap announcement email

A few days before the snap, a notification email should be sent to the team. Using the info from steps 1.1–1.2, draft the email. Ask the user for the snap date and time.

The email should follow this format:

Subject: Snap for {VS version} on {day of week}, {date}

Hi all,

We will snap for {VS version} on {day of week}, {date} ~ {time} PST. main will point to {new VS version} after the snap.

Following is important information about branches and dates.

Branch	Current VS	Current SDK	After-snap VS	After-snap SDK	Notes

Fill in each row using the VS channels and SDK channels discovered in step 1.2. For example, if main currently flows to .NET 10.0.3xx SDK and .NET 11.0.1xx SDK, show those in "Current SDK" and show the after-snap state (SDK channel moves to insiders, next-major stays on main). Mark channels that don't exist yet with * and add a footnote.

* {channel name} will be added when that channel is created.

If there's anything that needs to be checked in for QB mode, please contact the InfraSwat team.

Adapt the table to the actual branch structure:

• Include all active named branches and relevant servicing branches.
• Fill current/after-snap columns from darc default channels and PublishData.json.
• If the user provides a QB schedule or schedule link, include it.

Present the draft to the user for review and editing before they send it.

1.4 Check darc subscriptions and flows

List existing subscriptions and backflows:

darc get-subscriptions --exa

---

*Content truncated.*