added deprecation-policy.md and updated related documents (#122)

jonathanMLDev · zho · web-flow · commit b166af8e5ae3 · 2026-06-02T13:07:10.000-04:00
Co-authored-by: zho &lt;jornathanm910923@gmail.com&gt;
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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).
