QEP-1 v3: stamp from v0; drop the decision deadline; generate the index - #23
Conversation
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.
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>
1b6441b to
17be61c
Compare
mmcky
changed the title
|
QEP-3 sits on main with Status: Draft — field-tested in place, per #14 — carrying neither `version` nor `version-hash`. That falsified two claims in the v3 draft on their own terms, not merely ahead of the automation: - "stamps `version: 0` and the hash when the QEP first merges" would, read literally, stamp QEP-3 today, contradicting the same paragraph's "a Draft carries neither" and the outcome list two sentences later, which names Accepted, Rejected and Withdrawn and pointedly omits Draft; - "`–` only while a Draft's PR is open" would stay wrong after the backfill lands, since QEP-3's PR is merged and its README row is still `–`. Tie the stamp to the merge that records the QEP's outcome instead. The rule then covers a merged Draft with no exception clause, and needs no revisiting when the stamping automation follows. The same wording lands in Automation, Format, the surfacing bullets, and the Adoption item's backfill scope. Raised by Copilot's review of #23, which read all three as automation lag. The normative prose is deliberately unhedged — Adoption item 4 carries the transition — but the merged-Draft case was a real defect underneath it. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The one-week window half of this amendment is superseded — ruled 2026-09-08Ruled by @mmcky in a decision session on 2026-09-08 (recorded on #26): the decision deadline and the comment window are struck from QEP-1 entirely, rather than shortened or enforced. QEP-1 step 3 (announce and record a decision deadline) goes, and step 4 is respecified so lazy consensus has a trigger again without a clock:
What that means for this PR. Change 2 — "Default comment window: one week", replacing "normally one to two weeks" — is moot: there is no window left to shorten. Its reasoning still holds and is in fact the ruling's own premise ("the team is small enough that a fortnight is drift, not diligence"), taken further than this PR proposed. Change 1 — stamp Suggested disposition: drop the window change from this PR and land it as a v3 that does the stamping only, then let the deadline removal land as v4. Two smaller amendments rather than one that contains a clause the next one deletes. The alternative — folding the removal into this PR as a single v3 — is also coherent, but it would mean this PR's own description arguing for a window it then abolishes. One observation for the record, since it is part of why the ruling went the way it did. This PR recorded a decision deadline of 2026-09-03 and is still open on 2026-09-08. It is not alone: of the four open QEP PRs, #8 never set a deadline (open since 2026-07-23), #13's passed on 2026-08-28, this one's passed on 2026-09-03, and #18's is deliberately deferred. None was decidable, and Generated by Claude Code |
…tream amendments Folds three ruled changes into this amendment and drops one it originally proposed, so v3 lands as one coherent round instead of a v3 that a v4 would immediately partly delete. Ruled 2026-09-08; discussion on #26, #9 and #22. DROPPED FROM THIS AMENDMENT: the one-week default comment window. The ruling went further than shortening it. THE DECISION DEADLINE GOES. Step 3 of "How a QEP is decided" is struck and the acceptance trigger becomes "no objection is outstanding" rather than a date — lazy consensus with no clock, so a QEP nobody objects to still lands without needing the lead, and nothing is accepted by the mere passage of time. Roles, the Summary's "clear deadline" promise, and the README's Proposing steps all follow. The evidence is recorded under Alternatives considered: on 2026-09-08 none of the four open QEP pull requests had a live deadline — #8 had never set one in 47 days, #13's and #23's had passed, #18's was deliberately deferred — while nothing in CI ever read a PR description. The field was required by this document and checked by nothing. Enforcing it in CI was considered and declined: it would have turned three open PRs red for a rule they predated. THE README INDEX IS GENERATED, post-merge from frontmatter and ordered by number, so a PR carries no row of its own and two QEP PRs cannot collide on one line of one table. The mechanism shipped ahead of this amendment in #30, together with the ordered-list check; Automation now names both, and a stale index is a warning rather than a failure. Numbering states what already happened informally: a number is reserved when its draft PR opens, released if that PR closes unmerged, so index gaps are normal while drafts are open. A DOWNSTREAM QEP CARRIES ITS UPSTREAM AMENDMENTS — #9's sentence, widened by the case it did not anticipate. Where the superseded standard is not itself a QEP, the Adoption section must name the contract, the obligation and a date by which the handover completes: QEP-6 asserts precedence over an external tracker contract with no date on it, and the qe skills depend on that sentence at runtime. Closes #9. Also brings the branch up to date with main, which had moved on by QEP-3's merge (this branch predated it, so it carried neither the file nor its index row). Verified green under both the pre-#30 checks on this branch and #30's new ones, including the ordered-list rule over the rewritten Adoption entry. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Hwm5shrGXmaq4r3Lp9kS33
quantecon-services
changed the title
Rescoped and pushed — and this supersedes my own suggestion aboveCorrecting the previous comment: it suggested landing this as "a v3 that does the stamping only, then let the deadline removal land as v4." @mmcky ruled the other way — fold everything into one v3 — on the grounds that two amendments where the second deletes half of the first is worse to read than one coherent round. That is what Withdrawn from this PR: the one-week default comment window. Its rationale survives as the premise of the removal rather than as a change of its own. Added: the deadline removal with step 3 struck and the acceptance trigger respecified ( Also: The description is rewritten to match. Verified green under both this branch's pre-#30 checks and #30's new ones, including the ordered-list rule over the rewritten Adoption entry. Suggested landing order is #30 → #29 → this, for the reasons in the description. Generated by Claude Code |
…ver names the item that discharges it Two amendments to the v3 text before it lands, both from the adversarial review of the 2026-09-08 rulings. Step 3 said any Core Maintainer may accept a QEP, which let an author accept their own — and the first Accepted-status PR after the rule was drafted would have been exactly that. Acceptance is now an approving review from a Core Maintainer other than the author, still by lazy consensus and still without a clock: one other reader is the whole check, and it is the external check the deadline never supplied. Roles, step 4, the Alternatives entry, Adoption entry 4 and the README follow. The rule for a QEP that supersedes an external contract asked its Adoption section for "a date by which the handover completes". A date is the thing this same amendment has just removed from the decision process for describing what the team does not do; what a handover needs is an owner and a state, which is a tracking issue in the contract's own repository. The Adoption section now names the item that discharges the obligation. QEP-6 applies this first, naming QuantEcon/status-projects#114. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Hwm5shrGXmaq4r3Lp9kS33
|
Removes the "A QEP that touches another standard carries the amendment itself" paragraph and its Adoption entry. QEPs are the source of truth and are independent of every repository: a downstream consumer adapts to a QEP, and the QEP owes it nothing in return. Under that model the external half of the rule has no subject — the status-projects tracker contract is a consumer that must conform, not a peer standard being superseded — so a QEP has no cause to assert precedence over it or to name a tracking issue in another repository. Naming one would also make the Adoption section a status pointer into a repo this one does not own. The intra-repo half (carry the upstream edit in the downstream QEP's own PR; do not forward-reference a draft from an accepted standard) stays practice rather than QEP-1 text. #9 stays open recording that, and the explanation is on the issue. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
QEPs are the source of truth and are independent of every repository: a downstream consumer adapts to a QEP, and the QEP owes it nothing back. The dashboard's tracker contract is a consumer that must conform, not a peer standard this QEP supersedes — so Adoption item 4 no longer asserts precedence over it, no longer prescribes its handover, and no longer names a tracking issue in another repository. How each consumer reaches conformance, and when, is that consumer's own business. Also drops the citation of QEP-1's cross-standard amendment rule, which was withdrawn from the v3 amendment in #23; the reasoning is recorded on #9. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Records the cross-QEP amendment convention in `AGENTS.md` as author-side practice, rather than folding it into QEP-1 as #23 originally proposed. Ruled 2026-09-09; the reasoning is on #9, which this retires. ## Why here and not in QEP-1 QEP-1 already says amend in place and bump `version` — "put the edit in the PR that needs it" is the mechanical consequence, not a separate rule. It is author-side judgement of exactly the kind QEP-1's *Automation* section already delegates to `AGENTS.md`, alongside substantive-vs-editorial and the commit subject. And `AGENTS.md` is the document an author actually reads before drafting a QEP, which is where the convention needs to be to change anything. The second-instance rule that #9 was waiting on never fired, either: QEP-2 ↔ QEP-4 is intra-repo and QEP-6 ↔ status-projects is cross-repo — two problems with one instance each, not two instances of one problem. ## Three paragraphs The first is the original convention from #9: don't forward-reference a draft from an accepted QEP, and put the upstream edits in the downstream QEP's own branch so reference and target land in one commit. Unchanged in substance — it is how QEP-2 ↔ QEP-4 already works, with the removed hook wording preserved in the `qep-0004` branch's *Amendments to QEP-2* section. The second records the ruling that the convention stops at this repo's boundary. A QEP is the source of truth and is independent of every repository: it states the rule, and a consuming repo owns how and when it conforms. Precedence clauses, handover obligations and tracking-issue references for another repository do not belong in a QEP — an issue number in a repo this one does not own is a status pointer that rots, and a QEP states rules rather than tracking their adoption elsewhere. The third extends that from pointers to **descriptions**, added after QEP-6 supplied the worked example. Its Adoption item 5 said the projects dashboard re-sorts children by issue number and prescribed the remedy — a one-row contract change, a sort removal, and the test to verify it. status-projects had already removed the sort on its own reasoning two days earlier, and for a better-stated reason than the QEP gave. So the QEP shipped a stale claim *and* an obligation discharged before it was written, and nothing would have signalled either. What survives instead is the principle with its reason attached: §3 now says a consumer that republishes a tracker presents the structure the tracker expresses, because a consumer that re-sorts or re-groups makes a conformant tracker and a non-conformant one publish identically. That holds whatever any consumer does next. ## Already applied - #23 dropped the QEP-1 amendment; v3 is now three changes. - #18 dropped QEP-6's precedence clause and cross-repo handover item, removed Adoption item 5 entirely, and generalised §3's consumer clause to a principle. - Ownership is recorded from the other side in QuantEcon/status-projects#140, and the one thing genuinely missing there — a regression guard for list-order publishing — is QuantEcon/status-projects#142. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
…ated The note still told readers the Type/Version columns are "kept in sync by CI" — the behaviour this PR replaces with whole-table regeneration from frontmatter. AGENTS.md was updated in four places for that change and the README's own description of the same mechanism was left behind, so main would have carried a stale account of the thing this PR ships. The sentence about `Version` reading `–` is deliberately left alone: it is still true today, and it is QEP-1 v3 (#23) that changes it, so that half belongs in the PR that makes it false. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The note said `Version` reads `–` until a QEP is first amended — the v1–v2
rule this amendment replaces. Under v3 every merged QEP carries a version
from the moment it lands, so the column shows `v{N}` from `v0` up and a `–`
means only that the stamp has not reached that QEP yet, which QEP-1's
Adoption section commits to closing.
Stated as what the column means rather than hedged with when the automation
arrives: the pointer to Adoption carries the gap, as it does for the rest of
this amendment.
The note's other stale half — "the Type/Version columns are kept in sync by
CI", which whole-table regeneration replaces — is fixed in #30, the PR that
makes it false.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Copilot review: three answered, one acted onRe-ran the Copilot review on this PR. The three inline comments were all answered on 2026-09-04 and need nothing further — the position taken there holds: QEP-1 states the rule, and the gap between rule and implementation lives in Adoption, so the prose is not hedged with implementation status. One of those threads had already produced a real fix in The fourth comment was suppressed, so it has no thread to reply to. It was right, and it under-called the problem — the README index note is stale in two ways, not one:
The The "kept in sync by CI" half is not this PR's — whole-table regeneration is what makes it false, so it is fixed in #30 alongside the change that causes it. The two edits sit on separate source lines, so they compose without a conflict when this branch takes #30. |
Takes #30's generated index and the reworked checks. The README index note conflicted: both PRs rewrote that sentence, #30 replacing "kept in sync by CI" with the generated-table description and this branch replacing the `Version` clause with v3's rule. The resolution keeps both halves — the table is generated from frontmatter, and `Version` shows `v{N}` from `v0` up with `–` meaning the stamp has not reached that QEP yet. I had said the two edits sat on separate source lines and would compose without a conflict; they overlapped on the line they share. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
… narration Step 3 states the rule only; the rationale lives under Alternatives considered. Substantive amendments are accepted the same way as a new QEP; editorial changes need no second reader. Roles defines Core Maintainers by admin rights on this repository. The deadline entry under Alternatives keeps the principle and links #26 for the evidence; Adoption item 4 is reordered to match its title, drops the PR narration, and points the follow-up at #22. The unreachable Draft clause on the README Version column is removed. qeps/template.md and AGENTS.md follow the v3 version rule so neither describes the implicit-v0 semantics after this merges. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
|
@jstac this is a pretty sensible amendment for QEP-1 to put what we |
|
Thanks @mmcky , looks good to me. |
Substantive amendment: QEP-1 v2 → v3. Discussions: #22 (stamping), #26 (the deadline and the index).
What this amendment changes
1. Stamp
versionandversion-hashfrom v0. Every QEP that records an outcome carries both fields from the merge that records it. A Draft carries neither; the post-merge stamp writesversion: 0and the hash uniformly across Accepted, Rejected and Withdrawn, and the hash moves on every later merged change, editorial included.version-hashis stated plainly to be a historical anchor, not a file checksum. The implicit-v0 design it replaces is recorded under Alternatives considered.2. The decision deadline is struck; acceptance needs one other Core Maintainer. Step 3 of How a QEP is decided becomes: once the PR has been announced and no objection is outstanding, a Core Maintainer other than the author accepts the QEP with an approving review. Lazy consensus with no clock, and nobody accepts their own QEP. The same rule governs substantive amendments; editorial changes need no second reader. Roles now says who a Core Maintainer is (admin rights on this repository). The evidence for dropping the deadline is on #26; the QEP keeps the principle.
3. The README index is generated post-merge from each QEP's frontmatter, ordered by number, so a PR carries no row of its own. Numbering states the reservation rule that makes index gaps normal. The mechanism landed in #30; Automation names it, together with the ordered-list check.
Also in this PR
qeps/template.mdandAGENTS.mdfollow the new version rule, so neither describes the implicit-v0 semantics after this merges. The README's process steps and index note follow QEP-1.What follows acceptance
Tracked on #22: the stamp action writes
version: 0where missing, already-merged QEPs past Draft are backfilled, the pull-request check's new-QEP rule inverts, and the README index and theme pill showv0.Per convention
version-hashis removed for CI to re-stamp at merge. Under change 2 this PR wants an approving review from a Core Maintainer other than its author before it merges.🤖 Generated with Claude Code