QEP-1 v3: stamp version and version-hash from v0; one-week window - #23
Open
mmcky wants to merge 1 commit into
Open
QEP-1 v3: stamp version and version-hash from v0; one-week window#23mmcky wants to merge 1 commit into
mmcky wants to merge 1 commit into
Conversation
Contributor
There was a problem hiding this comment.
Pull request overview
This PR amends QEP-1 from v2 → v3 to redefine QEP versioning so that merged QEPs are intended to be stamped/anchored from v0 (rather than treating v0 as “absent version”), and updates the README index entry for QEP-1 accordingly.
Changes:
- Bump QEP-1 to version 3 and update the in-document header table to match.
- Update QEP-1 prose for Versioning, History and publication, Automation, Format, add an Alternatives entry, and add an adoption entry describing the v0-stamping change.
- Update the README index row for QEP-1 from v2 → v3.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
| README.md | Updates the QEP-1 index row version to v3. |
| qeps/qep-0001-purpose-and-process.md | Updates QEP-1 to v3 and revises the normative text to specify stamping/anchoring behavior from v0. |
Suppressed comments (1)
README.md:21
- The README index note below still says
Versionstays–until a QEP is first amended, which conflicts with the updated QEP-1 v3 semantics described in this PR (v0 is intended to be stamped/anchored as well). Since this PR already touches the README index, please update the explanatory text to avoid misleading readers about what–means.
| [QEP-1](qeps/qep-0001-purpose-and-process.md) | QEP Purpose and Process | process | Accepted | v3 |
| [QEP-2](qeps/qep-0002-standard-github-labels.md) | Standard GitHub Label Set and Labelling Policy | standard | Accepted | – |
QEPs that set an ongoing rule are **maintained in place**: a substantive amendment bumps
the QEP's `version` (shown above) under the same review process, rather than superseding
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Comment on lines
+206
to
+208
| - the **README index** carries `Type` and `Version` columns, with `Version` showing | ||
| `v{N}` from `v0` up (`–` only while a Draft's PR is open) — repo-controlled, so it | ||
| renders on any theme; |
Comment on lines
+162
to
+166
| Both fields are machine-written at birth: a Draft carries neither, and the post-merge | ||
| step (see *Automation*) stamps `version: 0` and the hash when the QEP first merges — a | ||
| commit cannot contain its own hash, so neither field is ever hand-written to start. | ||
| From then on the author bumps `version` on substantive amendments, and CI re-stamps the | ||
| hash on every merged change, editorial included. The stamp is uniform across merged |
Comment on lines
215
to
+219
| Two mechanical steps are enforced by CI rather than left to memory: | ||
|
|
||
| - a **post-merge action** (`.github/workflows/stamp-version.yml`) reads the merged short | ||
| hash, writes it into the `version-hash` field, and keeps the README `Type`/`Version` | ||
| columns in sync with each QEP's frontmatter; | ||
| hash, stamps `version: 0` alongside it into any newly merged QEP that carries no | ||
| `version`, writes the hash into every changed QEP's `version-hash` field, and keeps |
Every merged QEP carries version and version-hash from the moment it lands: the post-merge stamp writes version: 0 and the hash at first merge, uniformly across Accepted, Rejected and Withdrawn outcomes, and the hash moves on every later change, editorial included. Replaces the implicit v0 (absent version, anchored only from v1), which pushed an absent-means-v0 special case into every consumer and left QEP-2's machine-readable appendix with no recorded revision to cite (#22). Also shortens the default comment window from one-to-two weeks to one week (small team; the author may extend it for a larger change), states plainly that version-hash is a historical anchor rather than a file checksum, and records the dropped implicit-v0 design under Alternatives. Supporting machinery changes (stamp action, checks, backfill, README note, AGENTS.md) follow after acceptance per adoption entry v3. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
mmcky
force-pushed
the
qep-1-v3-stamp-from-v0
branch
from
August 27, 2026 03:31
1b6441b to
17be61c
Compare
mmcky
changed the title
Contributor
Author
|
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.
Substantive amendment: QEP-1 v2 → v3. Discussion: #22.
Two rule changes in this round:
1. Stamp from v0. Every merged QEP carries
versionandversion-hashfrom the moment it lands. A Draft carries neither field; the post-merge stamp writesversion: 0and the hash at first merge, uniformly across Accepted, Rejected and Withdrawn outcomes, and the hash continues to move on every later merged change, editorial included — so a consumer of a machine-readable appendix sees that something changed without diffing git. The amendment also states plainly thatversion-hashis a historical anchor, not a file checksum: the stamp commit post-dates the hash it writes, so the field names a revision rather than hashing the file's bytes.2. Default comment window: one week. Previously "normally one to two weeks"; the team is small enough that a fortnight is drift, not diligence. The author may still extend the window for a larger or more contested change.
Why the stamping change. The v1–v2 design made v0 implicit (absent
version, anchored only from v1). That pushed an absent-means-v0 special case into every consumer, and it left the machine-readable appendix of an accepted-but-unamended standard with no recorded revision at all — QEP-2's appendix section describedversion-hashpinning that does not exist at v0, an asymmetry surfaced by the planning pass on QuantEcon/cli#20. The dropped design is recorded under Alternatives considered with the trade-off: uniform stamping costs a pill and a bot commit; the implicit v0 cost correctness.What this PR contains. QEP-1 text only — the How a QEP is decided, Versioning, History and publication, Automation and Format sections, a new Alternatives entry, adoption entry (v3) — plus QEP-1's own README index row (v2 → v3) and the README's one-line echo of the comment window. Per convention,
version-hashis removed for CI to re-stamp at merge.What follows after acceptance (listed in adoption entry v3, deliberately not in this PR): the stamp action adds
version: 0where missing; already-merged v0 QEPs are backfilled, each stamped with the most recent commit that touched it; the pull-request check's new-QEP rule becomes "unversioned in the PR, v0 at merge"; the README index note and the theme's version pill showv0rather than–;AGENTS.mdfollows. Until that lands, CI still implements the v2 rules — this PR passes them (check.mjsrun locally against this branch).Comment window: one week, applying the new default to its own amendment — decision deadline 2026-09-03.
🤖 Generated with Claude Code