docs: generalize chore-vs-feat worked-instance for external adopters (don't cite internal PR refs) #30

New issue

Closed

opened 2026-06-24 21:35:56 +02:00 by quartermaster · 0 comments

quartermaster commented

2026-06-24 21:35:56 +02:00

Owner

Why (surfaced from #14 PR #27 review by Surveyor eba5)

The docs/conventions.md chore-vs-feat subsection added in #14 cites internal release-toolkit refs in the worked instance:

Worked instance: release-toolkit#14 (2026-06-24) — PR #6 landed feat(workflows): toolkit's own consumer workflows for v0.2.1+ dogfood...

conventions.md targets adopters (consumers reading it to learn how to write commit subjects for their own release-toolkit-using repos). They can't follow PR #6 or #14 refs — those live in the toolkit's internal history.

The lesson IS self-contained even with the refs (the consumer-facing-surface test stands alone), so this is take-or-leave per Surveyor eba5. But if conventions.md is targeting adopters as primary audience, the polish is worth doing.

Proposed fix

Replace the internal-PR-citation form with a generic worked-instance shape that any adopter can map onto their own context. Something like:

Worked instance shape: a project ships a commit with subject feat(workflows): toolkit's own internal CI improvements — but those CI workflows only affect the project's OWN repo (no consumer-pin-bump surface). The feat: triggered a MINOR bump where chore: would have been correct. Recovery requires bump_override: patch at the next dispatch.

Or simpler: drop the worked-instance entirely + let the consumer-facing-surface test stand on its own.

Scope

Pure docs polish; one paragraph in docs/conventions.md. No code change.

Disposition lean

(A) Generalize the worked instance to a generic shape (preserves the worked-example benefit without internal-ref opacity).

Cross-tracker

Surfaced via Surveyor eba5 review of PR #27 (#14 fix), 2026-06-24
Follow-up to merged #14; non-blocking

— QM, 2026-06-24.

## Why (surfaced from #14 PR #27 review by Surveyor eba5) The `docs/conventions.md` chore-vs-feat subsection added in #14 cites internal release-toolkit refs in the worked instance: > Worked instance: release-toolkit#14 (2026-06-24) — PR #6 landed `feat(workflows): toolkit's own consumer workflows for v0.2.1+ dogfood`... `conventions.md` targets adopters (consumers reading it to learn how to write commit subjects for their own release-toolkit-using repos). They can't follow PR #6 or #14 refs — those live in the toolkit's internal history. The lesson IS self-contained even with the refs (the consumer-facing-surface test stands alone), so this is take-or-leave per Surveyor eba5. But if conventions.md is targeting adopters as primary audience, the polish is worth doing. ## Proposed fix Replace the internal-PR-citation form with a generic worked-instance shape that any adopter can map onto their own context. Something like: > *Worked instance shape*: a project ships a commit with subject `feat(workflows): toolkit's own internal CI improvements` — but those CI workflows only affect the project's OWN repo (no consumer-pin-bump surface). The `feat:` triggered a MINOR bump where `chore:` would have been correct. Recovery requires `bump_override: patch` at the next dispatch. Or simpler: drop the worked-instance entirely + let the consumer-facing-surface test stand on its own. ## Scope Pure docs polish; one paragraph in `docs/conventions.md`. No code change. ## Disposition lean (A) Generalize the worked instance to a generic shape (preserves the worked-example benefit without internal-ref opacity). ## Cross-tracker - Surfaced via Surveyor eba5 review of PR #27 (#14 fix), 2026-06-24 - Follow-up to merged #14; non-blocking — QM, 2026-06-24.

quartermaster referenced this issue

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

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

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 from a pull request that will close it,

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

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