docs: document API deprecation process (closes #75)

[bradjin8]

Summary

• Add docs/API_DEPRECATION.md defining how HTTP API endpoints, CLI flags, and JSON response fields are deprecated and removed
• Cross-link from the README Versioning section to the deprecation policy
• Include docs/ in pyproject.toml sdist so the policy ships with source distributions

Closes #75

Motivation

The project had no documented API deprecation process. Combined with the versioning policy (#74), HTTP API and CLI consumers had no defined warning mechanism when endpoints, parameters, or response shapes change. This addresses the "Invisible Contract" finding from the baseline eval (Test 34 — API Stability Discipline).

What the policy covers

Requirement	Where
Communication (headers, changelog, server logs)	4-step workflow in docs/API_DEPRECATION.md
Deprecation header pattern	Deprecation: true; sunset=<ISO-8601-date> with optional link=
Minimum notice period	One minor version before removal (post-1.0)
Removal documentation	### Removed section in CHANGELOG.md
Pre-1.0 posture	Breaking changes may land without prior deprecation cycle

Documentation only — no runtime Deprecation headers are emitted yet; the policy establishes the process before it is needed.

Test plan

• docs/API_DEPRECATION.md renders correctly on GitHub
• README Versioning section links to docs/API_DEPRECATION.md
• pyproject.toml sdist include list contains docs/
• Policy cross-references CHANGELOG.md and README Versioning consistently

Summary by CodeRabbit

• Documentation

  • Added a Versioning section describing Semantic Versioning expectations, stability guidance for pre-1.0, and how notable changes are recorded.
  • Added an API deprecation policy covering HTTP API, CLI flags, and JSON response fields with deprecation/removal workflow, header formats, and migration guidance.

• Chores

  • Updated packaging so source distributions include project documentation.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 84bdc041-7654-482e-b97b-815984b5d017

📥 Commits

Reviewing files that changed from the base of the PR and between 397a9e2 and 073c79f.

📒 Files selected for processing (2)

• README.md
• docs/API_DEPRECATION.md

✅ Files skipped from review due to trivial changes (1)

• README.md

---

📝 Walkthrough

Walkthrough

Adds documentation: docs/API_DEPRECATION.md (API deprecation policy), a README “Versioning” section, and updates packaging (pyproject.toml) to include docs/ in the sdist.

Changes

API Deprecation and Versioning Policy

Layer / File(s)	Summary
API Deprecation Policy Definition docs/API_DEPRECATION.md	New document specifies pre-1.0 breaking-change expectations, post-1.0 deprecation workflows (CHANGELOG entries under ### Deprecated, optional CLI help notes, HTTP Deprecation/Sunset/Link header patterns, server logging.warning()), header formats and migration-link semantics, covered surfaces (HTTP endpoints/params, JSON response fields, CLI flags), and removal documentation requirements under ### Removed in CHANGELOG.md.
Versioning documentation and distribution README.md, pyproject.toml	README.md gains a Versioning section describing SemVer and pre-1.0 expectations and links to CHANGELOG.md and docs/API_DEPRECATION.md; pyproject.toml adds docs/ to the sdist include list so docs ship in source distributions.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Possibly related PRs

• cppalliance/cppa-cursor-browser#49: Both PRs update pyproject.toml build configuration, specifically the source distribution (sdist) include file lists.

Suggested reviewers

• timon0305
• wpak-ai

Poem

🐰 A deprecation dance so neat and bright,
Headers warn before the sunset light,
Docs now ship with every release,
Version notes tidy every piece,
~Hazel the Rabbit 🥕

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and accurately summarizes the main change: documentation of the API deprecation process, directly addressing the linked issue #75.
Linked Issues check	✅ Passed	All acceptance criteria are met: deprecation policy is documented in docs/API_DEPRECATION.md and README; the policy specifies communication methods, deprecation notice period (one minor version post-1.0), and removal documentation; a Deprecation header pattern is defined; pre-1.0 expectations are acknowledged.
Out of Scope Changes check	✅ Passed	All changes are scope-aligned: README versioning section cross-links to deprecation policy; docs/API_DEPRECATION.md documents the full policy; pyproject.toml includes docs/ in sdist to ship the policy. No unrelated changes detected.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch doc/api-deprecation-policy

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/API_DEPRECATION.md`:
- Line 16: Update the example in the "Removal" rule to match the stated "one
minor version" minimum notice: replace the current example pairing `1.2.0` →
`1.4.0` with `1.2.0` → `1.3.0` (or alternatively change the rule text if you
meant two minors); the change should be applied to the sentence beginning
"Removal — Remove no earlier than one minor version after the deprecation was
announced" so the example and rule are consistent.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: ccc3f32d-4ccd-4377-b86a-8221ac2e86a4

📥 Commits

Reviewing files that changed from the base of the PR and between 46bda64 and d6e7bb1.

📒 Files selected for processing (3)

• README.md
• docs/API_DEPRECATION.md
• pyproject.toml

[coderabbitai]

Actionable comments posted: 0

[clean6378-max-it]

Should fix

README.md:263 — Soften or defer the CHANGELOG claim until CHANGELOG.md exists on this branch
(“A complete history of changes is maintained in CHANGELOG.md” reads as if the file and history already exist; CHANGELOG.md is absent on master and on this branch, though it appears on origin/doc/changelog-versioningpolicy. Until that lands, use wording like “will be documented in CHANGELOG.md” or add a minimal stub so links are not dead on merge.)

Nice to have

README.md:243 — Note merge coordination with the changelog/versioning PR
(The new Versioning section overlaps issue #9 / doc/changelog-versioningpolicy; a one-line PR description cross-link avoids reviewers treating it as scope creep for #76.)

docs/API_DEPRECATION.md:15 — Add a one-line pointer to a future shared helper for Deprecation headers
(Optional: “implement via a small Flask helper when first endpoint is deprecated” — keeps policy and code aligned without implementing now.)

[clean6378-max-it]

@CodeRabbit. pleease review this PR in more depth except my 3 comments

[coderabbitai]

Tip

For best results, initiate chat on the files or code changes.

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
echo "=== docs/API_DEPRECATION.md ==="
cat docs/API_DEPRECATION.md

echo ""
echo "=== README.md (lines 230-280) ==="
sed -n '230,280p' README.md

echo ""
echo "=== pyproject.toml ==="
cat pyproject.toml

echo ""
echo "=== Git diff for this PR (stat) ==="
git diff origin/master...HEAD --stat

echo ""
echo "=== Full diff ==="
git diff origin/master...HEAD

Length of output: 12864

---

---

@clean6378-max-it Here is a deeper review of PR #86, excluding the three points you already raised.

---

docs/API_DEPRECATION.md

🔴 Should Fix — Non-standard Deprecation header format

Line 23:

Deprecation: true; sunset=2026-09-01

This format does not align with either active standard:

• IETF draft-ietf-httpapi-deprecation-header specifies Deprecation as an HTTP date (when deprecation became effective), not the string true.
• RFC 8594 defines Sunset as a separate header, not a parameter inside Deprecation.

The spec-compliant form would be:

Deprecation: Tue, 01 Sep 2026 00:00:00 GMT
Sunset: Tue, 01 Sep 2026 00:00:00 GMT
Link: <https://...>; rel="sunset"

If the project intentionally uses a simplified custom format (acceptable for pre-1.0), that should be stated explicitly to avoid misleading future implementers who may try to use standard HTTP client libraries that parse these headers.

---

🔴 Should Fix — link= placement is ambiguous

Line 27:

Optionally add link="<url>" pointing to the changelog entry or migration notes.

It's not specified whether link= is:

• appended to the Deprecation header value (e.g. Deprecation: true; sunset=...; link="...")
• or emitted as a separate Link header (the standard approach: Link: <url>; rel="deprecation")

An example line showing the full multi-header block (as you might emit from Flask) would resolve this.

---

🟡 Should Fix — CLI (deprecated) annotation missing from numbered workflow

The numbered deprecation workflow (steps 1–4) covers CHANGELOG, response headers, server log, and removal — but the CLI (deprecated) in --help annotation only appears in the Surfaces table, not in the workflow steps. Readers following the checklist for a CLI flag deprecation would miss it. Suggest adding it explicitly:

Step 1b (CLI): Add (deprecated, use <replacement>) to the flag's help string.

---

🟡 Should Fix — Pre-1.0 ambiguity: do steps 2 & 3 apply?

The Pre-1.0 section (line 7) says:

Deprecations are still recorded in the changelog when practicable

But it's unclear whether steps 2 (response Deprecation header) and 3 (server log warning) of the workflow also apply pre-1.0. If they don't, a developer following the workflow for a 0.x.y deprecation won't know to skip or include those steps. A single sentence would fix this:

Pre-1.0, steps 2 and 3 (response headers and server logs) are encouraged but optional.

---

🟡 Nice to Have — JSON response field has no in-band signal

The surfaces table acknowledges that a deprecated JSON field only gets a changelog entry (no header, no log). This means API consumers have no way to detect the deprecation programmatically. Consider noting a forward-looking approach, e.g.:

Future consideration: a X-Deprecated-Fields: fieldName response header or an _deprecated annotation inside the JSON envelope.

---

README.md

🟡 Should Fix — "Python package" breaking-change surface may be misleading

Line 261 (breaking-change table):
| Python package | Removing a public symbol from an importable module |

This project is described as a Flask web application and CLI tool, not an importable library. Including "Python package" as a breaking-change surface implies a stable public Python API that external code can import — which doesn't appear to be the intent. If this is not a supported surface, remove the row. If it is intended (e.g. scripts.export), add a note clarifying which modules are considered public.

---

🟡 Nice to Have — Security-fix carve-out not addressed

The pre-1.0 stability section promises patch bumps are "backward-compatible bug fixes only." It's worth noting whether security fixes (e.g. a CVE forcing a breaking API change) are exempt, since many projects reserve the right to break compatibility for security. A one-liner such as:

Exception: critical security fixes may break compatibility at any version with appropriate changelog notation.

would prevent future ambiguity.

---

pyproject.toml

✅ The docs/ addition to sdist only (not wheel) is correct — documentation is source-distribution material, not runtime. No issues found.

---

Summary table

#	File	Severity	Topic
1	docs/API_DEPRECATION.md L23	🔴 Should Fix	Non-standard Deprecation header format
2	docs/API_DEPRECATION.md L27	🔴 Should Fix	link= placement ambiguous
3	docs/API_DEPRECATION.md step list	🟡 Should Fix	CLI --help annotation not in numbered steps
4	docs/API_DEPRECATION.md L7	🟡 Should Fix	Pre-1.0 ambiguity for steps 2 & 3
5	docs/API_DEPRECATION.md table	🟡 Nice to Have	JSON field: no in-band deprecation signal
6	README.md L261	🟡 Should Fix	"Python package" surface may not apply
7	README.md pre-1.0 section	🟡 Nice to Have	Security-fix carve-out missing
8	pyproject.toml	✅ No issue	docs/ in sdist only — correct

（ ˘ ⌣ ˘ )੭ु⁾⁾ 🐇

[coderabbitai]

Actionable comments posted: 0