chore: audit-cleanup of .keep files (drop unused, document load-bearing ones) #151

New issue

Closed

opened 2026-06-27 01:34:19 +02:00 by quartermaster · 0 comments

quartermaster commented

2026-06-27 01:34:19 +02:00

Owner

The current state

Four .keep files exist in the repo, surfaced during the pre-1.0 audit pass discussion 2026-06-27:

File	Load-bearing?	Action
`tests/.keep`	No — `tests/` has 10+ `.bats` files; the `.keep` was load-bearing only at initial scaffold (commit `3bb81f2`) when the directory was empty	Drop
`changelog.d/.keep`	Yes — `scripts/release-prep.sh:364` calls `delete_fragments changelog.d` after each cut. Without `.keep`, the empty directory disappears from git → first-cut bootstrap fails for fresh consumers + toolkit-self breaks	Keep + document
`examples/go-project/.keep`	Conditional — depends on #152 (examples sprint). If examples get populated → drop (subdirectory has real content). If examples get retired → drop (subdirectory goes away).	Drop in either #152 outcome
`examples/node-project/.keep`	Same conditional as above	Drop in either #152 outcome

Why `changelog.d/.keep` is load-bearing

release-prep.sh invokes delete_fragments changelog.d (line 364) as part of the cut path's CHANGELOG transition. The script DELETES all files matching *.<kind>.md patterns from the directory. If at any point the directory contains only the deleted fragments + no .keep, git would see the directory as gone (git doesn't track empty directories).

The first-cut bootstrap for fresh consumers also depends on changelog.d/.keep being committed — docs/integration.md Step 2 explicitly instructs touch changelog.d/.keep.

Implementation surface

tests/.keep: git rm it
changelog.d/.keep: keep verbatim + add a brief comment in AGENTS.md or operations.md explaining why it must persist
examples/*/.keep: handled by #152 (file-level scope is part of that tracker's resolution)

Estimated scope: trivially small (one file removal + one doc note). Could be bundled with another sprint or shipped solo as a 1-line cleanup.

Composition

Sister tracker #152: examples scope. The examples/*/.keep files' disposition follows from #152's resolution (populate or retire).
Sequencing: this tracker can ship before, after, or bundled with #149 (workflow YAML Unicode) and #150 (script + bats Unicode) — independent of either. Cleanest if bundled with #149/#150's overall pre-1.0 cleanup wave.

What this PR does NOT do

Does NOT touch any other empty-directory-marker files — the audit surfaced ONLY these four; no other .keep / .gitkeep files exist in the repo
Does NOT change release-prep.sh's fragment-deletion behavior — .keep is preserved by the deletion logic (its filename doesn't match the fragment pattern)
Does NOT add an automated guard for "changelog.d/.keep must exist" — could be a follow-up if regressions surface; for now the docs note + the load-bearing context surfaces it for new contributors

Refs

Operator engagement 2026-06-27: identified the .keep files during the broader cleanup discussion + asked for a trackable home
Sister trackers: #149 (workflow YAML Unicode), #150 (script + bats Unicode), #152 (examples sprint)
Pre-1.0 readiness sweep family: this is part of the broader audit-cleanup wave

## The current state Four `.keep` files exist in the repo, surfaced during the pre-1.0 audit pass discussion 2026-06-27: | File | Load-bearing? | Action | |---|---|---| | `tests/.keep` | **No** — `tests/` has 10+ `.bats` files; the `.keep` was load-bearing only at initial scaffold (commit 3bb81f2) when the directory was empty | **Drop** | | `changelog.d/.keep` | **Yes** — `scripts/release-prep.sh:364` calls `delete_fragments changelog.d` after each cut. Without `.keep`, the empty directory disappears from git → first-cut bootstrap fails for fresh consumers + toolkit-self breaks | **Keep + document** | | `examples/go-project/.keep` | Conditional — depends on [#152](https://git.frankenbit.de/frankenbit/release-toolkit/issues/152) (examples sprint). If examples get populated → drop (subdirectory has real content). If examples get retired → drop (subdirectory goes away). | **Drop in either #152 outcome** | | `examples/node-project/.keep` | Same conditional as above | **Drop in either #152 outcome** | ## Why `changelog.d/.keep` is load-bearing `release-prep.sh` invokes `delete_fragments changelog.d` (line 364) as part of the cut path's CHANGELOG transition. The script DELETES all files matching `*.<kind>.md` patterns from the directory. If at any point the directory contains only the deleted fragments + no `.keep`, git would see the directory as gone (git doesn't track empty directories). The first-cut bootstrap for fresh consumers also depends on `changelog.d/.keep` being committed — `docs/integration.md` Step 2 explicitly instructs `touch changelog.d/.keep`. ## Implementation surface - `tests/.keep`: `git rm` it - `changelog.d/.keep`: keep verbatim + add a brief comment in AGENTS.md or operations.md explaining why it must persist - `examples/*/.keep`: handled by [#152](https://git.frankenbit.de/frankenbit/release-toolkit/issues/152) (file-level scope is part of that tracker's resolution) Estimated scope: trivially small (one file removal + one doc note). Could be bundled with another sprint or shipped solo as a 1-line cleanup. ## Composition - **Sister tracker [#152](https://git.frankenbit.de/frankenbit/release-toolkit/issues/152)**: examples scope. The `examples/*/.keep` files' disposition follows from #152's resolution (populate or retire). - **Sequencing**: this tracker can ship before, after, or bundled with [#149](https://git.frankenbit.de/frankenbit/release-toolkit/issues/149) (workflow YAML Unicode) and [#150](https://git.frankenbit.de/frankenbit/release-toolkit/issues/150) (script + bats Unicode) — independent of either. Cleanest if bundled with #149/#150's overall pre-1.0 cleanup wave. ## What this PR does NOT do - **Does NOT touch any other empty-directory-marker files** — the audit surfaced ONLY these four; no other `.keep` / `.gitkeep` files exist in the repo - **Does NOT change `release-prep.sh`'s fragment-deletion behavior** — `.keep` is preserved by the deletion logic (its filename doesn't match the fragment pattern) - **Does NOT add an automated guard** for "changelog.d/.keep must exist" — could be a follow-up if regressions surface; for now the docs note + the load-bearing context surfaces it for new contributors ## Refs - **Operator engagement 2026-06-27**: identified the `.keep` files during the broader cleanup discussion + asked for a trackable home - **Sister trackers**: [#149](https://git.frankenbit.de/frankenbit/release-toolkit/issues/149) (workflow YAML Unicode), [#150](https://git.frankenbit.de/frankenbit/release-toolkit/issues/150) (script + bats Unicode), [#152](https://git.frankenbit.de/frankenbit/release-toolkit/issues/152) (examples sprint) - **Pre-1.0 readiness sweep family**: this is part of the broader audit-cleanup wave

quartermaster referenced this issue

2026-06-27 01:34:48 +02:00

feat(examples): populate examples/go-project and examples/node-project with drop-in consumer setups #152

quartermaster self-assigned this

2026-06-27 02:15:40 +02:00

quartermaster referenced this issue from a commit

2026-06-27 02:23:55 +02:00

chore(cleanup): ASCII-only sweep + .keep audit (#149 + #150 + #151)

quartermaster referenced this issue

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

chore(cleanup): ASCII-only sweep + .keep audit (closes #149 + #150 + #151) #161

quartermaster closed this issue