Repository navigation
Migrate the remaining repos off the planning/ convention #67
Description
Tracking issue for moving the rest of the org off the planning/ convention and onto
PR-body-as-spec. #50 did this repo; modern-di and faststream-outbox did themselves
earlier. This covers everyone else.
Where the org actually stands
Measured across all 28 non-archived repos, not estimated:
| State | Count | Repos |
|---|---|---|
Migrated — CONTEXT.md + docs/adr/, no planning/ |
3 | .github, modern-di, faststream-outbox |
| Mid-migration — has both | 1 | chat-app |
Not migrated — planning/ only |
21 | the checklist below |
| On neither convention | 3 | that-depends, fastapi-sqlalchemy-template, litestar-sqlalchemy-template |
Three of those are handled elsewhere and are not part of this issue's checklist:
chat-app— chat-app is half-migrated: the PR body is the spec, but planning/ is still a merge gate #70that-depends— that-depends has no agent instructions file #69fastapi-sqlalchemy-templateandlitestar-sqlalchemy-templateare on neither
convention and have noplanning/tree, so there is nothing here to migrate. Whether
they should adopt one is undecided and untracked.
Why this is a programme, not a sweep
The .github migration (#50) was one PR but a session of judgment: ruling on 24 change
files, one decision record, a deferred list, and a 5-page architecture/ tree — each one
either derivable and dropped, enforceable and turned into a test, a rejected alternative
turned into an ADR, or real work turned into an issue. modern-di took five PRs
(modern-python/modern-di#424, #432, #433, #439, #449).
Per-repo issues should be spawned as work starts, not written upfront — 21 stale specs
would be worse than none.
The recipe, as actually performed twice
CONTEXT.md— the vocabulary. Seed fromarchitecture/glossary.mdwhere one exists;
otherwise author it, and audit every_Avoid_entry against real usage before committing
(in.githubthat cut ten terms to seven — four rejected synonyms appeared nowhere in
the repo).docs/adr/—planning/decisions/*becomeNNNN-slug.md, each with a revisit
trigger. Also rescue rejected alternatives buried in change files and capability pages.- Deferred items become GitHub issues, self-contained, carrying their revisit triggers.
planning/changes/*are deleted. Git history is the record; route anything
load-bearing through the admission check first.architecture/is dropped. Enforceable claims become tests whose name is the claim,
with anINVARIANT:docstring naming what breaks it.AGENTS.mdgains the Workflow and Where-a-fact-goes sections and loses the lanes.docs/agents/domain.mdrepoints toCONTEXT.md+docs/adr/.justfileand CI dropcheck-planning/index. Add the offline link gate (Add the offline link gate to the 18 green repos, and unpublish the ADRs in the two that have them #66) in
the same PR — see below.- Do not touch
.github/PULL_REQUEST_TEMPLATE.md. The org default is staying as the
generic form and is true under either convention, so a migrating repo needs no template
change. Template work is Delete the local PR templates; keep the generic org default #53, which runs independently of this issue.
The link gate rides along
#66 adopts a blocking offline link check in the 18 repos that are already green. Seven
repos are red, and all seven are red only inside planning/:
httpware 56, lite-bootstrap 8, compose2pod 4, semvertag 3, faststream-concurrent-aiokafka 3,
faststream-redis-timers 2, db-retry 1 — 77 broken links, 77 of 77 in planning/, zero in
any user-facing surface.
Deleting planning/ deletes all 77. So each migration PR should add the gate as its last
step and land green, rather than #66 excluding planning/ to work around history that is
about to be removed.
Checklist — the 21 not-migrated repos
-
compose2pod(4 dead links) — chore: migrate off the planning/ convention compose2pod#89 -
db-retry(1) — chore: migrate off the planning/ convention db-retry#37 -
eof-fixer— chore: migrate off the planning/ convention eof-fixer#34 -
faststream-concurrent-aiokafka(3) — chore: migrate off the planning/ convention faststream-concurrent-aiokafka#65 -
faststream-redis-timers(2) — chore: migrate off the planning/ convention faststream-redis-timers#68 -
httpware(56) — chore: migrate off the planning/ convention httpware#119 -
lite-bootstrap(8) — chore: migrate off the planning/ convention lite-bootstrap#176 -
modern-di-aiogram— chore: migrate off the planning/ convention modern-di-aiogram#14 -
modern-di-aiohttp— chore: migrate off the planning/ convention modern-di-aiohttp#19 -
modern-di-arq— chore: migrate off the planning/ convention modern-di-arq#14 -
modern-di-celery— chore: migrate off the planning/ convention modern-di-celery#14 -
modern-di-fastapi— chore: migrate off the planning/ convention modern-di-fastapi#42 -
modern-di-faststream— chore: migrate off the planning/ convention modern-di-faststream#43 -
modern-di-flask— chore: migrate off the planning/ convention modern-di-flask#14 -
modern-di-grpc— chore: migrate off the planning/ convention modern-di-grpc#13 -
modern-di-litestar— chore: migrate off the planning/ convention modern-di-litestar#44 -
modern-di-pytest— chore: migrate off the planning/ convention modern-di-pytest#40 -
modern-di-starlette— chore: migrate off the planning/ convention modern-di-starlette#19 -
modern-di-taskiq— chore: migrate off the planning/ convention modern-di-taskiq#12 -
modern-di-typer— chore: migrate off the planning/ convention modern-di-typer#37 -
semvertag— chore: migrate off the planning/ convention semvertag#62
chat-app (#70) and that-depends (#69) are tracked separately and are not on this list.
Out of scope
- The org-default PR template and the local-copy removals (Delete the local PR templates; keep the generic org default #53).
- Adopting the link gate in the 18 already-green repos (Add the offline link gate to the 18 green repos, and unpublish the ADRs in the two that have them #66).
Activity
lesnik512 commentedon Sep 6, 2026
The recipe is missing a step:
release.ymldepends onplanning/Found while migrating
modern-di-pytest(the first off this checklist). Step 8 coversjustfileand CI'scheck-planning/index, but not the release workflow — and in the_checks.yml-convention repos that workflow readsplanning/directly:It does two things: hard-requires a curated notes file for every stable tag, and sources the
GitHub Release body from it. Delete
planning/while leaving that in place and the nextstable tag fails the release job — after
just publishhas already pushed to PyPI, sincethe notes gate runs before publish but the body resolution runs after.
This is not one repo's quirk. Spot-checked locally:
lite-bootstrap— same threeplanning/releases/references inrelease.ymlmodern-di-faststream— same threechat-app— different shape:main.ymlinvokesplanning/index.pyandplanning/links.pydirectly (relevant to chat-app is half-migrated: the PR body is the spec, but planning/ is still a merge gate #70)
There is already a precedent to copy.
modern-dihit this during its own migration andresolved it in
1ea74ee, "drop theplanning/directory and the curated-release-notesconvention" (modern-python/modern-di#449) — one of the five PRs this issue cites. Its
post-migration
release.ymldrops the notes gate and the body source, keeping only theprerelease flag:
Suggested step 8b:
release.ymldrops the curated-notes gate and theplanning/releases/<tag>.mdbody source, matchingmodern-dipost-1ea74ee. Worth callingout explicitly that this retires a stated policy — curated notes were mandatory for stable
tags — so a migration PR should say so rather than let it ride in as a docs change. That also
means a migrating repo's PR is
chore:, notdocs:: it changes release behaviour.One more note for whoever picks up the remaining repos:
planning/releases/*.mdarebyte-identical to the published GitHub Release bodies (checked on
modern-di-pytest3.0.1), sodeleting them loses nothing — the Releases are the record.
chore: migrate off the planning/ convention (#40)
chore: migrate off the planning/ convention (#19)
chore: migrate off the planning/ convention (#14)
chore: migrate off the planning/ convention (#19)
chore: migrate off the planning/ convention (#43)
chore: migrate off the planning/ convention (#13)
chore: migrate off the planning/ convention (#14)
chore: migrate off the planning/ convention (#42)
chore: migrate off the planning/ convention (#44)
chore: migrate off the planning/ convention (#37)
chore: migrate off the planning/ convention (#14)
chore: migrate off the planning/ convention (#12)
chore: migrate off the planning/ convention (#14)
23 remaining items
chore(ci): check absolute self-links in the offline link gate (#15)
chore(ci): check absolute self-links in the offline link gate (#14)
chore(ci): check absolute self-links in the offline link gate (#45)
chore(ci): check absolute self-links in the offline link gate (#41)
chore(ci): check absolute self-links in the offline link gate (#20)
chore(ci): check absolute self-links in the offline link gate (#13)
chore(ci): check absolute self-links in the offline link gate (#38)
chore(ci): check absolute self-links in the offline link gate (#461)
chore(ci): check absolute self-links in the offline link gate (#83)
chore(ci): check absolute self-links in the offline link gate (#63)
chore(ci): check absolute self-links in the offline link gate
chore(ci): check absolute self-links in the offline link gate
chore(ci): check absolute self-links in the offline link gate (#27)
chore(ci): check absolute self-links in the offline link gate (#242)
chore: migrate off the planning/ convention (#53)