docs(register): reduce internal jargon in adopter-facing workflow YAML + script top-of-file comments #313

New issue

Closed

opened 2026-07-03 12:14:45 +02:00 by bosun · 0 comments

bosun commented

2026-07-03 12:14:45 +02:00

Owner

Motivation

Lookout Codeberg cold-read (bus 45db) flagged: .forgejo/workflows/*.yml and scripts/*.sh comments carry too much incident archaeology + internal jargon for public first-glance readers. Terms like substrate-honest, path-alpha, mechanism-of-touch, operator directive show up in files adopters will copy-paste. As a maintainer, useful; as a newcomer, confusing.

Scope

Reusable workflows (reusable-release.yml, reusable-manifest-check.yml, reusable-changelog-*.yml) — top-of-file # documentation blocks + inline comments
Scripts adopters wire directly (scripts/release-decide.sh, scripts/release-prep.sh, scripts/draft-release.sh, scripts/manifest-check.sh)
KEEP internal-jargon comments where the file is internal-review-target (bats tests, dev-tools/, scripts/lib/ internal helpers)
Move incident-archaeology comments to ADRs (referenced by ADR number, e.g. # See ADR-0007 for path-α rationale)

Set J context

Must land before v1.0.0. QM substrate-familiar — knows which comments are load-bearing context vs archaeology-nostalgia.

## Motivation Lookout Codeberg cold-read (bus 45db) flagged: `.forgejo/workflows/*.yml` and `scripts/*.sh` comments carry too much incident archaeology + internal jargon for public first-glance readers. Terms like `substrate-honest`, `path-alpha`, `mechanism-of-touch`, `operator directive` show up in files adopters will copy-paste. As a maintainer, useful; as a newcomer, confusing. ## Scope - Reusable workflows (`reusable-release.yml`, `reusable-manifest-check.yml`, `reusable-changelog-*.yml`) — top-of-file `# ` documentation blocks + inline comments - Scripts adopters wire directly (`scripts/release-decide.sh`, `scripts/release-prep.sh`, `scripts/draft-release.sh`, `scripts/manifest-check.sh`) - KEEP internal-jargon comments where the file is internal-review-target (bats tests, dev-tools/, scripts/lib/ internal helpers) - Move incident-archaeology comments to ADRs (referenced by ADR number, e.g. `# See ADR-0007 for path-α rationale`) ## Set J context Must land before v1.0.0. QM substrate-familiar — knows which comments are load-bearing context vs archaeology-nostalgia.

bosun added the

priority/medium

size/M

kind/docs

labels

2026-07-03 12:14:45 +02:00