Document the pull-request workflow, and require a release note to merge #81

New issue

Closed

opened 2026-09-22 15:47:00 +01:00 by cruelacid · 0 comments

cruelacid commented

2026-09-22 15:47:00 +01:00

Owner

Part of #77.

Why

The workflow only works if every session follows it, and sessions read
CLAUDE.md. The changelog only works if a release note cannot be skipped.

What to do

CLAUDE.md — extend "Working a plan". The shape is unchanged; it gains a
merge event:

One plan → one worktree → one branch → one pull request → fast-forward onto main.

Say what the PR body must carry, and that main is protected so there is no
longer a way round it.

A pull request template carrying the release-note block. Kubernetes'
mechanism, which Forgejo's own release-notes-assistant also reads:

## Changelog
<one user-facing sentence, or NONE>

NONE is Kubernetes' exact convention for a change with no user-facing effect.
A PR carrying several distinct user-visible changes instead adds
release-notes/<PR>.md to the branch, one line each — release-notes-assistant's
convention, adopted verbatim so that door stays open.

A required check that fails while the block is missing or empty. Kubernetes
does this with do-not-merge/release-note-label-needed. Enforcing at the PR
rather than at release time is the point: nothing merges undocumented, so the
changelog cannot silently omit a change.

Routing needs no new taxonomy

area:plugin, area:server, area:identity, area:docs and area:ops
already exist and are already applied. They decide which ledger an entry joins.

Part of #77. ## Why The workflow only works if every session follows it, and sessions read `CLAUDE.md`. The changelog only works if a release note cannot be skipped. ## What to do **`CLAUDE.md`** — extend "Working a plan". The shape is unchanged; it gains a merge event: > One plan → one worktree → one branch → one pull request → fast-forward onto `main`. Say what the PR body must carry, and that `main` is protected so there is no longer a way round it. **A pull request template** carrying the release-note block. Kubernetes' mechanism, which Forgejo's own `release-notes-assistant` also reads: ``` ## Changelog <one user-facing sentence, or NONE> ``` `NONE` is Kubernetes' exact convention for a change with no user-facing effect. A PR carrying several distinct user-visible changes instead adds `release-notes/<PR>.md` to the branch, one line each — `release-notes-assistant`'s convention, adopted verbatim so that door stays open. **A required check** that fails while the block is missing or empty. Kubernetes does this with `do-not-merge/release-note-label-needed`. Enforcing at the PR rather than at release time is the point: nothing merges undocumented, so the changelog cannot silently omit a change. ## Routing needs no new taxonomy `area:plugin`, `area:server`, `area:identity`, `area:docs` and `area:ops` already exist and are already applied. They decide which ledger an entry joins.

cruelacid added this to the Backlog - unscheduled milestone

2026-09-22 15:47:00 +01:00

cruelacid added the

area:docs

label

2026-09-22 15:47:00 +01:00

~~cruelacid referenced this issue 2026-09-22 15:47:00 +01:00~~

Derive CHANGELOG.md into the published mirror #83

cruelacid referenced this issue

2026-09-22 15:48:40 +01:00

The pull request as the unit of change, and a changelog built on it #77

cruelacid added this to the User Experience project