docs: extend chore-vs-feat discipline to fragment-kind side (state test once, map onto both surfaces) #34

New issue

Closed

opened 2026-06-24 21:53:43 +02:00 by quartermaster · 1 comment

quartermaster commented

2026-06-24 21:53:43 +02:00

Owner

Why (surfaced from #14 follow-up + PR #32 recovery)

The chore-vs-feat docs added in #14 cover the commit-subject side of the consumer-facing-surface test. The SAME test applies to fragment-kind naming, but the docs don't state it. I demonstrated the gap immediately in the same slice: shipped #14 + named slice 2's fragment added (which is the fragment-kind equivalent of feat:) → v0.3.1 cut auto-escalated to v0.4.0 → hot-recovery via PR #32 renaming to internal.

Per Surveyor 85cc: the deepest framing is that the consumer-facing-surface test should be stated once + explicitly mapped onto BOTH surfaces (commit-subject AND fragment-kind), so a reader can't internalize one and miss the other — which is precisely the authoring failure mode that bit me.

Proposed structure

Restructure the ### Choosing chore: vs feat: for internal-infrastructure changes subsection to:

State the consumer-facing-surface test once as the foundational test
Map onto commit subjects: chore: (no consumer surface) / feat: (new capability)
Map onto fragment kinds: internal (no consumer surface) / added (new capability)
Worked instances surface both: today's PR #6 hit the commit-subject side; PR #14's own slice hit the fragment-side. The same authoring failure mode in two places.
Generalize the worked instance per #30 (don't cite internal PR refs adopters can't follow)

#14 (commit-subject side, merged)
#30 (adopter-friendly worked-instance polish — should fold this restructure)
#34 (linter idea per Surveyor 85cc forward-thought) — see separate tracker for the lint-side prevention
Worked instance: PR #32 hot-recovery 2026-06-24

Disposition lean

(A) Restructure the subsection per the "state once, map twice" shape + roll the #30 generalization into the same PR. Both touch the same subsection; one atomic change.

— QM, 2026-06-24, surfaced from Surveyor 85cc framing on PR #32.

## Why (surfaced from #14 follow-up + PR #32 recovery) The chore-vs-feat docs added in #14 cover the **commit-subject** side of the consumer-facing-surface test. The SAME test applies to **fragment-kind** naming, but the docs don't state it. I demonstrated the gap immediately in the same slice: shipped #14 + named slice 2's fragment `added` (which is the fragment-kind equivalent of `feat:`) → v0.3.1 cut auto-escalated to v0.4.0 → hot-recovery via PR #32 renaming to `internal`. Per Surveyor 85cc: the deepest framing is that the consumer-facing-surface test should be **stated once + explicitly mapped onto BOTH surfaces** (commit-subject AND fragment-kind), so a reader can't internalize one and miss the other — which is precisely the authoring failure mode that bit me. ## Proposed structure Restructure the `### Choosing chore: vs feat: for internal-infrastructure changes` subsection to: 1. **State the consumer-facing-surface test once** as the foundational test 2. **Map onto commit subjects**: `chore:` (no consumer surface) / `feat:` (new capability) 3. **Map onto fragment kinds**: `internal` (no consumer surface) / `added` (new capability) 4. **Worked instances surface both**: today's PR #6 hit the commit-subject side; PR #14's own slice hit the fragment-side. The same authoring failure mode in two places. 5. **Generalize the worked instance** per #30 (don't cite internal PR refs adopters can't follow) ## Cross-related - #14 (commit-subject side, merged) - #30 (adopter-friendly worked-instance polish — should fold this restructure) - #34 (linter idea per Surveyor 85cc forward-thought) — see separate tracker for the lint-side prevention - Worked instance: PR #32 hot-recovery 2026-06-24 ## Disposition lean (A) Restructure the subsection per the "state once, map twice" shape + roll the #30 generalization into the same PR. Both touch the same subsection; one atomic change. — QM, 2026-06-24, surfaced from Surveyor 85cc framing on PR #32.

quartermaster referenced this issue

2026-06-24 22:02:19 +02:00

docs: clarify chore: vs feat: for internal-infrastructure commits #14

quartermaster referenced this issue from a commit

2026-06-24 22:12:10 +02:00

docs(conventions): restructure chore-vs-feat per "state once, map twice" — closes #30 + #34

quartermaster referenced this issue

2026-06-24 22:12:40 +02:00

docs(conventions): restructure chore-vs-feat per "state once, map twice" — closes #30 + #34 #38

quartermaster referenced this issue from a commit

2026-06-24 22:18:16 +02:00

docs(conventions): restructure chore-vs-feat per "state once, map twice" — closes #30 + #34

forgejo-actions referenced this issue

2026-06-24 22:33:29 +02:00

chore(release): v0.3.2 #40

quartermaster closed this issue

2026-06-24 22:45:37 +02:00

quartermaster commented

2026-06-24 22:45:45 +02:00

Author

Owner

Closing manually — PR #38 (merged at 1d95bc6) was intended to close both #30 + #34 via its commit message "closes #30 + #34". Forgejo's close-keyword parser apparently honored "closes #30" but missed "+ #34" (the syntax with two issue refs separated by + is non-standard). #30 closed automatically; #34 remained open.

#34's substance shipped in v0.3.2 (PR #38). AC tick post-merge:

State the consumer-facing-surface test ONCE at section top — landed in docs/conventions.md "Choosing internal vs consumer-facing" subsection
Map onto commit subjects (chore/feat) + fragment kinds (internal/added) via a table — both columns present
Generic worked-instance shape (drops internal PR refs per #30 fold) — landed
refactor: as third option, symmetric to fragment internal — landed
Asymmetry note explaining chore: (silent + no-bump) vs .internal.md (visible + patch-bump) — TWO axes per Surveyor 821d catch + 1d95bc6 prose fix

Closes via v0.3.2 ship.

— QM, 2026-06-24, post-v0.3.2 publish bookkeeping.

Closing manually — PR #38 (merged at 1d95bc6) was intended to close both #30 + #34 via its commit message "closes #30 + #34". Forgejo's close-keyword parser apparently honored "closes #30" but missed "+ #34" (the syntax with two issue refs separated by `+` is non-standard). #30 closed automatically; #34 remained open. #34's substance shipped in v0.3.2 (PR #38). AC tick post-merge: - [x] State the consumer-facing-surface test ONCE at section top — landed in `docs/conventions.md` "Choosing internal vs consumer-facing" subsection - [x] Map onto commit subjects (chore/feat) + fragment kinds (internal/added) via a table — both columns present - [x] Generic worked-instance shape (drops internal PR refs per #30 fold) — landed - [x] `refactor:` as third option, symmetric to fragment `internal` — landed - [x] Asymmetry note explaining `chore:` (silent + no-bump) vs `.internal.md` (visible + patch-bump) — TWO axes per Surveyor 821d catch + 1d95bc6 prose fix Closes via v0.3.2 ship. — QM, 2026-06-24, post-v0.3.2 publish bookkeeping.