Skip to content

chore: migrate off the planning/ convention - #19

Merged
lesnik512 merged 1 commit into
mainfrom
chore/migrate-off-planning
Sep 6, 2026
Merged

chore: migrate off the planning/ convention#19
lesnik512 merged 1 commit into
mainfrom
chore/migrate-off-planning

Conversation

@lesnik512

Copy link
Copy Markdown
Member

Migrates modern-di-aiohttp off the planning/ convention and onto PR-body-as-spec, with CONTEXT.md owning the vocabulary and docs/adr/ holding rejected alternatives. Part of modern-python/.github#67.

Replaces the two-axis planning/ + architecture/ convention with PR-body-as-spec,
CONTEXT.md for vocabulary, and docs/adr/ for rejected alternatives, per
modern-python/.github#67.

  • planning/ deleted in full. The four change files hold nothing git history does
    not; all six release notes are the published GitHub Release bodies verbatim
    (verified against gh release view for 2.0.0, 3.1.0 and 3.1.1 — identical but
    for GitHub's trailing newline), so the Releases are the record. deferred.md
    was empty and no change file carries unscheduled work, so no issues needed
    spawning.
  • decisions/ was empty, but two rejected alternatives were buried in the design
    change file and in architecture/container-lifecycle.md, and both would be
    re-litigated by anyone who read only the code. They become docs/adr/0001 (two
    connection providers, one reference-only: dishka's single SESSION binding with
    contiguous scopes rejected) and docs/adr/0002 (scope from the can_prepare
    handshake probe: dishka's header comparison and route-table dispatch
    rejected). Each keeps a revisit trigger.
  • architecture/ held prose about mechanism the module already states. The one
    enforceable claim was that exactly one connection provider carries a bound
    type, now the INVARIANT test in tests/test_connection_providers.py. Verified by
    breaking it: dropping bound_type=None from aiohttp_websocket_provider turns it
    red, restoring turns it green, and adding a third reference-only connection
    provider — a change that keeps the invariant — leaves it green.
  • CONTEXT.md defines only the three terms local to this integration; the rest are
    modern-di's. The glossary audit cut the FromDI-marker entry (its only rejected
    synonym, "Depends", appears nowhere) and four of five Avoid synonyms: "app
    container", "global container" and "sub-container" have no use in the repo.
    "request container" is kept and is the one that earns its place — the public
    fetch_request_container() returns a SESSION-scoped container on a WebSocket, so
    the function name misnames the scope. No source edit was forced: no prose in
    the package, tests or README uses a rejected synonym today.
  • AGENTS.md gains Workflow and Where-a-fact-goes, loses the lanes and the
    capability-page promotion rule, and sheds the Build & checks list the justfile
    already owned.
  • justfile and lint-ci drop index/check-planning/check-links; the offline lychee
    gate replaces links.py (Add the offline link gate to the 18 green repos, and unpublish the ADRs in the two that have them .github#66), reporting 0 errors over 32
    unique links.

Beyond the recipe, and the reason this is chore: and not docs: release.yml read
planning/releases/.md as the GitHub Release body, so deleting planning/
would have silently changed every future Release. It now uses GitHub's generated
notes. The file is modern-di's post-migration release.yml verbatim, down to the
PyPI project name in one comment; that workflow dropped the same convention in
1ea74ee ("drop the planning/ directory and the curated-release-notes
convention", modern-python/modern-di#449), one of the five migration PRs #67
cites. This repo never carried the mandatory "Require curated release notes"
gate some siblings did, so nothing here becomes newly ungated — curated notes
simply stop being a source; a release wanting prose is edited after the fact
with gh release edit <tag> --notes-file.

Verification

  • just lint-ci — clean (eof-fixer, ruff format, ruff check, ty).
  • Test suite green at the repo's 100% coverage gate.
  • Offline link gate (lychee --offline --no-progress '**/*.md') — 0 errors.
  • No planning/, architecture/, check-planning, check-links or convention-version reference remains.

Note

release.yml previously read planning/releases/<tag>.md, both as a hard gate for stable tags and as the Release body source; deleting planning/ without changing it would have broken the next stable release. It now uses GitHub's generated notes, matching modern-di post-modern-python/modern-di#449. This retires the mandatory-curated-notes policy.

Replaces the two-axis planning/ + architecture/ convention with PR-body-as-spec,
CONTEXT.md for vocabulary, and docs/adr/ for rejected alternatives, per
modern-python/.github#67.

- planning/ deleted in full. The four change files hold nothing git history does
  not; all six release notes are the published GitHub Release bodies verbatim
  (verified against `gh release view` for 2.0.0, 3.1.0 and 3.1.1 — identical but
  for GitHub's trailing newline), so the Releases are the record. deferred.md
  was empty and no change file carries unscheduled work, so no issues needed
  spawning.
- decisions/ was empty, but two rejected alternatives were buried in the design
  change file and in architecture/container-lifecycle.md, and both would be
  re-litigated by anyone who read only the code. They become docs/adr/0001 (two
  connection providers, one reference-only: dishka's single SESSION binding with
  contiguous scopes rejected) and docs/adr/0002 (scope from the can_prepare
  handshake probe: dishka's header comparison and route-table dispatch
  rejected). Each keeps a revisit trigger.
- architecture/ held prose about mechanism the module already states. The one
  enforceable claim was that exactly one connection provider carries a bound
  type, now the INVARIANT test in tests/test_connection_providers.py. Verified by
  breaking it: dropping bound_type=None from aiohttp_websocket_provider turns it
  red, restoring turns it green, and adding a third reference-only connection
  provider — a change that keeps the invariant — leaves it green.
- CONTEXT.md defines only the three terms local to this integration; the rest are
  modern-di's. The glossary audit cut the FromDI-marker entry (its only rejected
  synonym, "Depends", appears nowhere) and four of five _Avoid_ synonyms: "app
  container", "global container" and "sub-container" have no use in the repo.
  "request container" is kept and is the one that earns its place — the public
  fetch_request_container() returns a SESSION-scoped container on a WebSocket, so
  the function name misnames the scope. No source edit was forced: no prose in
  the package, tests or README uses a rejected synonym today.
- AGENTS.md gains Workflow and Where-a-fact-goes, loses the lanes and the
  capability-page promotion rule, and sheds the Build & checks list the justfile
  already owned.
- justfile and lint-ci drop index/check-planning/check-links; the offline lychee
  gate replaces links.py (modern-python/.github#66), reporting 0 errors over 32
  unique links.

Beyond the recipe, and the reason this is chore: and not docs: release.yml read
planning/releases/<tag>.md as the GitHub Release body, so deleting planning/
would have silently changed every future Release. It now uses GitHub's generated
notes. The file is modern-di's post-migration release.yml verbatim, down to the
PyPI project name in one comment; that workflow dropped the same convention in
1ea74ee ("drop the planning/ directory and the curated-release-notes
convention", modern-python/modern-di#449), one of the five migration PRs #67
cites. This repo never carried the mandatory "Require curated release notes"
gate some siblings did, so nothing here becomes newly ungated — curated notes
simply stop being a source; a release wanting prose is edited after the fact
with `gh release edit <tag> --notes-file`.
@lesnik512
lesnik512 merged commit a8cb417 into main Sep 6, 2026
7 checks passed
@lesnik512
lesnik512 deleted the chore/migrate-off-planning branch September 6, 2026 19:12
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant