modelcontextprotocol/csharp-sdk/prepare-release

Prepare Release

Prepare a new release for the modelcontextprotocol/csharp-sdk repository. This skill assesses the appropriate Semantic Versioning 2.0.0 level based on queued changes, bumps the version, runs API compatibility and diff tools, reviews documentation, drafts release notes, and creates a pull request containing all release artifacts.

Safety: This skill creates a local branch and PR. It must never create a GitHub release. Release creation is handled by the publish-release skill after this PR is merged.

User confirmation required: This skill NEVER pushes a branch or creates a pull request without explicit user confirmation. The user must review and approve all details before any remote operations occur.

Use the shared release branch reference for branch roles, previous-release lookup rules, and release work-branch naming.

Process

Work through each step sequentially. Present findings at each step and get user confirmation before proceeding. Skip any step that has no applicable items.

Step 0: Sync With Upstream

Every later step reads branches, tags, and file contents from the local repository. Stale local refs produce assessments that are wrong in ways that look plausible: a missing tag makes a released version invisible, and a stale branch hides merged PRs. Establish a complete, current view before reading anything.

1. Identify the remote that points at the canonical repository (modelcontextprotocol/csharp-sdk).

Do not assume it is named origin — in a fork-based checkout origin is often the fork: git remote -v

1. Fetch that remote's branches and tags, pruning deleted refs:

git fetch {upstream} --prune --prune-tags --tags

1. Confirm the tag for the most recent published release exists locally and resolves:

git rev-parse --verify v{previous}^{commit}

Report what changed as a result of the fetch — new tags, updated branch heads — so the user can see whether the starting state was stale.

Read every subsequent step's branch state from the remote-tracking refs ({upstream}/main, {upstream}/release/{MAJOR}.x), not from local branches, which may lag or have diverged.

Step 1: Select Source Branch

List candidate source/base branches via: gh api repos/{owner}/{repo}/branches --paginate --jq '[.[] | select(.name == "main" or (.name | startswith("release/"))) | .name]'

Present the list to the user and ask them to choose the source/base branch. Default selection: main.

The selected branch drives every subsequent step:

1. The branch on which the candidate version is read from src/Directory.Build.props.
2. The "previous release" lookup (constrained to v{MAJOR}.* on release/{MAJOR}.x).
3. The commit range from which PRs are collected.
4. The PR base (--base) for gh pr create at the end of the skill.

See release-branches.md for the structured branch rules.

Step 2: Determine Target and Gather PRs

The user may provide:

• A git ref (commit SHA, branch, or tag) — use as the target commit relative to the selected source/base branch
• No context — show the last 5 commits on the selected source/base branch (noting HEAD) and offer the option to enter a branch or tag name instead

Once the target is established:

1. Determine the previous release tag from gh release list — the highest semver among published releases that are ancestors of the target commit (exclude drafts with --exclude-drafts). Do not order by publication date; see release-branches.md for why the two differ and what breaks. On release/{MAJOR}.x, restrict candidates to tags matching v{MAJOR}.*; on main, there is no MAJOR filter.
2. Get the full list of PRs merged between the previous release tag and the target commit on the selected branch.
3. Read src/Directory.Build.props at the target commit. Extract <VersionPrefix> and <VersionSuffix>; the candidate version is {VersionPrefix} plus -{VersionSuffix} when the suffix is present (for example, 2.0.0-preview.1).
4. Verify the previous release tag is an ancestor of the target commit:

git merge-base --is-ancestor v{previous} {target}

If it is not an ancestor, stop and report. The two histories have diverged, which means the selected source branch is not a continuation of the previous release. Every downstream conclusion would be wrong: the PR range would be computed across unrelated history, and the ApiCompat baseline in Step 7 would report the previous release's entire API surface as removed. This is a source-selection problem, not a compatibility problem — do not attempt to suppress it.

The usual cause is that the previous release shipped from a different branch than the one selected. Re-run Step 1 and choose the branch that actually contains the previous release, or confirm with the user that a divergent source is intended and why.

Step 3: Categorize and Attribute

Sort every PR into one of four categories. See references/categorization.md for detailed guidance.

Entry format — * Description #PR by @author with co-authors when present:

* Description #PR by @author
* Description #PR by @author (co-authored by @user1 @Copilot)

Attribution rules:

• Harvest Co-authored-by trailers from all commits in each PR (not just the merge commit) to identify co-authors. Do this for every PR regardless of primary author.
• For Copilot-authored PRs, additionally check the copilot_work_started timeline event to identify the triggering user. That person becomes the primary author; @Copilot becomes a co-author.
• Omit the co-author parenthetical when there are none
• Sort entries within each section by merge date (chronological)

Step 4: Breaking Change Audit

Invoke the breaking-changes skill with the commit range from the previous release tag to the target commit. Examine every PR, assess impact, reconcile labels (offering to add/remove labels and comment on PRs), and get user confirmation.

Use the results (confirmed breaking changes with impact ordering and detail bullets) in the remaining steps.

Step 5: Assess Release Version

Using the categorized PRs from Step 3 and confirmed breaking changes from Step 4, assess the appropriate Semantic Versioning 2.0.0 release level. Follow the SemVer assessment guide (owned by the bump-version skill) for the full assessment criteria.

1. Classify the release level:

• MAJOR — if any confirmed breaking changes are present (API or behavioral), excluding changes to [Experimental] APIs
• MINOR — if no breaking changes but new public APIs, features, or obsoletion warnings are introduced
• PATCH — otherwise

1. Compute the recommended version from the previous release tag and branch context:

• Increment the appropriate component (MAJOR resets MINOR.PATCH to 0; MINOR resets PATCH to 0)
• For prerelease candidates such as preview.N or rc.N, the recommendation may simply increment the trailing integer per the assessment guide

1. Compare against the candidate version from src/Directory.Build.props. Flag any discrepancy:

• Under-versioned: The candidate is lower than the recommended level. This is a concern that should be resolved.
• Over-versioned: The candidate is higher than strictly required. This is acceptable under SemVer but worth noting.

1. Present the assessment with a summary table showing the previous release, change classification, recommended level, recommended version, and any discrepancy with the candidate. Include a brief rationale citing the most significant PRs.
2. Get user confirmation of the release version before proceeding.

Step 6: Create Release Branch and Bump Version

After the version is confirmed:

1. Create a local branch named release-{version} from the target commit (e.g., release-2.0.0-preview.1, release-1.3.1).
2. Update src/Directory.Build.props:

• Set <VersionPrefix> to the confirmed stable component
• Set <VersionSuffix> for prerelease versions, or clear it for stable versions; add the element if it is missing
• Update <PackageValidationBaselineVersion> when appropriate, per the rule in references/apicompat-apidiff.md. Read the current value from src/Directory.Build.props and derive the correct one from the versions actually published; never copy a version from an example. Show the derivation — current value, published versions considered, resulting value, and whether it changes — and get confirmation before editing. If the value changes, the [baseline-transition suppression audit](references/apicompat-apidiff.md#baseline-transition-suppression-audit) is mandatory.

1. Build the solution to verify the version change compiles: dotnet build

This step creates local changes only — nothing is committed or pushed yet.

Step 7: Run API Compatibility Check

Run API compatibility validation against the baseline version. Follow references/apicompat-apidiff.md for the full procedure.