Skip to content

docs(versioning): add schema-publication-at-merge policy#3391

Merged
bokelley merged 1 commit into
mainfrom
claude/issue-2366-schema-publication-at-merge
Apr 28, 2026
Merged

docs(versioning): add schema-publication-at-merge policy#3391
bokelley merged 1 commit into
mainfrom
claude/issue-2366-schema-publication-at-merge

Conversation

@bokelley

Copy link
Copy Markdown
Contributor

Closes #2366

Adds a ### Schema publication at merge subsection to docs/reference/versioning.mdx, placed immediately after the existing ### Breaking-change notice section. The section codifies the invariant: the latest published tag and source HEAD must always reflect the same required-field set, and any PR that changes a required array, a discriminator const, or tightens a validation constraint must be accompanied by a new tag cut before the change propagates to evaluators.

The root case (source↔published drift from PR #2315 on the rc.3 tag) is resolved by the 3.0 GA tag. This doc addition is the durable Evergreen fix: it names the invariant, explains why the drift matters for pinned-tag and alias-resolving implementors alike, covers RC cycles explicitly, and describes manual responsibility until a CI check enforces the rule.

Non-breaking justification: adds a new subsection to an existing docs page; no schema changes, no wire changes, no API surface affected.

Pre-PR review:

  • code-reviewer: approved — no blockers; nits on wording and changeset style noted, addressed in revision (reviewer trigger condition changed from commit-prefix to actual schema-change categories; "staged or already cut" → "ready to publish"; redundant RC-cycle sentence removed)
  • docs-expert: two blockers on initial draft: (1) conflict with the 3.x stability table's deprecation-first rule for optional→required; (2) "Why" block incorrectly scoped to alias users only. Both fixed: added "in addition to any upstream obligations" clause; broadened "Why" to cover pinned-tag implementors; added cross-link to /docs/building/schemas-and-sdks#schema-versioning.

Triage-managed PR. This bot does not currently iterate on
review comments or PR conversation threads (only on the source
issue). To unblock:

  • Push fixup commits directly: gh pr checkout <num>
    fix → push.
  • Or re-trigger: comment /triage execute on the source
    issue.

See #3121
for context.

Session: https://claude.ai/code/session_01PKwE7MvNkQjTBaWssihqjj


Generated by Claude Code

@bokelley bokelley added the claude-triaged Issue has been triaged by the Claude Code triage routine. Remove to re-triage. label Apr 28, 2026
@bokelley bokelley marked this pull request as ready for review April 28, 2026 15:11
@bokelley bokelley merged commit ff05dee into main Apr 28, 2026
18 checks passed
@bokelley bokelley deleted the claude/issue-2366-schema-publication-at-merge branch April 28, 2026 15:11
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

claude-triaged Issue has been triaged by the Claude Code triage routine. Remove to re-triage.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Release policy: tag-at-merge for breaking schema changes to prevent source↔published drift

2 participants