Repository navigation
Host the PR-body-as-spec template org-wide; adopt the convention here #50
Description
What
Two repos have now moved to a convention where the PR body is the spec for a change — there is
no committed change file, no lane to pick, and no planning/ tree:
modern-di— PRs #424–#450faststream-outbox— chore: adopt the modern-di convention; drop planning/ and architecture/ faststream-outbox#159 (open)
Both carry an identical-in-shape .github/PULL_REQUEST_TEMPLATE.md, differing only in the package
path and the test command. This repo already hosts the org-default template at
.github/PULL_REQUEST_TEMPLATE.md, so it is the natural home — but the default is currently the
generic Summary / Changes / Checklist form, which does not carry the parts that make the convention
work.
Why the generic template is not enough
The convention's template is not a nicer checklist; four of its prompts are the convention:
- The admission check. Before writing a fact anywhere: derivable from the package → don't write
it; enforceable → a test; a user needs it →docs/; otherwise it does not get written. Without
this prompt at review time, prose accretes and theplanning/tree grows back. - The invariant pin. If a wrong change could pass silently, pin it with a test whose name is the
claim and whose docstring opensINVARIANT:and says what breaks it. - ADR routing. A rejected alternative with load-bearing reasoning goes to
docs/adr/, not into
the PR body where it is lost on merge. - Issue routing. Real work you are not doing now becomes an issue, not a deferred-work file.
The generic template's "Docs updated if behavior or public API changed" asks the old question —
did you update the page? — which is what let the capability pages in both repos ratchet toward
restating code.
Proposed
- Adopt the convention in this repo.
planning/.convention-versionis still2.0.0, and this
repo still carriesplanning/andarchitecture/. Deciding for the org while running the older
convention here is the awkward part; doing it first also proves the migration on a docs-shaped
repo rather than a library. - Replace the org-default
.github/PULL_REQUEST_TEMPLATE.mdwith the convention form, written
generically — the two repo-specific bits are the package directory and the test command, which
can be phrased as "the package" and "the repo's full-suite recipe". - Then the local copies come out. Once the default is in place,
modern-diand
faststream-outboxdelete their own.github/PULL_REQUEST_TEMPLATE.mdand inherit it. Both are
deliberately keeping theirs until step 2 lands, since a repo-local template silently wins over
the org default and there is no signal when the two drift.
Open question
Whether the generic form loses too much. The value of the checklist is partly that it names the
repo's actual gate (just test at 100% coverage in faststream-outbox, just test-ci in
modern-di). If the generic version reads as boilerplate, the alternative is to keep the template
local per repo and instead put the convention — the admission check and the four routes — in this
repo's CLAUDE.md as an org-wide rule, with each repo's template referencing it.
Activity
lesnik512 commentedon Sep 6, 2026
Triage outcome:
ready-for-human, scope narrowed to step 1Splitting. Step 1 stays here. Steps 2 and 3 move to a follow-up issue, because verification turned up a blocker they cannot clear as written.
Step 2 would mis-instruct 21 repos
The org default is inherited by everything without a local template. Measured across the 28 non-archived repos:
.github/PULL_REQUEST_TEMPLATE.md—.github,chat-app,faststream-outbox,modern-di,that-depends.planning/.Replacing the org default with the convention form would hand those 21 a template instructing "file an ADR in
docs/adr/", "no change file", "no lane to pick" — while they still runplanning/withplanning/decisions/, change files, andjust check-planningas a gate. The template would contradict each repo's own workflow on the day it lands, with nothing in CI to notice. That is the same class of defect the body identifies in the generic template, pointed the other way.Only two repos have actually adopted the convention:
modern-diandfaststream-outbox. Every other repo is on the old one.The two templates differ in more than two places
The body says they are "identical-in-shape, differing only in the package path and the test command". Diffing them shows three parameterizable axes and one semantic divergence:
modern_di/vsfaststream_outbox/)just test-civsjust test)just bench-checkas a stated gate — onlyfaststream-outboxmodern-direquires "with a revisit trigger";faststream-outboxdropped that phraseThe last one is not cosmetic, and it shows in practice:
modern-dihas a revisit trigger in 27 of 27 ADRs;faststream-outboxin 1 of 2. The template that omits the requirement is the repo that doesn't do it. This is precisely the silent drift the body warns about — "there is no signal when the two drift" — except it has already happened, before the org default was even touched.Whichever way step 2 goes, that phrase needs a deliberate ruling rather than being inherited from whichever copy is used as the base.
Status correction
The body lists
faststream-outbox#159as open. It merged on 2026-09-05. Both named repos are fully on the convention now —planning/andarchitecture/are gone from both — so step 3's "the local copies come out" is the only part of those two repos still pending.What stays here: step 1
Adopting the convention in this repo is self-contained, needs none of the above settled, and is the part the body correctly argues should go first — "deciding for the org while running the older convention here is the awkward part". It also does what the body wants it to: proves the migration on a docs-shaped repo rather than a library.
ready-for-humanrather thanready-for-agent, because the migration is a series of judgment calls, not a mechanical transform:planning/, plus anarchitecture/tree with 5 capability pages and adeferred.md. Retiringplanning/means ruling on each: promote intoarchitecture/, convert to an ADR under a newdocs/adr/, become an issue, or drop.modern-didid this over several PRs (#429–#431, #439), not one.docs/adr/yet, and itsdocs/is the published MkDocs source for modern-python.org — so an ADR directory needs anot_in_navorexclude_docsdecision, which the library repos did not face.just check-planningis a CI gate here and would need retiring with the tree.architecture/+planning/as this repo's domain homes. It is written to be rewritten as part of this migration; whoever does step 1 should updatedocs/agents/domain.mdin the same PR.Out of scope for this issue: the org-default template and the local-copy removals, now tracked separately.
lesnik512 commentedon Sep 6, 2026
Steps 2 and 3 are now tracked in #53, labeled
needs-infopending the sequencing decision. This issue is step 1 only.chore: migrate off the planning/ convention (#43)
chore: migrate off the planning/ convention (#65)