unom/punktfunk
9
0
Fork 4
Code Issues 15 Pull Requests 2 Actions 1 Packages Projects 1 Releases 59 Wiki Activity

docs: adopt the Punktfunk house style #438

Merged
enricobuehler merged 1 commits from worktree-house-style into main 2026-08-28 21:58:19 +00:00
Conversation 0 Commits 1 Files Changed 5
+276 -3
enricobuehler commented 2026-08-28 21:49:57 +00:00
Owner
Copy Link
Copy Source

Adopts the house style from luxus/punktfunk-house-style — an audit of this tree dated 28 August 2026 — for the three surfaces it covers: commits, CHANGELOG.md, and comments.

What landed

Following the rulebook's own §6 adoption steps:

  • docs/writing.md (new) — the rulebook itself, with a per-PR checklist in §4.
  • CONTRIBUTING.md — a "How to write it" section. It replaces the previous one-line rule, which was "Commit messages end with the Co-Authored-By trailer".
  • AGENTS.md — a Writing standards section ahead of Agent skills, because agents write most of the commits here.
  • .gitea/PULL_REQUEST_TEMPLATE.md — a title comment, because Gitea turns a PR title into the merge subject.
  • CHANGELOG.md — one header paragraph saying new sections take Keep a Changelog form, and older ones stay as they are.

The rules, in short

Commit subjects are type(scope): summary — imperative, 72-character hard cap, no trailing period. The why goes in the body, wrapped at 72; the investigation goes on the PR. New CHANGELOG.md sections use Keep a Changelog categories. A comment states an invariant or a trap, and never enforces a trust boundary on its own — a type, a test or an assertion has to.

One deviation from upstream

The rulebook's §1 body rules say "Co-Authored-By trailers stay." This repo disabled attribution on 2026-08-04, because Gitea 1.27 promotes the trailer to a second participant on the commit page. Our copy inverts that bullet and records why.

That is the only rule changed. Two smaller edits keep the file honest in our tree: §6 now records which adoption steps are done versus ongoing, and one audit sentence about CONTRIBUTING moved to the past tense, because this PR changes the thing it described.

What this deliberately does not do

There is no sweep. The 6,090-line CHANGELOG.md archive, the release notes, and every existing module rustdoc header stay exactly as they are — §6.3 and §6.4 rule that out. No docs/adr/ directory either, because docs/agents/domain.md says that gets created lazily, when a decision actually needs recording.

Checks

  • scripts/ci/check-docs-links.sh — exit 0. Negative control: pointing CONTRIBUTING at a nonexistent file makes it exit 1, so the green is not vacuous.
  • scripts/ci/check-docs-drift.sh — exit 0. Both were re-run after rebasing onto e12f3a62, because the drift script itself moved on main.
  • No Rust changed, so the cargo gates do not apply.
  • The commit is checked against the rules it introduces: subject 37 characters, body wrapped at 72, no trailer.

User-facing fact changed? n/a — this is contributor-facing only. No docs-site page owns writing standards.

Adopts the house style from [luxus/punktfunk-house-style](https://github.com/luxus/punktfunk-house-style) — an audit of this tree dated 28 August 2026 — for the three surfaces it covers: commits, `CHANGELOG.md`, and comments. ## What landed Following the rulebook's own §6 adoption steps: - **`docs/writing.md`** (new) — the rulebook itself, with a per-PR checklist in §4. - **`CONTRIBUTING.md`** — a "How to write it" section. It replaces the previous one-line rule, which was "Commit messages end with the `Co-Authored-By` trailer". - **`AGENTS.md`** — a Writing standards section ahead of Agent skills, because agents write most of the commits here. - **`.gitea/PULL_REQUEST_TEMPLATE.md`** — a title comment, because Gitea turns a PR title into the merge subject. - **`CHANGELOG.md`** — one header paragraph saying new sections take Keep a Changelog form, and older ones stay as they are. ## The rules, in short Commit subjects are `type(scope): summary` — imperative, 72-character hard cap, no trailing period. The *why* goes in the body, wrapped at 72; the investigation goes on the PR. New `CHANGELOG.md` sections use Keep a Changelog categories. A comment states an invariant or a trap, and never enforces a trust boundary on its own — a type, a test or an assertion has to. ## One deviation from upstream The rulebook's §1 body rules say "`Co-Authored-By` trailers stay." This repo disabled attribution on 2026-08-04, because Gitea 1.27 promotes the trailer to a second participant on the commit page. Our copy inverts that bullet and records why. That is the only rule changed. Two smaller edits keep the file honest in our tree: §6 now records which adoption steps are done versus ongoing, and one audit sentence about CONTRIBUTING moved to the past tense, because this PR changes the thing it described. ## What this deliberately does not do There is no sweep. The 6,090-line `CHANGELOG.md` archive, the release notes, and every existing module rustdoc header stay exactly as they are — §6.3 and §6.4 rule that out. No `docs/adr/` directory either, because `docs/agents/domain.md` says that gets created lazily, when a decision actually needs recording. ## Checks - `scripts/ci/check-docs-links.sh` — exit 0. Negative control: pointing CONTRIBUTING at a nonexistent file makes it exit 1, so the green is not vacuous. - `scripts/ci/check-docs-drift.sh` — exit 0. Both were re-run after rebasing onto `e12f3a62`, because the drift script itself moved on main. - No Rust changed, so the cargo gates do not apply. - The commit is checked against the rules it introduces: subject 37 characters, body wrapped at 72, no trailer. **User-facing fact changed?** n/a — this is contributor-facing only. No docs-site page owns writing standards.
enricobuehler added 1 commit 2026-08-28 21:50:02 +00:00
docs: adopt the Punktfunk house style
ci / web (pull_request) Successful in 1m25s
Details
ci / bun-nix (pull_request) Successful in 1m0s
Details
ci / rust-arm64 (pull_request) Successful in 2m9s
Details
ci / docs-drift (pull_request) Successful in 43s
Details
ci / docs-site (pull_request) Successful in 1m44s
Details
ci / rust (pull_request) Successful in 24m7s
Details
ad6b5184dc 
Three writing surfaces were being asked to hold design reviews. Commit
subjects on main averaged 101 characters, CHANGELOG.md ran to 6,090
lines for eight versions, and module rustdoc carried milestone codes and
soak durations that git blame already keeps honest.

The rules now live in docs/writing.md: Conventional Commits with a
72-character cap, Keep a Changelog categories for new sections, and
comments that state an invariant rather than recap a diff. CONTRIBUTING,
AGENTS.md and the Gitea PR template point at it, and the CHANGELOG
header says which form new sections take.

Nothing existing is rewritten. The changelog archive, the release notes
and every current rustdoc header stay as they are; the style applies to
what gets written next.

Source: github.com/luxus/punktfunk-house-style
enricobuehler merged commit 81c103c54a into main 2026-08-28 21:58:19 +00:00
enricobuehler deleted branch worktree-house-style 2026-08-28 21:58:31 +00:00
Sign in to join this conversation.
Reviewers
No Reviewers
Labels
No items
No labels
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
FernandoMX FlipperDan HitFrostbite bluelightspecial enricobuehler (Enrico Bühler) kszlim luxus nannku neoney
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: unom/punktfunk#438