From ffe0ced431c3a343b6fc2bc1ebe1f6098ed94b0f Mon Sep 17 00:00:00 2001 From: Artur Shiriev Date: Wed, 8 Jul 2026 09:58:18 +0300 Subject: [PATCH] docs(planning): retire "bundle" wording across planning prose Sweep the pre-2.0.0 word "bundle" to "change"/"change file"/"folder" in 6 historical change files and the CI step name. Accuracy-preserving: "folder" where it names the retired directory mechanism, "change" otherwise. Keep 3 coherence-required uses in the upgrade spec (the before/after definition, "rejects folder bundles", and a verbatim quote of the old CLAUDE.md text). Co-Authored-By: Claude Opus 4.8 (1M context) --- .github/workflows/planning.yml | 2 +- ...2026-06-28.02-adopt-planning-convention.md | 16 +++--- .../2026-06-30.02-docs-ogimage-rollout.md | 2 +- .../2026-06-30.05-profile-badge-tables.md | 2 +- .../changes/2026-07-02.04-aiohttp-surfaces.md | 4 +- .../changes/2026-07-05.01-docs-lockup-hero.md | 4 +- .../2026-07-08.01-sweep-bundle-wording.md | 55 +++++++++++++++++++ 7 files changed, 70 insertions(+), 15 deletions(-) create mode 100644 planning/changes/2026-07-08.01-sweep-bundle-wording.md diff --git a/.github/workflows/planning.yml b/.github/workflows/planning.yml index ccf4116..408c4c1 100644 --- a/.github/workflows/planning.yml +++ b/.github/workflows/planning.yml @@ -14,5 +14,5 @@ jobs: uses: astral-sh/setup-uv@v7 with: python-version: "3.11" - - name: Validate planning bundles + - name: Validate planning changes run: uv run python planning/index.py --check diff --git a/planning/changes/2026-06-28.02-adopt-planning-convention.md b/planning/changes/2026-06-28.02-adopt-planning-convention.md index e5e23d8..834dbdf 100644 --- a/planning/changes/2026-06-28.02-adopt-planning-convention.md +++ b/planning/changes/2026-06-28.02-adopt-planning-convention.md @@ -1,5 +1,5 @@ --- -summary: Adopt lesnik512/planning-convention v1.1.1 at the repo root and migrate docs/superpowers/ into planning/ change bundles plus a lazy architecture/ truth home. +summary: Adopt lesnik512/planning-convention v1.1.1 at the repo root and migrate docs/superpowers/ into planning/ change folders plus a lazy architecture/ truth home. --- # Design: Adopt the planning convention and migrate docs/superpowers/ @@ -10,7 +10,7 @@ Apply the portable two-axis planning convention from [`lesnik512/planning-convention`](https://github.com/lesnik512/planning-convention) (v1.1.1) to this repo via its `APPLY.md` flow, as a **fresh adoption**, and migrate the existing planning material under `docs/superpowers/` into the -convention's `planning/changes/` bundles. The convention's `architecture/` and +convention's `planning/changes/` folders. The convention's `architecture/` and `planning/` trees live at the **repo root**, where the convention's prose, `index.py` path resolution, and `APPLY.md` §5 all assume they live. @@ -35,10 +35,10 @@ validator, a generated index, a Quick-path lane decision, and a living delete `docs/superpowers/`. Matches the convention verbatim with no prose rewrites. Nothing lands under `docs/`, so MkDocs never publishes it and the `exclude_docs: superpowers/` rule is retired. -2. **community-health bundle: `change.md`.** The `org-community-health-defaults` - plan (06-24) has no design doc; the bundle is given a condensed `change.md` as +2. **community-health change: `change.md`.** The `org-community-health-defaults` + plan (06-24) has no design doc; the change is given a condensed `change.md` as its spec. The substantial shipped `plan.md` is **kept alongside** it (the - validator allows `change.md` + `plan.md` in one bundle) so the detailed + validator allows `change.md` + `plan.md` in one folder) so the detailed shipped record is preserved in-repo rather than only in git history. *(Open for confirmation at the review gate: keep both, or fold the plan into change.md and drop plan.md.)* @@ -83,7 +83,7 @@ frontmatter. Migration is **structural only**: each document's existing body and headings are preserved (the templates are starting points, not mandatory section names; the validator enforces only `summary:` on specs). -| Bundle | Lane | Source | Frontmatter change | +| Change | Lane | Source | Frontmatter change | |---|---|---|---| | `2026-06-24.01-promotion-strategy` | design-only (pending) | `specs/2026-06-24-promotion-strategy-design.md` → `design.md` | add `summary:`; drop the `**Date/Status/Owner/Scope**` block (date derived from dir; `status`/`owner` are not convention fields); keep Scope as a prose line | | `2026-06-24.02-org-community-health-defaults` | `change.md` + `plan.md` | `plans/2026-06-24-org-community-health-defaults.md` → `plan.md`; new `change.md` from the plan intro | plan.md: none; change.md: `summary:` | @@ -94,7 +94,7 @@ The `.NN` counter on 06-24 places the strategic umbrella (`promotion-strategy`) at `.01` and its implementation (`community-health-defaults`) at `.02`. `launch-playbook.md` moves to `planning/launch-playbook.md` as a loose -operational asset — it cannot live inside a bundle (the validator rejects any +operational asset — it cannot live inside a change folder (the validator rejects any file other than `design.md`/`plan.md`/`change.md` there). Its "excluded via `exclude_docs`" note is updated, since it now sits at the repo root and is never published. After migration, `docs/superpowers/` is deleted. @@ -144,7 +144,7 @@ Local edits to these are intentionally not made — they are owned upstream. ## Risk -- **Plan-without-design bundle fails validation** (community-health). Mitigated by +- **Plan-without-design change fails validation** (community-health). Mitigated by decision 2 (write a `change.md`). - **Stale references** to `docs/superpowers/` elsewhere in the repo (e.g. `mkdocs.yml`, CLAUDE.md, launch-playbook prose). Mitigated by the `git grep` diff --git a/planning/changes/2026-06-30.02-docs-ogimage-rollout.md b/planning/changes/2026-06-30.02-docs-ogimage-rollout.md index 42cfdf3..114aeb5 100644 --- a/planning/changes/2026-06-30.02-docs-ogimage-rollout.md +++ b/planning/changes/2026-06-30.02-docs-ogimage-rollout.md @@ -12,7 +12,7 @@ GitHub/Slack/X/etc. show the branded card instead of nothing. Each docs repo self-hosts its card (`docs/assets/social-card.png`, copied from this repo's `brand/projects//social-card.png`) and gains a small MkDocs Material template override that emits the Open Graph + Twitter meta. Shipped as **seven -PRs**, one per docs repo. This planning bundle lives in `.github` (the org/brand +PRs**, one per docs repo. This planning change lives in `.github` (the org/brand home where the cards are generated); no code changes land in `.github`. ## Motivation diff --git a/planning/changes/2026-06-30.05-profile-badge-tables.md b/planning/changes/2026-06-30.05-profile-badge-tables.md index 6e875d9..7c6ed97 100644 --- a/planning/changes/2026-06-30.05-profile-badge-tables.md +++ b/planning/changes/2026-06-30.05-profile-badge-tables.md @@ -23,7 +23,7 @@ maintainer wants the org landing page to read as metrics-forward, matching the badge strips already present in every repo README (`modern-di`'s README even carries a project table already, so the pattern has internal precedent). -Two research sweeps (saved findings in this bundle's history) established the +Two research sweeps (saved findings in this change's history) established the guardrails: - No surveyed org (astral-sh, pydantic, encode, prisma, grafana, langchain, vercel, supabase, …) puts a per-repo badge **table** in its org profile; the diff --git a/planning/changes/2026-07-02.04-aiohttp-surfaces.md b/planning/changes/2026-07-02.04-aiohttp-surfaces.md index c66622f..639c19d 100644 --- a/planning/changes/2026-07-02.04-aiohttp-surfaces.md +++ b/planning/changes/2026-07-02.04-aiohttp-surfaces.md @@ -27,7 +27,7 @@ PyPI. Progress so far: placement — `modern-di-aiohttp` now lands in its alphabetical slot. Future integrations slot in alphabetically, no insertion-point decision needed. -The brand mark and assets are already done and merged (bundle +The brand mark and assets are already done and merged (change `2026-07-02.02-aiohttp-brand`, PR #31) — `brand/projects/modern-di-aiohttp/` exists on `main`. @@ -103,6 +103,6 @@ gh repo edit modern-python/modern-di-aiohttp \ ## Notes -Ship as one PR (this bundle finalized + the two file edits) once unblocked; the +Ship as one PR (this change finalized + the two file edits) once unblocked; the GitHub-settings step is out-of-repo and applied alongside. Independent of any other pending work. diff --git a/planning/changes/2026-07-05.01-docs-lockup-hero.md b/planning/changes/2026-07-05.01-docs-lockup-hero.md index ed2d9ad..423c9a8 100644 --- a/planning/changes/2026-07-05.01-docs-lockup-hero.md +++ b/planning/changes/2026-07-05.01-docs-lockup-hero.md @@ -147,7 +147,7 @@ Add a short "docs home page hero" note to `architecture/brand-marks.md` (beside the existing README-banner note), recording that docs sites vendor the lockup as a centered `.mp-hero` — contrasted with the README `` hotlink approach — and add a one-line pointer in `brand/README.md`'s per-project marks section. This -promotion rides in the same PR as the planning bundle (this `.github` repo's +promotion rides in the same PR as the planning change (this `.github` repo's slice of the rollout). ## Rollout @@ -161,7 +161,7 @@ Full lane, executed **pilot then replicate**: 3. **`modern-di`** last, once its branch is free. Each target repo is a separate PR in its own repo. This `.github` repo carries -its own PR for the planning bundle + architecture/brand-README docs (step 4). +its own PR for the planning change + architecture/brand-README docs (step 4). ## Testing diff --git a/planning/changes/2026-07-08.01-sweep-bundle-wording.md b/planning/changes/2026-07-08.01-sweep-bundle-wording.md new file mode 100644 index 0000000..e2bc735 --- /dev/null +++ b/planning/changes/2026-07-08.01-sweep-bundle-wording.md @@ -0,0 +1,55 @@ +--- +summary: Retire the pre-2.0.0 word "bundle" from planning prose — sweep it to "change"/"change file"/"folder" across 6 historical change files and the CI step name, keeping only the 3 coherence-required uses in the upgrade spec. +--- + +# Change: Retire "bundle" wording across planning prose + +## What & why + +Convention 2.0.0 renamed change *bundles* (folders) to flat change *files*. +The merged upgrade (#39) fixed the living-truth surfaces (`CLAUDE.md`, +`architecture/README.md`, `planning/README.md`), but the word "bundle" lingered +in six historical change files and one CI step name. This sweep retires it +everywhere it still reads as the change artifact, so the docs speak the 2.0.0 +vocabulary consistently. + +Accuracy-preserving (maintainer's ruling): use "folder" where the text names the +retired directory mechanism (a folder that held `change.md` + `plan.md`), and +"change"/"change file" where it just means the change. Three uses are +deliberately **kept** — they would otherwise become incoherent or falsify a +quote. + +## Scope + +Swept to "change"/"change file"/"folder": + +- `.github/workflows/planning.yml` — CI step `Validate planning bundles` → `Validate planning changes`. +- `planning/changes/2026-06-28.02-adopt-planning-convention.md` — 8 uses; "folder" where it names the v1.1.1 directory (e.g. "in one folder"), else "change". +- `planning/changes/2026-06-30.02-docs-ogimage-rollout.md` — 1. +- `planning/changes/2026-06-30.05-profile-badge-tables.md` — 1. +- `planning/changes/2026-07-02.04-aiohttp-surfaces.md` — 2. +- `planning/changes/2026-07-05.01-docs-lockup-hero.md` — 2. + +**Kept (intentional):** + +- `planning/changes/2026-07-07.02-upgrade-planning-convention-2.0.md` — 3 uses: + the before→after definition ("change *bundles* become flat *files*"), "rejects + folder bundles", and a verbatim quote of the pre-change `CLAUDE.md` text + ("create a bundle under …"). That file's subject is retiring bundles, so it + necessarily names the old thing. +- `architecture/site-branding.md` — "bundled Jost TTF" is a font reference, not + planning vocabulary. + +## Verification + +- `just check-planning` prints `planning: OK`. +- After the sweep, `grep -rni 'bundle' --include='*.md' --include='*.yml'` over + the repo (excluding `site/`) returns only: the 3 kept uses in the upgrade + spec, the Jost-font line, and this change file's own descriptive mentions. +- No folder diagrams or `change.md`+`plan.md` references were altered — only the + word "bundle" changed. + +## Notes + +Pure documentation vocabulary; no code, no tests, no assets. Multi-file only +because "bundle" was scattered; each edit is a one-word substitution.