Semantic Versioning Assessment Guide

This reference describes how to assess the appropriate Semantic Versioning 2.0.0 (SemVer) release level for the C# MCP SDK based on the changes queued since the previous release.

SemVer Summary

The SDK follows SemVer 2.0.0 as documented in the C# SDK Versioning documentation. Given a version MAJOR.MINOR.PATCH:

MAJOR: Increment when incompatible API changes are included
MINOR: Increment when functionality is added in a backward-compatible manner
PATCH: Increment when only backward-compatible bug fixes are included

When incrementing:

MAJOR resets MINOR and PATCH to 0 (e.g., 1.2.3 → 2.0.0)
MINOR resets PATCH to 0 (e.g., 1.2.3 → 1.3.0)
PATCH increments only the PATCH component (e.g., 1.2.3 → 1.2.4)

Assessment Criteria

Evaluate every PR in the release range against these criteria, ordered from highest to lowest precedence.

MAJOR — Incompatible API Changes

Recommend a MAJOR version increment if any of the following are present:

Confirmed breaking changes from the breaking change audit (API or behavioral)
Removal of public types, members, or interfaces
Changes to parameter types, order, or count on public methods
Return type changes on public methods or properties
Sealing of previously unsealed types (with accessible constructors)
Escalation of [Obsolete] from warning to error
Removal of previously obsolete APIs

Exception — Experimental APIs: Changes to APIs annotated with [Experimental] do not require a MAJOR increment, even if they would otherwise be considered breaking. This includes changes that only affect consumers who have opted into an [Experimental] code path — for example, adding an abstract member to a public abstract class whose only accessible constructor is [Experimental]. If every path to the breaking impact requires suppressing an experimental diagnostic, the change is not considered breaking for versioning purposes. Note these changes but classify the release level based on the non-experimental changes.

MINOR — Backward-Compatible New Functionality

Recommend a MINOR version increment if no MAJOR criteria are met but any of the following are present:

Any new public APIs
New MCP capabilities or protocol features
Addition of [Obsolete] attributes producing build warnings (step 1 of obsoletion lifecycle)
Changes to [Experimental] APIs (regardless of whether they would be breaking outside the experimental surface)

PATCH — Everything Else

Recommend a PATCH version increment if no MAJOR or MINOR criteria are met.

Note: Releases that contain only documentation, test, or infrastructure changes may not warrant a release at all. Flag this to the user if no shipped-package changes are present.

Computing the Recommended Version

Parse the previous release tag to extract MAJOR.MINOR.PATCH.
Apply the assessed level:
- MAJOR: (MAJOR+1).0.0
- MINOR: MAJOR.(MINOR+1).0
- PATCH: MAJOR.MINOR.(PATCH+1)

Prereleases

While the candidate version uses a prerelease suffix (e.g., X.Y.Z-preview.N, X.Y.Z-rc.N), the recommended next version increments the trailing integer of the suffix: preview.3 → preview.4, rc.1 → rc.2.

Going to GA drops the suffix entirely: 2.0.0-rc.2 → 2.0.0.

This is purely about how to compute the next version. It does not declare any new policy about what kinds of changes are permitted between previews — refer to the existing versioning documentation for breaking-change policy.

Branch context

The "previous release" lookup selects the highest semver among published releases that are ancestors of the target commit, constrained to tags matching v{MAJOR}.* when assessing from a release/{MAJOR}.x servicing branch. On main, there is no MAJOR filter. It is not a date-ordered lookup; see release-branches.md.

The MAJOR/MINOR/PATCH classification criteria above are unchanged regardless of branch.

See release-branches.md for branch-role definitions and previous-release lookup rules.

Examples:

Previous release	Branch	Level	Recommended
`v1.2.0`	`main`	PATCH	`v1.2.1`
`v1.2.0`	`main`	MINOR	`v1.3.0`
`v1.2.0`	`main`	MAJOR	`v2.0.0`
`v2.0.0-preview.1`	`main`	(prerelease bump)	`v2.0.0-preview.2`
`v1.3.0`	`release/1.x`	PATCH	`v1.3.1`

Comparing Against the Candidate Version

After computing the recommended version:

Compare it against the candidate version (from src/Directory.Build.props or an existing draft release tag).
Present one of three outcomes:
- Match: The candidate aligns with the assessment. Proceed with confidence.
- Under-versioned: The candidate uses a lower increment level than the changes warrant (e.g., candidate is 1.2.1 but changes include new APIs requiring 1.3.0). Flag this as a concern — the version should be corrected.
- Over-versioned: The candidate uses a higher increment level than strictly required (e.g., candidate is 2.0.0 but no breaking changes). This is permitted by SemVer but worth noting for the user's awareness.

Presentation Format

Present the assessment as a summary table followed by a rationale:

### Version Assessment

| Aspect | Finding |
|--------|---------|
| Branch context | release/1.x |
| Previous release | v1.0.0 |
| Breaking changes | None confirmed |
| New API surface | Yes — 3 PRs add new public APIs |
| Bug fixes | Yes — 2 PRs fix runtime behavior |
| Recommended level | **MINOR** |
| Recommended version | `v1.1.0` |
| Candidate version | `1.1.0` ✅ matches |

**Rationale**: Three PRs introduce new public API surface (#101, #105, #112)
including new extension methods and configuration options. No confirmed breaking
changes. The candidate version in Directory.Build.props aligns with the MINOR
assessment.

When the candidate does not match, flag the discrepancy:

| Candidate version | `1.0.1` ⚠️ under-versioned (PATCH < MINOR) |

6.5 KiB Raw Blame History