Skip to content

chore: migrate off the planning/ convention - #40

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

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

Conversation

@lesnik512

Copy link
Copy Markdown
Member

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.

What moves, and what is genuinely deleted

  • planning/ deleted in full. changes/ and releases/ held nothing git
    history and GitHub Releases do not: the release notes were byte-identical to
    the published Release bodies. deferred.md was empty, so no issues needed
    spawning.
  • The one decision record becomes docs/adr/0001, keeping its revisit
    trigger.
  • architecture/ carried no capability pages. The only claim worth rescuing
    was the two-symbol public surface, now an INVARIANT test checked against three
    cases: __all__ growing and an unprefixed public binding both fail it, and
    narrowing the surface does not.
  • CONTEXT.md defines only the three terms local to this package; the rest
    are modern-di's. Its install/inject/register entry reflects real usage
    (install 12, inject 3, register 2), so the three stragglers in factory.py
    and README.md were brought to the winner rather than the entry dropped. One
    is a user-visible ValueError string.
  • AGENTS.md gains Workflow and Where-a-fact-goes, loses the lanes, and
    sheds the prose restatement of factory.py that the admission check
    disallows.
  • 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).

Why this is chore: and not docs:

release.yml sourced the Release body from planning/releases/<tag>.md and
hard-required one for every stable tag, so deleting planning/ would have
failed every future stable release. It now uses GitHub's generated notes,
byte-identical to modern-di's post-migration workflow, which dropped the same
gate 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. Stable releases lose a hard gate; that is the precedent's call, not a new
one.

Verification

just lint-ci clean. just test-ci passes at 100% coverage, 18 tests
(17 plus the new public-surface invariant). No remaining relative link points
into planning/ or architecture/; the new offline lychee job covers the rest.

Rebased onto 11a0d11 for this PR. It picked up the three README/expose()
changes that landed while it sat (#37, #38, #39) with no conflicts, and the two
independent edits to the same expose() paragraph composed correctly: this
branch's install/onto rewording plus #39's TypeError sentence.

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. changes/ and releases/ held nothing git history and
  GitHub Releases do not; the release notes were byte-identical to the published
  Release bodies. deferred.md was empty, so no issues needed spawning.
- The one decision record becomes docs/adr/0001, keeping its revisit trigger.
- architecture/ carried no capability pages. The only claim worth rescuing was
  the two-symbol public surface, now an INVARIANT test checked against three
  cases: __all__ growing and an unprefixed public binding both fail it, and
  narrowing the surface does not.
- CONTEXT.md defines only the three terms local to this package; the rest are
  modern-di's. Its install/inject/register entry reflects real usage (install 12,
  inject 3, register 2), so the three stragglers in factory.py and README.md were
  brought to the winner rather than the entry dropped. One is a user-visible
  ValueError string.
- AGENTS.md gains Workflow and Where-a-fact-goes, loses the lanes, and sheds the
  prose restatement of factory.py that the admission check disallows.
- justfile and lint-ci drop index/check-planning/check-links; the offline lychee
  gate replaces links.py (modern-python/.github#66), reporting 0 errors.

Beyond the recipe, and the reason this is chore: and not docs: release.yml
sourced the Release body from planning/releases/<tag>.md and hard-required one
for every stable tag, so deleting planning/ would have failed every future
stable release. It now uses GitHub's generated notes, byte-identical to
modern-di's post-migration workflow, which dropped the same gate in 1ea74ee
("drop the planning/ directory and the curated-release-notes convention", #449)
— one of the five migration PRs #67 cites. Stable releases lose a hard gate;
that is the precedent's call, not a new one.
@lesnik512
lesnik512 merged commit a09a7e4 into main Sep 6, 2026
7 checks passed
@lesnik512
lesnik512 deleted the docs/migrate-off-planning branch September 6, 2026 19:07
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