Skip to content

Publish versioning, roadmap, and dependency policies for v2 - #3215

Open
maxisbey wants to merge 1 commit into
mainfrom
docs/tier1-governance-files
Open

Publish versioning, roadmap, and dependency policies for v2#3215
maxisbey wants to merge 1 commit into
mainfrom
docs/tier1-governance-files

Publish versioning, roadmap, and dependency policies for v2

e90d907
Select commit
Loading
Failed to load commit list.
Claude / Claude Code Review completed Jul 29, 2026 in 28m 20s

Code review found 3 potential issues

Found 5 candidates, confirmed 3. See review comments for details.

Details

Severity Count
🔴 Important 0
🟡 Nit 3
🟣 Pre-existing 0
Severity File:Line Issue
🟡 Nit DEPENDENCY_POLICY.md:18 Policy docs disagree on cross-major dependency floor raises
🟡 Nit RELEASE.md:5-6 Canonized dependency-bump recipe tells maintainers to rewrite uv.lock to floors
🟡 Nit docs/versioning.md:13 versioning.md understates when installers select pre-releases

Annotations

Check warning on line 18 in DEPENDENCY_POLICY.md

See this annotation in the file changed.

@claude claude / Claude Code Review

Policy docs disagree on cross-major dependency floor raises

The two new policy docs answer the same question differently: DEPENDENCY_POLICY.md scopes the minor-release permission to floor raises "within the same major version of a dependency", while docs/versioning.md's non-breaking list allows any minimum-version raise (no cross-major carve-out) — and each page defers to the other as the authority. Either drop the qualifier here or add the cross-major case explicitly to versioning.md's breaking-change list, so a reader can tell whether e.g. moving to py

Check warning on line 6 in RELEASE.md

See this annotation in the file changed.

@claude claude / Claude Code Review

Canonized dependency-bump recipe tells maintainers to rewrite uv.lock to floors

The new sentence promotes this recipe into the published dependency-policy chain, but step 2 (`uv lock --resolution lowest-direct`) would rewrite the committed `uv.lock` down to floor versions — the committed lock is a normal/highest resolution refreshed by Dependabot, exactly as this PR's own DEPENDENCY_POLICY.md "Automated updates" section describes, and lowest-direct belongs only to the CI leg that never touches the lock. The wrong command pre-dates this PR, but since this PR canonizes the re

Check warning on line 13 in docs/versioning.md

See this annotation in the file changed.

@claude claude / Claude Code Review

versioning.md understates when installers select pre-releases

The pre-release bullet says installers select a pre-release only "by exact pin or `--pre`", but PEP 440 (as implemented by pip and uv) has a third opt-in route: any specifier that names a pre-release version (e.g. `mcp>=2.1.0b1`) enables pre-release selection for that requirement, so a later resolve can pick a newer alpha over the newest stable. Suggest mirroring RELEASE.md's complete wording — "an exact pin, a specifier that names a pre-release version, or `--pre`" — so the categorical "never"