docs: clarify `chore:` vs `feat:` for internal-infrastructure commits

quartermaster commented

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

Owner

Why

Today's v0.2.1 dogfood cut hit a bump-escalation: cut as v0.3.0 instead of v0.2.1 because PR #6's commit subject was feat(workflows): toolkit's own consumer workflows for v0.2.1+ dogfood. The feat: type triggered MINOR bump.

But the dogfood workflows are INTERNAL substrate — from an external-consumer POV (cellblock, tmux-tell, future projects), nothing changed. The 4 reusable workflows (_release-prep.yml etc.) existed since v0.1.0; PR #6 only added the toolkit's OWN consumer-shape wrappers that fire on the toolkit's own pushes. External consumers don't reference them.

The right commit type would have been chore: (or refactor: if framed as internal-cleanup-of-bootstrap-state). The toolkit's cc_bump_level_from_subject correctly handled feat: as minor; the human gap was the type choice.

Failure mode

Today: cut produced v0.3.0 prematurely. Recovery: closed prep PR + operator re-dispatched with bump_override: patch. Worked, but the recovery is operator-friction that documentation can save.

Proposed addition to `docs/conventions.md`

A new subsection under "Conventional commits" titled something like "When to use chore: for internal-infrastructure changes":

Use chore: (not feat:) for:

Internal infrastructure that doesn't change the consumer-facing surface (the toolkit's own dogfood workflows, internal scripts, build/test plumbing)

Bootstrap state cleanup that wires the toolkit to operate on its own substrate

Repository hygiene (README updates, internal docs, infrastructure refactoring)

Use feat: only when:

A new user-facing surface lands (new config option, new reusable workflow, new script flag)

An existing consumer would observe new behavior on next pin-bump

Test: "Would a consumer pinning to this version observe ANY new capability or behavior change?" If no → chore:. If yes → feat:.

Optionally fold into an ADR documenting the decision shape with the worked instance.

Disposition lean

(A) Single section addition to docs/conventions.md — small scope, ships in next patch or minor cut.

Cross-tracker

Worked instance: today's v0.2.1 cut escalated to v0.3.0 unexpectedly (closed prep PR + re-dispatched)
Sibling: release-toolkit#9 + #10 (other fail-loud-when-environment-mismatch fixes that shipped in v0.2.1)

— QM, 2026-06-24, surfaced from v0.2.1 dogfood cut escalation.

## Why Today's v0.2.1 dogfood cut hit a bump-escalation: cut as v0.3.0 instead of v0.2.1 because PR #6's commit subject was `feat(workflows): toolkit's own consumer workflows for v0.2.1+ dogfood`. The `feat:` type triggered MINOR bump. But the dogfood workflows are INTERNAL substrate — from an external-consumer POV (cellblock, tmux-tell, future projects), nothing changed. The 4 reusable workflows (`_release-prep.yml` etc.) existed since v0.1.0; PR #6 only added the toolkit's OWN consumer-shape wrappers that fire on the toolkit's own pushes. External consumers don't reference them. The right commit type would have been `chore:` (or `refactor:` if framed as internal-cleanup-of-bootstrap-state). The toolkit's `cc_bump_level_from_subject` correctly handled `feat:` as minor; the human gap was the type choice. ## Failure mode Today: cut produced v0.3.0 prematurely. Recovery: closed prep PR + operator re-dispatched with `bump_override: patch`. Worked, but the recovery is operator-friction that documentation can save. ## Proposed addition to `docs/conventions.md` A new subsection under "Conventional commits" titled something like "When to use `chore:` for internal-infrastructure changes": > Use `chore:` (not `feat:`) for: > - **Internal infrastructure** that doesn't change the consumer-facing surface (the toolkit's own dogfood workflows, internal scripts, build/test plumbing) > - **Bootstrap state cleanup** that wires the toolkit to operate on its own substrate > - **Repository hygiene** (README updates, internal docs, infrastructure refactoring) > > Use `feat:` only when: > - A new user-facing surface lands (new config option, new reusable workflow, new script flag) > - An existing consumer would observe new behavior on next pin-bump > > Test: "Would a consumer pinning to this version observe ANY new capability or behavior change?" If no → `chore:`. If yes → `feat:`. Optionally fold into an ADR documenting the decision shape with the worked instance. ## Disposition lean (A) Single section addition to `docs/conventions.md` — small scope, ships in next patch or minor cut. ## Cross-tracker - Worked instance: today's v0.2.1 cut escalated to v0.3.0 unexpectedly (closed prep PR + re-dispatched) - Sibling: release-toolkit#9 + #10 (other fail-loud-when-environment-mismatch fixes that shipped in v0.2.1) — QM, 2026-06-24, surfaced from v0.2.1 dogfood cut escalation.

quartermaster referenced this issue from a commit

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

docs(CHANGELOG): clean up v0.2.1 section per substrate-care discipline

quartermaster referenced this issue from a commit

2026-06-24 21:27:00 +02:00

docs(conventions): chore: vs feat: for internal-infra changes — closes #14

quartermaster referenced this issue from a pull request that will close it,

2026-06-24 21:27:13 +02:00

docs(conventions): chore: vs feat: for internal-infra changes — closes #14 #27

quartermaster referenced this issue from a commit

2026-06-24 21:34:27 +02:00

docs(conventions): chore: vs feat: for internal-infra changes — closes #14

quartermaster closed this issue

