From 975019bb9cd4bc7a79ce2614ca60bdf65698023f Mon Sep 17 00:00:00 2001 From: Koichi ITO Date: Tue, 7 Jul 2026 23:16:08 +0900 Subject: [PATCH] Add VERSIONING.md documenting the versioning and breaking-change policy ## Motivation and Context The SDK tiering system (SEP-1730) requires Tier 1 SDKs to publish a clear versioning policy with a documented breaking-change policy. The CHANGELOG already states that the project adheres to Semantic Versioning, but there was no standalone document describing what counts as a breaking change, how the 0.x phase differs from post-1.0.0, or how incompatibilities are communicated to users. One policy decision is worth calling out: minor releases avoid incompatible changes as much as possible, but fixes for incorrect MCP spec conformance, for security vulnerabilities, and for clear defects (behavior contradicting the documentation, crashes, or data corruption) may ship in a minor release even when they are behavior-breaking. The SDK's primary contract is conformance to the MCP specification, so behavior that deviates from the spec is treated as a bug rather than an API guarantee, and preserving compatibility with a clear defect would mean preserving the defect itself. ## How Has This Been Tested? Documentation-only change; there is no code to exercise. The referenced files (CHANGELOG.md, GitHub Releases) and their formats were verified against the current repository state. ## Breaking Changes None. This adds a new top-level Markdown document and touches no code. --- VERSIONING.md | 56 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 56 insertions(+) create mode 100644 VERSIONING.md diff --git a/VERSIONING.md b/VERSIONING.md new file mode 100644 index 00000000..1b2cd88b --- /dev/null +++ b/VERSIONING.md @@ -0,0 +1,56 @@ +# Versioning Policy + +The MCP Ruby SDK follows [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html). +This document describes what each version component means for users of the `mcp` gem, +what counts as a breaking change, and how breaking changes are communicated. + +## Version Scheme + +Given a version number `MAJOR.MINOR.PATCH`: + +- **MAJOR** is incremented for incompatible changes to the public API. +- **MINOR** is incremented for backwards-compatible new functionality. +- **PATCH** is incremented for backwards-compatible bug fixes. + +### Current 0.x Phase + +While the SDK is at version 0.x, the public API is not yet considered stable. +Following SemVer conventions for initial development, minor releases (0.x -> 0.y) may contain breaking changes. +All breaking changes are recorded in [CHANGELOG.md](CHANGELOG.md). + +### After 1.0.0 + +Once 1.0.0 is released, breaking changes will only ship in major releases, with the exceptions described below. + +## What Counts as a Breaking Change + +A breaking change is any change that requires users to modify their code when upgrading, including: + +- Removing or renaming a public class, module, method, or constant +- Changing a public method's signature in a way that rejects previously valid arguments +- Changing documented behavior that users can reasonably depend on + +New functionality that is purely additive (new classes, new methods, new optional keyword arguments) +is not a breaking change. + +## Exceptions: Spec Compliance, Security, and Clear Defects + +Minor releases avoid incompatible changes as much as possible. However, the SDK's primary contract is +conformance to the [MCP specification](https://modelcontextprotocol.io/specification/). +Behavior that deviates from the specification is treated as a bug, even when users may have come to rely on it. +Therefore, incompatible changes may be shipped in a minor release when they are required to: + +- Fix incorrect conformance to the MCP specification +- Address a security vulnerability +- Fix a clear defect, such as behavior that contradicts the documentation, a crash, + or data corruption, where compatibility would mean preserving the defect + +When such a change ships, the release notes and CHANGELOG entry explicitly call out the incompatibility +and describe how to migrate. + +## How Breaking Changes Are Communicated + +- [CHANGELOG.md](CHANGELOG.md) records every release in [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) format; + breaking changes appear under the "Changed" or "Removed" headings +- [GitHub Releases](https://github.com/modelcontextprotocol/ruby-sdk/releases) mirror the changelog for each release +- Where practical, deprecation warnings are added at least one minor release before removal