docs: add auth-scope release labeling policy#8
Merged
Conversation
Adds docs/release-policy.md establishing that past version numbers are facts and future version numbers are predictions; the two must be treated differently in code, CHANGELOG, JSDoc, error messages, and PR titles. The policy is canonical for the 4 OSS repos in the auth scope (auth.utils / auth.provider / auth.policy-verifier / auth.proxy) and is mirrored to each repo's docs/ directory so contributors see it as part of repo-local documentation. Established in response to a documented drift incident where the "1.0 GA" planning anchor became internally contradictory and silently dropped originally-committed features. See the policy doc for full rationale and the six concrete rules (R1-R6) covering past-only references, CHANGELOG Unreleased convention, JSDoc since-only, PR titles, validation error metadata, and release-cut audit pass. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
There was a problem hiding this comment.
Pull request overview
Adds a new documentation page codifying an “auth-scope” release labeling policy intended to prevent forward-version drift across the auth.* OSS repos.
Changes:
- Introduces
docs/release-policy.mddescribing rules R1–R6 for referencing versions in code/docs/CHANGELOG/error strings and for release-cut auditing. - Documents the retirement of the “1.0 GA” planning label and prescribes how to avoid future forward-version promises.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Resolves Copilot review threads on PR #8: 1. Canonical policy doc revised (mirrors fixes applied in sibling PRs): - Scope-aware narrative — no longer states v0.5.x/v0.6.0 history as fact about "this project"; auth.provider's drift is named explicitly, the other 3 repos adopt going forward - R5 examples no longer pre-stamp a concrete version (v0.6.0); use vX.Y.Z placeholder + "this release" / "(Phase G / M4)" neutral wording, since the policy itself must not encode forward-version promises - R2 explicitly forbids hybrid `## [X.Y.Z] — Unreleased` headers alongside the bare-version pre-stamps - R3 example references CHANGELOG (always present) instead of MIGRATION.md (which is not guaranteed to exist in every repo) - Table row generalized from `.claude/` to "internal planning artifacts" — `.claude/` is agent-scope convention, not OSS-repo content - R2 tag-creation wording fixed: a commit doesn't create a tag; the tag is created to point at the commit (clarified as separate but atomic release-cut step) 2. CHANGELOG.md `## [0.0.4] — Unreleased` → `## [Unreleased]` (R2): The hybrid pre-stamp header is exactly the kind of forward-version reference R2 prohibits. Restoring the canonical Keep-a-Changelog `## [Unreleased]` heading. The 0.0.4 label will be applied at the release-cut PR per R6 step 2. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
docs/release-policy.mdestablishing the auth-scope release labeling policyauth.utils/auth.provider/auth.policy-verifier/auth.proxy)auth.utilsadoption PR; sibling PRs follow in the other 3 reposauth.utilshad zero forward-version drift to clean upContext
A documented drift incident showed that anchoring multi-release planning on future version labels (specifically "1.0 GA") led to:
auth.providerschema referencing "1.0 GA" — already shipping in v0.5.3The policy codifies six rules (R1-R6) to prevent recurrence:
## [Unreleased]until cut — no pre-stamping@deprecatedsays "since" only — removal timing lives in CHANGELOG, not in JSDocWhy this PR per repo
Adopting the policy in each repo's
docs/makes it visible to contributors during local development; folding it intoAGENTS.mdwould mix labeling convention with dev guidelines and risk it getting overlooked.Test plan