From fe496104a1bae16fb35c75eed0e08968f6c6b3ed Mon Sep 17 00:00:00 2001 From: zho Date: Tue, 2 Jun 2026 03:53:49 +0800 Subject: [PATCH] added deprecation-policy.md and updated related documents --- CHANGELOG.md | 4 + README.md | 5 + docs/CONTRIBUTING.md | 8 ++ docs/MIGRATION.md | 2 + docs/README.md | 2 + docs/RELEASING.md | 2 +- docs/deprecation-policy.md | 123 ++++++++++++++++++ .../breaking-change-release-notes.md | 42 ++++++ 8 files changed, 187 insertions(+), 1 deletion(-) create mode 100644 docs/deprecation-policy.md create mode 100644 docs/templates/breaking-change-release-notes.md diff --git a/CHANGELOG.md b/CHANGELOG.md index bbe88af..b26ff32 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,10 @@ Tagged releases are published to npm from GitHub Actions when a **GitHub Release ## [Unreleased] +### Added + +- Formal deprecation policy ([docs/deprecation-policy.md](docs/deprecation-policy.md)) and breaking-change release notes template ([docs/templates/breaking-change-release-notes.md](docs/templates/breaking-change-release-notes.md)). + ## [0.2.0] - 2026-05-29 ### Changed diff --git a/README.md b/README.md index b7bd3d4..47a147e 100644 --- a/README.md +++ b/README.md @@ -13,6 +13,10 @@ A Model Context Protocol (MCP) server that provides semantic search over Pinecon Version **0.2.0** includes breaking MCP and type changes. See [docs/MIGRATION.md](docs/MIGRATION.md) for before/after examples and the [CHANGELOG](CHANGELOG.md#020---2026-05-29) **Changed** section for the full list. +## Release policy + +While the package is **`0.y.z`**, minor releases may include breaking changes ([semver §4](https://semver.org/spec/v2.0.0.html#spec-item-4)) — pin an exact npm version for reproducible MCP and library use. Deprecated APIs stay available for at least **two minor releases** before removal; breaking releases ship with CHANGELOG entries, [MIGRATION.md](docs/MIGRATION.md) steps, and (for publishes) structured GitHub Release notes. Full rules: [docs/deprecation-policy.md](docs/deprecation-policy.md). + ## Documentation | Doc | Description | @@ -22,6 +26,7 @@ Version **0.2.0** includes breaking MCP and type changes. See [docs/MIGRATION.md | [docs/CONFIGURATION.md](docs/CONFIGURATION.md) | Env vars, CLI flags, library config | | [docs/FAQ.md](docs/FAQ.md) | Common questions | | [docs/MIGRATION.md](docs/MIGRATION.md) | Deprecations & breaking changes | +| [docs/deprecation-policy.md](docs/deprecation-policy.md) | Release & deprecation policy | | [docs/CI_CD.md](docs/CI_CD.md) | GitHub Actions, SBOM, Docker, releases | | [docs/RELEASING.md](docs/RELEASING.md) | npm publish via GitHub Releases | | [docs/CONTRIBUTING.md](docs/CONTRIBUTING.md) | How to contribute | diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index fe9863f..2ccbc8f 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -41,6 +41,14 @@ npm ci - Keep changes focused; update `CHANGELOG.md` `[Unreleased]` for user-visible behavior. - Documentation changes should keep [README](../README.md) links; run `npm run docs:link-check` locally if you touch many relative links. +### Deprecations and breaking changes + +Follow [deprecation-policy.md](./deprecation-policy.md). In summary: + +- **Deprecating** an API: add `### Deprecated` in CHANGELOG with a removal target (minimum two minor releases), update [MIGRATION.md](./MIGRATION.md), and use `@deprecated` in types when applicable. +- **Breaking** a release (especially while `0.y.z`): use labeled bullets — `**Breaking (MCP):**`, `**Breaking (types):**`, etc. — each with what changed, who is affected, and a link to a MIGRATION anchor. +- **Removing** deprecated APIs: add `### Removed` only after the deprecation window; keep migration text in MIGRATION.md. + ## Documentation Authoritative reference lives under [`docs/`](./README.md). When adding tools or config knobs, update `docs/TOOLS.md` and `docs/CONFIGURATION.md` in the same PR when possible. diff --git a/docs/MIGRATION.md b/docs/MIGRATION.md index 120f1c0..93de976 100644 --- a/docs/MIGRATION.md +++ b/docs/MIGRATION.md @@ -1,5 +1,7 @@ # Migration guide +Deprecation timelines and maintainer obligations are defined in [deprecation-policy.md](./deprecation-policy.md). + This guide is for **library and MCP client authors** upgrading from earlier **0.1.x** lines. The **[0.2.0]** section of [`CHANGELOG.md`](../CHANGELOG.md) is the authoritative list of changes; this document shows **how** to migrate. Under [semver 0.y.z](https://semver.org/spec/v2.0.0.html#spec-item-4), **0.1.x → 0.2.0 is a breaking minor** — pin `@0.2.0` only after reading this guide. diff --git a/docs/README.md b/docs/README.md index 1e46489..64ff003 100644 --- a/docs/README.md +++ b/docs/README.md @@ -11,6 +11,8 @@ Guides for operators, MCP client authors, and library embedders. | [CI_CD.md](./CI_CD.md) | GitHub Actions, CodeQL, SBOM, Codecov, releases | | [FAQ.md](./FAQ.md) | Common questions | | [MIGRATION.md](./MIGRATION.md) | Breaking changes and upgrade paths | +| [deprecation-policy.md](./deprecation-policy.md) | Deprecation window, semver, CHANGELOG conventions | +| [templates/breaking-change-release-notes.md](./templates/breaking-change-release-notes.md) | GitHub Release body template for breaking versions | | [RELEASING.md](./RELEASING.md) | npm publish via GitHub Releases | The main [README.md](../README.md) remains the high-level overview; deep reference lives here. diff --git a/docs/RELEASING.md b/docs/RELEASING.md index faaec85..c893998 100644 --- a/docs/RELEASING.md +++ b/docs/RELEASING.md @@ -5,7 +5,7 @@ Packages are published to npm as **`@will-cppa/pinecone-read-only-mcp`**. ## Mechanism 1. Merge changes to `main` with an updated [`CHANGELOG.md`](../CHANGELOG.md). -2. Create a **GitHub Release** (publish event) with a version tag aligned with semver. +2. Create a **GitHub Release** (publish event) with a version tag aligned with semver. When the release includes breaking changes, use the body from [templates/breaking-change-release-notes.md](./templates/breaking-change-release-notes.md) and follow [deprecation-policy.md](./deprecation-policy.md). 3. The [Publish workflow](../.github/workflows/publish.yml) runs the full CI suite (`workflow_call` to `ci.yml`), then executes `npm publish --provenance --access public` on Ubuntu with `NODE_AUTH_TOKEN`. ## Requirements diff --git a/docs/deprecation-policy.md b/docs/deprecation-policy.md new file mode 100644 index 0000000..4d2fd22 --- /dev/null +++ b/docs/deprecation-policy.md @@ -0,0 +1,123 @@ +# Deprecation policy + +This document defines how **`@will-cppa/pinecone-read-only-mcp`** deprecates and removes public APIs. It applies to: + +- npm package exports (`@will-cppa/pinecone-read-only-mcp` core and `/alliance`) +- MCP tool input/output schemas and registered tool names +- TypeScript types and functions published from `package.json` `exports` + +For step-by-step upgrades, see [MIGRATION.md](./MIGRATION.md). For publish mechanics, see [RELEASING.md](./RELEASING.md). + +## Semantic versioning while `0.y.z` + +This package currently ships as **`0.y.z`**. Under [Semantic Versioning §4](https://semver.org/spec/v2.0.0.html#spec-item-4), **minor releases may include breaking changes** until the first `1.0.0` release. Consumers should **pin an exact version** (for example `@will-cppa/pinecone-read-only-mcp@0.2.0`) in `package.json`, MCP server config, and Docker tags. + +After **`1.0.0`**, this project intends to follow standard semver: breaking changes land only in **major** releases, and the deprecation window below becomes **binding** for removals that were previously announced as deprecated. + +## Deprecation window + +When we deprecate a public surface (field, type, tool name, export, or behavior): + +| Phase | When | Requirement | +| ----- | ---- | ------------- | +| **Deprecated** | Minor release `0.N.0` (or patch if only docs/warnings) | Listed under `### Deprecated` in [CHANGELOG.md](../CHANGELOG.md) with a **removal target** (minimum next minor + one more minor, i.e. at least **two minor releases** later). | +| **Supported** | Entire window | Replacement API available; [MIGRATION.md](./MIGRATION.md) documents before/after. | +| **Removed** | No earlier than `0.(N+2).0` | Listed under `### Removed`; migration section retained in MIGRATION.md for one further release when practical. | + +**Example:** deprecated in `0.2.x` → earliest removal in `0.4.0`. + +Renames may ship the **replacement immediately** alongside the deprecated alias (for example `document_id` with `paper_number` still present). Consumers should migrate to the replacement during the window. + +### Grandfathered deprecations + +APIs deprecated **before** this policy was published follow the removal target recorded in CHANGELOG and source comments at deprecation time. The `paper_number` field on query result rows (use `document_id` instead) was deprecated in **0.2.0** with removal planned no earlier than the **next major** release after `1.0.0`; it will not be removed in a `0.y` minor without an explicit CHANGELOG entry and MIGRATION update. + +## How we deprecate (maintainer checklist) + +For each deprecated public surface: + +1. **CHANGELOG** — Add under `[Unreleased]` → `### Deprecated` with removal target version and link to MIGRATION. +2. **MIGRATION.md** — Add a section with rationale, before/after examples, and anchor-friendly heading. +3. **Types** — Add JSDoc `@deprecated` on exported TypeScript symbols where applicable. +4. **Runtime (optional)** — For MCP-visible response fields, emit at most **one `WARN` log per process** per deprecation (see existing `paper_number` pattern in `format-query-result.ts`). +5. **Alliance vs core** — State which layer (`core` or `alliance`) owns the surface when only one changes. + +Do **not** remove a deprecated surface without completing items 1–2 and without waiting for the deprecation window (unless semver allows an immediate breaking minor while `0.y.z` — see below). + +## Migration support commitment + +For every deprecated public API we commit to: + +- **Documented migration** in [MIGRATION.md](./MIGRATION.md) for at least the full deprecation window. +- **No silent removal** — removal appears in CHANGELOG `### Removed` and references the MIGRATION anchor. +- **Clear ownership** — note when a change affects only Alliance presets, only core, or both. + +Breaking changes that ship **without** a prior deprecation period (allowed while `0.y.z` for minors, or for security fixes) still require a MIGRATION section and, when user-visible, [breaking-change release notes](./templates/breaking-change-release-notes.md). + +## Breaking changes without prior deprecation + +While **`0.y.z`**, a minor release **may** ship breaking changes without a prior deprecation cycle (as in **0.2.0**). Such releases must still include: + +- CHANGELOG entries using **`Breaking (MCP):`**, **`Breaking (types):`**, **`Breaking (runtime / tooling):`**, or similar categories (see [CHANGELOG format](#changelog-format-for-breaking-changes)). +- [MIGRATION.md](./MIGRATION.md) upgrade steps. +- GitHub Release notes from the [breaking-change template](./templates/breaking-change-release-notes.md) when the release is published. + +Security fixes may break behavior when required; document impact in CHANGELOG and MIGRATION. + +## Future instance APIs (`ServerContext`) + +A planned refactor introduces **`ServerContext`** and **`createServer(config)`** while keeping legacy module-level getters during a transition. That work will: + +- Add new instance APIs without removing legacy getters in the same release. +- Document legacy getters under `### Deprecated` with a named removal target per this policy. +- Link migration steps from [MIGRATION.md](./MIGRATION.md) to this document. + +Until that migration guide is published, treat this section as the policy constraint for that refactor. + +## CHANGELOG format for breaking changes + +This project follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). Each version block should use the sections that apply: `### Added`, `### Changed`, `### Deprecated`, `### Removed`, `### Fixed`. + +### Breaking entries + +Group breaking items under `### Changed` (or a dedicated breaking subsection) using category labels: + +```markdown +### Changed + +- **Breaking (MCP):** … +- **Breaking (types):** … +- **Breaking (runtime / tooling):** … +``` + +Each breaking bullet should state: + +- **What changed** — concrete behavior or schema difference. +- **Who is affected** — MCP clients, library embedders, operators, etc. +- **Migration** — link to [MIGRATION.md](./MIGRATION.md#anchor) (or “see MIGRATION.md § …”). + +### Deprecated entries + +```markdown +### Deprecated + +- `old_name` on … — use `new_name` instead; removal targeted in **0.4.0** (deprecated **0.2.0**). See [MIGRATION.md](./MIGRATION.md#anchor). +``` + +Contributors: see [CONTRIBUTING.md](./CONTRIBUTING.md) for PR expectations. + +## Release hygiene + +- **`package.json` `version`** is the single source of truth for the published npm version. +- **`SERVER_VERSION`** (MCP `serverInfo.version`) is read from `package.json` at runtime and must stay aligned (see [RELEASING.md](./RELEASING.md)). +- Breaking GitHub Releases should use [docs/templates/breaking-change-release-notes.md](./templates/breaking-change-release-notes.md). + +## Related documentation + +| Document | Role | +| -------- | ---- | +| [MIGRATION.md](./MIGRATION.md) | Per-version upgrade how-to | +| [CHANGELOG.md](../CHANGELOG.md) | Authoritative change list | +| [CONTRIBUTING.md](./CONTRIBUTING.md) | PR and CHANGELOG expectations | +| [RELEASING.md](./RELEASING.md) | npm publish via GitHub Releases | +| [templates/breaking-change-release-notes.md](./templates/breaking-change-release-notes.md) | GitHub Release body template | diff --git a/docs/templates/breaking-change-release-notes.md b/docs/templates/breaking-change-release-notes.md new file mode 100644 index 0000000..54de8e1 --- /dev/null +++ b/docs/templates/breaking-change-release-notes.md @@ -0,0 +1,42 @@ +# Breaking-change release notes (template) + +Copy the section below into the **GitHub Release** description when a version includes breaking changes. Replace placeholders in `ALL_CAPS` or angle brackets. + +--- + +## `vX.Y.Z` — Breaking changes + +**Summary:** One or two sentences describing why this release matters and the main upgrade action (for example “MCP tool errors now use `ToolError`; update clients that parsed `{ status: 'error' }`.”). + +### What changed + +| Change | Affected consumers | Action | +| ------ | ------------------ | ------ | +| _Short title_ | MCP clients / library embedders / operators | _Concrete step (pin version, update schema, set env var)_ | +| … | … | … | + +### Upgrade checklist + +- [ ] Pin `@will-cppa/pinecone-read-only-mcp@X.Y.Z` in `package.json`, MCP config, and Docker image tags (avoid floating `latest` until validated). +- [ ] Read [CHANGELOG.md](https://github.com/cppalliance/pinecone-read-only-mcp-typescript/blob/vX.Y.Z/CHANGELOG.md#xyz---YYYY-MM-DD) for the full list. +- [ ] Follow [docs/MIGRATION.md](https://github.com/cppalliance/pinecone-read-only-mcp-typescript/blob/vX.Y.Z/docs/MIGRATION.md) for before/after examples. +- [ ] Review [docs/deprecation-policy.md](https://github.com/cppalliance/pinecone-read-only-mcp-typescript/blob/vX.Y.Z/docs/deprecation-policy.md) for ongoing deprecations. +- [ ] Run your integration tests against the new version. + +### npm + +- Package: `@will-cppa/pinecone-read-only-mcp` +- Version: `X.Y.Z` +- Install: `npm install @will-cppa/pinecone-read-only-mcp@X.Y.Z` + +If you rely on reproducible builds, pin the exact version rather than a range until you have verified compatibility. + +### Links + +- [CHANGELOG — vX.Y.Z](https://github.com/cppalliance/pinecone-read-only-mcp-typescript/releases/tag/vX.Y.Z) +- [MIGRATION.md](https://github.com/cppalliance/pinecone-read-only-mcp-typescript/blob/vX.Y.Z/docs/MIGRATION.md) +- [Deprecation policy](https://github.com/cppalliance/pinecone-read-only-mcp-typescript/blob/vX.Y.Z/docs/deprecation-policy.md) + +--- + +**Maintainers:** delete this heading and the instructions above when publishing; keep only the release body. See [RELEASING.md](../RELEASING.md).