Release notes are raw commit-message dumps with no user-facing framing, so a downstream consumer cannot tell if an upgrade matters to them

coilyco-ops commented

2026-07-01 23:01:52 +00:00

Owner

Why

Persona: forgejo-selfhoster, angle release-story. This persona is the one audience actually positioned to consume the Linux release binaries directly (unlike brew/macOS users), so release-page legibility matters more to them than most.

Latest three releases, bodies verbatim:

v0.242.0: - test(agents): add the drain exit-gate ratchet + docs (ward#425) (31ec534)
          - refactor(agents): drain opencode + goose, delete the closure bridges (ward#425) (9178e22)
          - refactor(agents): drain claude + codex bodies into their folders (ward#425) (ce73558)
          - refactor(agents): rename agentspi -> agentsapi (ward#425 Part A) (a67ab46)
v0.241.0: - feat(advisor): fan cross-repo research out into per-repo issues (8f016a6)
v0.240.0: - docs: split agent harness pages (4c8e694)

Every release body is a raw git log dump of conventional-commit messages: internal refactor jargon ("drain opencode + goose, delete the closure bridges", "rename agentspi -> agentsapi"), bare short SHAs, bare ward#NNN refs. Nothing distinguishes "internal refactor, safe to ignore" from "behavior changed, read this before upgrading" - AGENTS.md itself says "Minor API breaks ship in main with a note in the commit body," but that note, if present, is buried in the same undifferentiated commit-message wall as everything else.

A self-hoster deciding whether to run ward upgrade (or pull a new Linux binary directly) has no way to answer "does this release affect me" without reading raw commit history and inferring intent from refactor-speak.

Deliverable

Either curate release notes (even a one-line "user-facing changes" header above the commit dump) or, at minimum, tag commits that constitute a "note in the commit body" per AGENTS.mds own API-break policy so they are visually distinguishable from routine refactors in the release body.

Done condition

A reader of a release body can tell, without git archaeology, whether that release changed anything they need to react to.

Severity: major-friction · persona: forgejo-selfhoster · angle: release-story
Filed by Claude Code during a cold-read release pressure test (run 22).

## Why Persona: `forgejo-selfhoster`, angle `release-story`. This persona is the one audience actually positioned to consume the Linux release binaries directly (unlike brew/macOS users), so release-page legibility matters more to them than most. Latest three releases, bodies verbatim: ``` v0.242.0: - test(agents): add the drain exit-gate ratchet + docs (ward#425) (31ec534) - refactor(agents): drain opencode + goose, delete the closure bridges (ward#425) (9178e22) - refactor(agents): drain claude + codex bodies into their folders (ward#425) (ce73558) - refactor(agents): rename agentspi -> agentsapi (ward#425 Part A) (a67ab46) v0.241.0: - feat(advisor): fan cross-repo research out into per-repo issues (8f016a6) v0.240.0: - docs: split agent harness pages (4c8e694) ``` Every release body is a raw `git log` dump of conventional-commit messages: internal refactor jargon ("drain opencode + goose, delete the closure bridges", "rename agentspi -> agentsapi"), bare short SHAs, bare `ward#NNN` refs. Nothing distinguishes "internal refactor, safe to ignore" from "behavior changed, read this before upgrading" - AGENTS.md itself says "Minor API breaks ship in `main` with a note in the commit body," but that note, if present, is buried in the same undifferentiated commit-message wall as everything else. A self-hoster deciding whether to run `ward upgrade` (or pull a new Linux binary directly) has no way to answer "does this release affect me" without reading raw commit history and inferring intent from refactor-speak. ## Deliverable Either curate release notes (even a one-line "user-facing changes" header above the commit dump) or, at minimum, tag commits that constitute a "note in the commit body" per AGENTS.mds own API-break policy so they are visually distinguishable from routine refactors in the release body. ## Done condition A reader of a release body can tell, without git archaeology, whether that release changed anything they need to react to. --- **Severity: major-friction** · persona: forgejo-selfhoster · angle: release-story Filed by Claude Code during a cold-read release pressure test (run 22).

coilyco-ops added the

pressure-test

label

2026-07-01 23:01:52 +00:00

coilyco-ops referenced this issue

2026-07-01 23:02:09 +00:00

meta: release pressure-test run log (cold-read usability sweeps) #428

coilyco-ops added this to the ward launch milestone

2026-07-01 23:29:21 +00:00

coilyco-ops added the

labels

2026-07-01 23:30:37 +00:00

coilyco-ops commented

2026-07-01 23:58:54 +00:00

Author

Owner

DECISION - categorized release-notes template in release CI: group by conventional-commit type (feat/fix/docs/refactor), lead with a one-line 'does this affect you' header, collapse internal refactors under a fold. Coordinate with #454 (release CI is being reworked for the GitHub matrix in the same window). Recorded by Claude Code (Fable) during the 2026-07-01 ward launch triage session with Kai.

coilyco-ops referenced this issue

2026-07-01 23:58:55 +00:00

Publish the full release binary matrix to GitHub releases, checksummed and CI-built from the same tags #454

coilyco-ops referenced this issue

2026-07-02 00:01:42 +00:00

meta: jul 1st evening sprint - launch burndown session 1 #492

coilyco-ops commented

2026-07-02 02:50:35 +00:00

Author

Owner

🔒 Reserved by ward agent --driver claude — container engineer-claude-ward-486 on host kais-macbook-pro-2.local is carrying this issue (reserved 2026-07-02T02:50:33Z). Concurrent ward agent runs are blocked until it finishes or the reservation goes stale (2h0m0s TTL); --force overrides.

— Claude (she/her), via ward agent

🔒 Reserved by `ward agent --driver claude` — container `engineer-claude-ward-486` on host `kais-macbook-pro-2.local` is carrying this issue (reserved 2026-07-02T02:50:33Z). Concurrent `ward agent` runs are blocked until it finishes or the reservation goes stale (2h0m0s TTL); `--force` overrides.  — Claude (she/her), via `ward agent`

coilysiren referenced this issue from a commit

2026-07-02 03:05:12 +00:00

feat(release): categorise release-note bodies with a "does this affect you" verdict

coilysiren closed this issue

2026-07-02 03:05:12 +00:00

coilysiren commented

2026-07-02 03:05:55 +00:00

Owner

WARD-OUTCOME: done - release job now renders a categorised body (verdict + breaking-first + folded internals) via scripts/release-notes.sh; landed on main.

Honest retro: the actual change was small and satisfying - the categoriser is one awk pass, and seeing v0.242.0 (the issue's own example) come out as "Probably not, internal changes only" with the refactors folded away felt like the done-condition proving itself.

What fought back was entirely the guardrails, not the feature. Two things ate most of the time: (1) docs/FEATURES.md and docs/release.md were both already sitting right at the 4000-char / 80-line caps, so every sentence I added had to be clawed back byte-for-byte - I ended up splitting the prose into a new docs/release-notes.md and trimming my own wording to land at 3999/3995. (2) The first cut used awk RS="\0" to read NUL-delimited records with bodies inline; I talked myself out of it because the runner may be alpine/busybox awk (create-release's apk fallback hints at it), so I rewrote to line-based %h\t%s records and moved body-level BREAKING detection to git log --grep in the workflow. Cleaner and portable, but a real second pass.

Confidence: high on the categoriser logic (unit-tested against fixtures under ward exec test, including subject-!, body-footer breaks, and the internal-only/empty/first-release edges) and on the fallback-to-raw-changelog safety. The one thing I could NOT exercise end to end is the live Forgejo Actions run - the notes step only fires on a real tag bump, so the first real proof is the next release to main. If the runner's awk turns out to choke on something, the fallback still ships the old raw body rather than an empty one.

Rough edges / possible follow-ups: the "does it affect you" verdict is coarse (breaking > feat/fix > internal); it does not read scopes or dedupe reverts. git log --grep='BREAKING' is deliberately broad and could over-flag a commit that merely mentions the word - I chose over-flagging as the safer failure for release notes. No follow-up issue filed; happy to if the next release surfaces anything.

WARD-OUTCOME: done - release job now renders a categorised body (verdict + breaking-first + folded internals) via scripts/release-notes.sh; landed on main. Honest retro: the actual change was small and satisfying - the categoriser is one awk pass, and seeing v0.242.0 (the issue's own example) come out as "Probably not, internal changes only" with the refactors folded away felt like the done-condition proving itself. What fought back was entirely the guardrails, not the feature. Two things ate most of the time: (1) docs/FEATURES.md and docs/release.md were both already sitting right at the 4000-char / 80-line caps, so every sentence I added had to be clawed back byte-for-byte - I ended up splitting the prose into a new docs/release-notes.md and trimming my own wording to land at 3999/3995. (2) The first cut used awk `RS="\0"` to read NUL-delimited records with bodies inline; I talked myself out of it because the runner may be alpine/busybox awk (create-release's apk fallback hints at it), so I rewrote to line-based `%h\t%s` records and moved body-level BREAKING detection to `git log --grep` in the workflow. Cleaner and portable, but a real second pass. Confidence: high on the categoriser logic (unit-tested against fixtures under `ward exec test`, including subject-`!`, body-footer breaks, and the internal-only/empty/first-release edges) and on the fallback-to-raw-changelog safety. The one thing I could NOT exercise end to end is the live Forgejo Actions run - the notes step only fires on a real tag bump, so the first real proof is the next release to main. If the runner's awk turns out to choke on something, the fallback still ships the old raw body rather than an empty one. Rough edges / possible follow-ups: the "does it affect you" verdict is coarse (breaking > feat/fix > internal); it does not read scopes or dedupe reverts. `git log --grep='BREAKING'` is deliberately broad and could over-flag a commit that merely mentions the word - I chose over-flagging as the safer failure for release notes. No follow-up issue filed; happy to if the next release surfaces anything.

coilysiren referenced this issue

2026-07-14 15:27:09 +00:00

director should emit colorized, space buffered, visually distinct messages about the categories of actions its performing on startup #1283

Rows
Columns

Release notes are raw commit-message dumps with no user-facing framing, so a downstream consumer cannot tell if an upgrade matters to them #486

Why

Deliverable

Done condition