docs: add versions & compatibility overview page#3258
Code review found 3 important issues
Found 6 candidates, confirmed 4. See review comments for details.
Details
| Severity | Count |
|---|---|
| 🔴 Important | 3 |
| 🟡 Nit | 1 |
| 🟣 Pre-existing | 0 |
| Severity | File:Line | Issue |
|---|---|---|
| 🔴 Important | content/docs/compatibility.mdx:96 |
Trace-level evals labeled 'Deprecated' contradicts FAQ commitment |
| 🔴 Important | content/docs/compatibility.mdx:78 |
MCP endpoint marked 'v4 only' contradicts existing mcp-server docs |
| 🔴 Important | content/docs/compatibility.mdx:66-81 |
v4 self-hosted opt-in contradictions and undocumented env var |
| 🟡 Nit | content/docs/observability/sdk/overview.mdx:40-44 |
Self-hosted requirements callout still names Python v3 / JS v4 as current |
Annotations
Check failure on line 96 in content/docs/compatibility.mdx
claude / Claude Code Review
Trace-level evals labeled 'Deprecated' contradicts FAQ commitment
The 'Deprecated' column on line 96 lists trace-level evaluations, but content/faq/all/llm-as-a-judge-migration.mdx line 24 explicitly promises 'Trace-level evaluators will continue to work. This is an upgrade path, not a deprecation.' The compatibility page's own definition on line 92 says deprecated versions 'will be removed' — directly contradicting that promise. Fix by relabeling the column to 'Legacy' / 'Superseded' (matching the FAQ language), or update the FAQ with product sign-off if this
Check failure on line 78 in content/docs/compatibility.mdx
claude / Claude Code Review
MCP endpoint marked 'v4 only' contradicts existing mcp-server docs
The compatibility table marks `/api/public/mcp` as "v4 (Fast Preview) only" (line 78), but [`mcp-server.mdx`](content/docs/api-and-data-platform/features/mcp-server.mdx) already documents this endpoint as generally available today on Cloud EU/US/Japan/HIPAA and Self-Hosted — no v4 or preview qualifier. Readers of this new canonical reference page will be misled into thinking MCP is unavailable outside the v4 preview. Please reconcile the two pages (e.g. mark MCP as GA for prompt management/exist
Check failure on line 81 in content/docs/compatibility.mdx
claude / Claude Code Review
v4 self-hosted opt-in contradictions and undocumented env var
The new compatibility page contradicts itself and other docs about v4 self-hosted availability. The Read APIs table (lines 68, 71) and bullet at line 80 tell self-hosted operators they can enable v2 Observations/Metrics via a preview opt-in and env var `LANGFUSE_MIGRATION_V4_ALLOW_PREVIEW_OPT_IN`, but the Server versions row (line 49) marks v4 as "Cloud-only preview" and the bullet at line 81 tells them to "use the legacy observations and metrics resources until their v2 APIs are GA there". The
Check warning on line 44 in content/docs/observability/sdk/overview.mdx
claude / Claude Code Review
Self-hosted requirements callout still names Python v3 / JS v4 as current
The self-hosting requirements callout still names Python SDK v3 and TypeScript SDK v4 as if current, but the top of this same file (lines 17–18) and the new /docs/compatibility page identify Python v4 / JS-TS v5 as current. The numeric minimums (≥ 3.125.0 and ≥ 3.95.0) happen to match v4/v5 too, so the copy is out of date rather than wrong — but since this PR now cross-links this callout to a page that visibly lists v4/v5, a one-line update to say "Python SDK v4" / "JS-TS SDK v5" (or drop the ve