2026-06-24 21:34:41 +02:00

quartermaster referenced this issue

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

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

forgejo-actions referenced this issue

2026-06-24 21:48:01 +02:00

chore(release): v0.4.0 #31

quartermaster referenced this issue from a commit

2026-06-24 21:50:09 +02:00

fix(changelog.d): correct kind 'added' → 'internal' for #14 docs fragment

quartermaster referenced this issue

2026-06-24 21:50:26 +02:00

fix(changelog.d): correct kind 'added' → 'internal' for #14 docs fragment (v0.3.1 bump correction) #32

forgejo-actions referenced this issue

2026-06-24 21:52:59 +02:00

chore(release): v0.3.1 #33

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 21:53:58 +02:00

workflows / scripts: lint fragment-kind vs change-type mismatch (observability over author-discipline) #35

quartermaster commented

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

Author

Owner

AC tick (pre-merge bookkeeping, post-merge catchup)

Shipped via PR #27 (commit 208eba4) + corrected via PR #32 (commit 533ab44) for the fragment-kind mismatch surfaced in the same slice.

Disposition (A) ACs

New ### Choosing chore: vs feat: for internal-infrastructure changes subsection added to docs/conventions.md under "Conventional commits" — landed in 208eba4
Consumer-facing-surface test stated as the discriminator ("Would a consumer pinning to this version observe ANY new capability or behavior change on their next pin-bump?")
Worked-instance reference included (v0.2.1 cut-escalation from PR #6 feat(workflows): → unintended v0.3.0 bump)
refactor: as the right alternative named for substantial internal restructuring (emits as ### Internal, no bump)

Deferred-conditional (surfaced post-merge, follow-up tracked)

Discipline-sibling for fragment-kind: the test applies to BOTH commit-subjects AND fragment-kind naming. I violated the fragment-kind sibling in the SAME slice (named slice 2's fragment .added.md → bump-escalation to v0.4.0; recovered via PR #32 → .internal.md). Tracked as #34 for the "state test once, map onto both surfaces" docs restructure per Surveyor 85cc framing.
Adopter-friendly worked-instance: current text cites internal PR #6 / #14 refs that external adopters can't follow. Tracked as #30; will fold into #34's restructure since both touch the same subsection.
Observability-not-discipline prevention: fragment-kind vs change-type lint as the next layer of defense per Surveyor 85cc. Tracked as #35; v0.4.x-class candidate.

Cross-tracker confirmation

Original sibling: #9 + #10 — both shipped in v0.2.1 ✓
This issue's worked instance (v0.2.1 cut → v0.3.0 escalation): the PR #32 hot-recovery validates the discipline operates as designed (the discipline caught its own author in the same session — load-bearing not just existing).

Closed via PR #27 merge. AC + deferred-conditional summary recorded.

— QM, 2026-06-24, v0.3.1 post-publish AC-tick pass.

## AC tick (pre-merge bookkeeping, post-merge catchup) Shipped via PR #27 (commit 208eba4) + corrected via PR #32 (commit 533ab44) for the fragment-kind mismatch surfaced in the same slice. ### Disposition (A) ACs - [x] **New `### Choosing chore: vs feat: for internal-infrastructure changes` subsection added to `docs/conventions.md`** under "Conventional commits" — landed in 208eba4 - [x] **Consumer-facing-surface test stated** as the discriminator (*"Would a consumer pinning to this version observe ANY new capability or behavior change on their next pin-bump?"*) - [x] **Worked-instance reference included** (v0.2.1 cut-escalation from PR #6 `feat(workflows):` → unintended v0.3.0 bump) - [x] **`refactor:` as the right alternative** named for substantial internal restructuring (emits as `### Internal`, no bump) ### Deferred-conditional (surfaced post-merge, follow-up tracked) - [x] *Discipline-sibling for fragment-kind:* the test applies to BOTH commit-subjects AND fragment-kind naming. I violated the fragment-kind sibling in the SAME slice (named slice 2's fragment `.added.md` → bump-escalation to v0.4.0; recovered via PR #32 → `.internal.md`). Tracked as **#34** for the "state test once, map onto both surfaces" docs restructure per Surveyor 85cc framing. - [x] *Adopter-friendly worked-instance:* current text cites internal PR #6 / #14 refs that external adopters can't follow. Tracked as **#30**; will fold into #34's restructure since both touch the same subsection. - [x] *Observability-not-discipline prevention:* fragment-kind vs change-type lint as the next layer of defense per Surveyor 85cc. Tracked as **#35**; v0.4.x-class candidate. ### Cross-tracker confirmation - Original sibling: #9 + #10 — both shipped in v0.2.1 ✓ - This issue's worked instance (v0.2.1 cut → v0.3.0 escalation): the PR #32 hot-recovery validates the discipline operates as designed (the discipline caught its own author in the same session — load-bearing not just existing). Closed via PR #27 merge. AC + deferred-conditional summary recorded. — QM, 2026-06-24, v0.3.1 post-publish AC-tick pass.

quartermaster referenced this issue

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

workflows: _release-draft.yml@v0.2.0 fails on prep-PR merge; needs diagnostic #16

quartermaster referenced this issue

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

tests: cc_parse_subject empty-scope tests fail on bats 5.2.37+ (lines[] empty-line collapse) #18

quartermaster referenced this issue

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

v0.3 — tmux-tell migration enablement (5 config additions) #4

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