Skip to content

Commit 90aaaa7

Browse files
committed
docs(releases): add PR body section + tighten opening prose
Aligns RELEASES.md with the structural improvements that landed in agentnative-spec/RELEASES.md, adapted for the CLI's PR template (Summary / Changelog / Type of Change / Related Issues/Stories / Files Modified / Testing — six sections, distinct from the spec's five-section template). Adds: - New `## PR body` section between "Daily development" and "Releasing dev to main". Codifies what belongs in PR bodies (NEW user-facing substance, six required template sections) and what does NOT (workflow recap, triple-diff output, pre-push gate results, CI status, AI attribution trailers). Closes the gap that produced the body-discipline drift across recent PRs. - Explicit `cliff.toml` chore-skip footgun reference inside the new Type of Change bullet (mirrors the spec's `^chore` regex form for precision). - Required-empty-fields rules: four `Files Modified` sub-headers and four `Related Issues/Stories` labels stay even when empty (`None.` rather than deletion). - Internal tooling commit guidance (no entries in `## Changelog` for `chore(cliff): ...`, `chore(prose-check): ...`). - Release-PR repetition rationale (`^release` skip prevents double-counting in future regeneration). - No-AI-attribution rule, mirrored from global CLAUDE.md. Tightens: - Drops em-dash overuse in the file's opening sentences (matches spec's cleaner period-separated form): "are not permitted." instead of "are not permitted —"; same in the Branches table cell and the dev-as- forever-branch paragraph. Self-referential: this PR (#50) is also the v0.4.0 spec sync companion, so the new PR body guidance is what the v0.4.0 release operator follows when scrubbing this PR's own body before submit. Future RELEASES.md edits inherit the framing.
1 parent c654e6d commit 90aaaa7

1 file changed

Lines changed: 36 additions & 4 deletions

File tree

RELEASES.md

Lines changed: 36 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
# Releasing `agentnative`
22

3-
Every change reaches production via this pipeline. Direct commits to `dev` or `main` are not permitted — every change
4-
has a PR number in its squash commit message, which keeps the history scannable, attributable, and changelog-ready.
3+
Every change reaches production via this pipeline. Direct commits to `dev` or `main` are not permitted. Every change has
4+
a PR number in its squash commit message, which keeps the history scannable, attributable, and changelog-ready.
55

66
```text
77
feature branch → PR to dev (squash merge)
@@ -16,12 +16,12 @@ feature branch → PR to dev (squash merge)
1616
| -------------------------------------- | --------------------------------------- | ------------------------------------------- | ------------------------------------ |
1717
| `main` | Production. Only release commits. | Forever. | `.github/rulesets/protect-main.json` |
1818
| `dev` | Integration. All feature PRs land here. | Forever. Never delete. | `.github/rulesets/protect-dev.json` |
19-
| `feat/*`, `fix/*`, `chore/*`, `docs/*` | Feature work. | One PR's worth. Auto-deleted on merge. | None — squash into dev freely. |
19+
| `feat/*`, `fix/*`, `chore/*`, `docs/*` | Feature work. | One PR's worth. Auto-deleted on merge. | None. Squash into dev freely. |
2020
| `release/*` | Head of a dev → main PR. | One release's worth. Auto-deleted on merge. | None. |
2121

2222
`dev` is a **forever branch**. Never delete it locally or remotely, even after a `release/* → main` merge. The next
2323
release cycle reuses the same `dev`. The repo's `deleteBranchOnMerge: true` setting doesn't touch `dev` as long as `dev`
24-
is never the head of a PR — using a short-lived `release/*` head is what keeps the setting compatible with a forever
24+
is never the head of a PR. Using a short-lived `release/*` head is what keeps the setting compatible with a forever
2525
integration branch.
2626

2727
## Daily development (feature → dev)
@@ -42,6 +42,38 @@ gh pr create --base dev --title "feat(scope): what changed"
4242
sees it. Save the body to `/tmp/`, run Vale + LanguageTool + unslop, fix findings, then submit via `--body-file`. See
4343
[§ Prose scrubbing](#prose-scrubbing).
4444

45+
## PR body
46+
47+
Every PR — feature, fix, docs, release — uses `.github/pull_request_template.md` verbatim. Six sections, no inventions:
48+
`## Summary`, `## Changelog`, `## Type of Change`, `## Related Issues/Stories`, `## Files Modified`, `## Testing`.
49+
50+
- **Summary** is the NEW user-facing substance the PR ships. What is changing for the consumer that was not already
51+
there. One short paragraph fits. Do NOT recap the workflow (cherry-pick / regenerate / pre-push gate / CI behavior is
52+
documented in this file and `.github/`). Do NOT paste triple-diff output, pre-push gate results, or CI check status
53+
into the body. Those are author verification artifacts that stay local; anomalies get fixed before push, not
54+
audit-trailed in the body.
55+
- **Changelog** subsections (`### Added` / `### Changed` / `### Fixed` / `### Documentation`) hold the user-facing
56+
entries. The template's RULES (in the HTML comment at the top of the section) are literal: 1-5 bullets, delete empty
57+
subsections entirely, each bullet starts with a verb. Prose-only edits leave the section empty or omit it.
58+
- **Type of Change** is one checkbox. Prefer `feat` / `fix` over `chore` when the change has any user-observable effect
59+
(config defaults, env vars, default behaviors). `cliff.toml` skips `^chore` (and `^style` / `^test` / `^ci` /
60+
`^build`) regardless of body content; mistyping a user-facing change as `chore` silently strips it from release notes.
61+
- **Related Issues/Stories** has four labels (`Story:` / `Issue:` / `Architecture:` / `Related PRs:`). All four are
62+
required even when empty — write `- None.` or `n/a` rather than deleting the label.
63+
- **Files Modified** has four sub-headers (`**Modified:**` / `**Created:**` / `**Renamed:**` / `**Deleted:**`). All four
64+
are required even when empty — `Renamed: None.` / `Deleted: None.`
65+
- **Internal tooling commits** (`chore(cliff): ...`, `chore(prose-check): ...`, etc.) do NOT appear in the PR body's `##
66+
Changelog`. They are not user-facing.
67+
- **Release PRs** repeat the entries from the upstream feature PRs they cherry-pick. The repetition is intentional and
68+
harmless: `cliff.toml`'s `^release` skip prevents the release-PR squash commit from being double-counted in any future
69+
regeneration.
70+
- **No AI attribution.** Never append `Co-Authored-By: Claude …`, `🤖 Generated with [Claude Code]`, or any similar
71+
AI-attribution trailer to PR bodies or commit messages. Commits and PRs stand on their own technical content.
72+
73+
The PR body is read by humans reviewing what shipped. Workflow mechanics, verification output, and tool-fix provenance
74+
are noise from that perspective; they belong in this file (`RELEASES.md`), the script outputs, and the commit history
75+
respectively.
76+
4577
## Releasing dev to main
4678

4779
Engineering docs (`docs/plans/`, `docs/solutions/`, `docs/brainstorms/`, `docs/reviews/`) live on `dev` only.

0 commit comments

Comments
 (0)