Skip to content

chore: migrate off the planning/ convention - #62

Merged
lesnik512 merged 2 commits into
mainfrom
chore/migrate-off-planning
Sep 6, 2026
Merged

chore: migrate off the planning/ convention#62
lesnik512 merged 2 commits into
mainfrom
chore/migrate-off-planning

Conversation

@lesnik512

Copy link
Copy Markdown
Member

Migrates semvertag 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.

This branch also carries chore(context7): drop the stale planning/ exclusion — the context7.json entry naming planning/ only becomes dead once this migration deletes the directory, so the two land together.

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, 53 files. changes/ held 25 design and change files
    that git history already carries. releases/ held 13 notes; 11 are byte-identical
    to the published GitHub Release bodies except for a "See also" footer pointing at
    planning/ paths that fix(planning): salvage archived change links to flat 2.0.0 files #51 retro-edited locally and never re-pushed, plus a local H1
    on 0.3.1 — all of it dying with planning/. Two are not: the published bodies for
    0.5.0 and 0.7.2 are shorter summaries than the local drafts. The Releases are
    still the record; the longer drafts stay in git history. deferred.md was empty.
  • The five decision records become docs/adr/0001..0005 in date order, frontmatter
    stripped, revisit triggers kept, cross-references renumbered. None carried
    supersedes/superseded_by, so nothing needed restating as prose. Two more rejected
    alternatives were rescued from prose that planning/ was about to take with it:
    0006, the removed doctor preflight and the three arguments that retire it, from
    changes/2026-05-31.02; and 0007, why the composite action deliberately does not
    run actions/checkout, from a single decision-log line in changes/2026-06-08.03.
  • architecture/ carried a README and three capability pages, all prose about
    mechanism that semvertag/ states itself. One claim was enforceable and unenforced:
    a strategy sees one commit and nothing else. It is now the INVARIANT test
    tests/test_strategy_isolation.py, which walks the import closure of
    semvertag/strategies/. Verified against four cases: a strategy importing httpware
    fails it, a strategy importing semvertag.providers fails it, an httpx2 import
    added to semvertag/_commit_parse.py fails it through the closure rather than
    directly, and a strategy importing semvertag._errors — widening nothing — leaves
    it green. Sources restored byte-identically, suite green.
  • CONTEXT.md is authored from scratch; there was no architecture/glossary.md. Seven
    terms. The audit cut one the previous draft had listed: Bump, whose rejected
    synonyms ("bump level", "bump kind") appear nowhere outside AGENTS.md and
    architecture/, both rewritten or deleted here. It forced no source edits, but it
    did surface a docs defect too large to fix in this commit: four docs/ pages tell
    users the conventional-commits strategy scans every commit since the last tag,
    when the use-case fetches only the head commit of the default branch. Correcting
    the phrase alone would leave the false claim standing, so it is drafted as an
    issue instead of edited here.
  • AGENTS.md gains Workflow and Where-a-fact-goes and loses the planning lanes and
    the architecture/ promotion rule. The admission check applied to it also cut a
    "Reference directories (do not edit)" section naming _archive/bmad/ and
    _autosemver_reference/ — neither directory exists in the tree or in git history —
    and a commit-message section whose only live content restated conventional
    commits. docs/agents/domain.md is deliberately absent: origin/main has no
    docs/agents/ and AGENTS.md had no Agent skills section to link one from, so
    authoring domain.md alone would be a half-rollout of a separate convention.
  • justfile and lint-ci drop index/check-planning (this repo had no links.py); the
    offline lychee gate lands in _checks.yml as a links job (Add the offline link gate to the 18 green repos, and unpublish the ADRs in the two that have them .github#66),
    taking the tree from 3 errors to 0 over 46 unique links. mkdocs.yml excludes
    /adr/ from the published site, matching modern-di, so the decision records do not
    appear on semvertag.modern-python.org.

Beyond the recipe, and the reason this is chore: and not docs: release.yml both
hard-required planning/releases/.md for every stable tag and sourced the
Release body from it, so deleting planning/ would have failed every future stable
release. The gate is gone and the body is now GitHub's generated notes, matching
modern-di's post-migration workflow, which dropped the same gate in 1ea74ee
(modern-python/modern-di#449). This retires the mandatory-curated-notes policy; a
release wanting prose is edited after the fact with gh release edit. modern-di's
file was NOT copied verbatim: semvertag's release.yml also owns the Float major tag
step that force-updates the v0 ref action consumers pin, which modern-di has no
equivalent of. Copying verbatim would have deleted it and broken every
uses: modern-python/semvertag@v0 on the next release, so only the notes handling
was aligned.

Verification: just lint-ci clean, just test 474 passed at 100% branch coverage,
just docs-build strict green with no adr/ output, lychee --offline 0 errors, and no
file outside .git references planning/, architecture/, check-planning, check-links
or convention-version.

The sibling commit on this branch deletes planning/, so the exclusion now
names a directory that does not exist.

Dropping the key rather than leaving an empty list: Context7's schema
(https://context7.com/schema/context7.json) declares no required properties
and gives excludeFolders a default of [], so an absent key and an empty list
are equivalent. Absent matches the repos that never carried the line.

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, 53 files. changes/ held 25 design and change files
  that git history already carries. releases/ held 13 notes; 11 are byte-identical
  to the published GitHub Release bodies except for a "See also" footer pointing at
  planning/ paths that #51 retro-edited locally and never re-pushed, plus a local H1
  on 0.3.1 — all of it dying with planning/. Two are not: the published bodies for
  0.5.0 and 0.7.2 are shorter summaries than the local drafts. The Releases are
  still the record; the longer drafts stay in git history. deferred.md was empty.
- The five decision records become docs/adr/0001..0005 in date order, frontmatter
  stripped, revisit triggers kept, cross-references renumbered. None carried
  supersedes/superseded_by, so nothing needed restating as prose. Two more rejected
  alternatives were rescued from prose that planning/ was about to take with it:
  0006, the removed doctor preflight and the three arguments that retire it, from
  changes/2026-05-31.02; and 0007, why the composite action deliberately does not
  run actions/checkout, from a single decision-log line in changes/2026-06-08.03.
- architecture/ carried a README and three capability pages, all prose about
  mechanism that semvertag/ states itself. One claim was enforceable and unenforced:
  a strategy sees one commit and nothing else. It is now the INVARIANT test
  tests/test_strategy_isolation.py, which walks the import closure of
  semvertag/strategies/. Verified against four cases: a strategy importing httpware
  fails it, a strategy importing semvertag.providers fails it, an httpx2 import
  added to semvertag/_commit_parse.py fails it through the closure rather than
  directly, and a strategy importing semvertag._errors — widening nothing — leaves
  it green. Sources restored byte-identically, suite green.
- CONTEXT.md is authored from scratch; there was no architecture/glossary.md. Seven
  terms. The audit cut one the previous draft had listed: Bump, whose rejected
  synonyms ("bump level", "bump kind") appear nowhere outside AGENTS.md and
  architecture/, both rewritten or deleted here. It forced no source edits, but it
  did surface a docs defect too large to fix in this commit: four docs/ pages tell
  users the conventional-commits strategy scans every commit since the last tag,
  when the use-case fetches only the head commit of the default branch. Correcting
  the phrase alone would leave the false claim standing, so it is drafted as an
  issue instead of edited here.
- AGENTS.md gains Workflow and Where-a-fact-goes and loses the planning lanes and
  the architecture/ promotion rule. The admission check applied to it also cut a
  "Reference directories (do not edit)" section naming _archive/bmad/ and
  _autosemver_reference/ — neither directory exists in the tree or in git history —
  and a commit-message section whose only live content restated conventional
  commits. docs/agents/domain.md is deliberately absent: origin/main has no
  docs/agents/ and AGENTS.md had no Agent skills section to link one from, so
  authoring domain.md alone would be a half-rollout of a separate convention.
- justfile and lint-ci drop index/check-planning (this repo had no links.py); the
  offline lychee gate lands in _checks.yml as a links job (modern-python/.github#66),
  taking the tree from 3 errors to 0 over 46 unique links. mkdocs.yml excludes
  /adr/ from the published site, matching modern-di, so the decision records do not
  appear on semvertag.modern-python.org.

Beyond the recipe, and the reason this is chore: and not docs: release.yml both
hard-required planning/releases/<tag>.md for every stable tag and sourced the
Release body from it, so deleting planning/ would have failed every future stable
release. The gate is gone and the body is now GitHub's generated notes, matching
modern-di's post-migration workflow, which dropped the same gate in 1ea74ee
(modern-python/modern-di#449). This retires the mandatory-curated-notes policy; a
release wanting prose is edited after the fact with gh release edit. modern-di's
file was NOT copied verbatim: semvertag's release.yml also owns the Float major tag
step that force-updates the v0 ref action consumers pin, which modern-di has no
equivalent of. Copying verbatim would have deleted it and broken every
uses: modern-python/semvertag@v0 on the next release, so only the notes handling
was aligned.

Verification: just lint-ci clean, just test 474 passed at 100% branch coverage,
just docs-build strict green with no adr/ output, lychee --offline 0 errors, and no
file outside .git references planning/, architecture/, check-planning, check-links
or convention-version.
The sibling commit on this branch deletes planning/, so the exclusion now
names a directory that does not exist.

Dropping the key rather than leaving an empty list: Context7's schema
(https://context7.com/schema/context7.json) declares no required properties
and gives excludeFolders a default of [], so an absent key and an empty list
are equivalent. Absent matches the repos that never carried the line.
@lesnik512
lesnik512 merged commit 332018a into main Sep 6, 2026
8 checks passed
@lesnik512
lesnik512 deleted the chore/migrate-off-planning branch September 6, 2026 19:14
@lesnik512 lesnik512 changed the title chore(context7): drop the stale planning/ exclusion chore: migrate off the planning/ convention Sep 6, 2026
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