From 13df1da9837d895b8e0d6bd50ea9fa37e76f525c Mon Sep 17 00:00:00 2001 From: Ogulcan Celik Date: Tue, 25 Aug 2026 22:19:02 +0300 Subject: docs: move changelog curation to release prep --- .../herdr-pre-release-audit/references/pre-release-audit.md | 13 ++++++++----- AGENTS.md | 8 ++++++-- 2 files changed, 14 insertions(+), 7 deletions(-) diff --git a/.agents/skills/herdr-pre-release-audit/references/pre-release-audit.md b/.agents/skills/herdr-pre-release-audit/references/pre-release-audit.md index 2dfcb4d4..0544b18e 100644 --- a/.agents/skills/herdr-pre-release-audit/references/pre-release-audit.md +++ b/.agents/skills/herdr-pre-release-audit/references/pre-release-audit.md @@ -44,11 +44,14 @@ Process: - formatting-only changes - comment-only/doc-only changes unless they materially affect users -6. Audit `docs/next/CHANGELOG.md` and issue references. - - Treat root `CHANGELOG.md` as the latest released changelog. - - Treat `docs/next/CHANGELOG.md` as the next-release changelog. - - Compare meaningful user-facing changes in the commit range against `docs/next/CHANGELOG.md`. +6. Build the stable-release changelog inventory, then audit `docs/next/CHANGELOG.md` and issue references. + - Normal feature and fix work does not maintain `docs/next/CHANGELOG.md`. Stable release preparation owns the complete changelog update so long-lived pull requests do not conflict over one shared file. + - Treat root `CHANGELOG.md` as the latest released changelog and `docs/next/CHANGELOG.md` as the human-curated next-release changelog. + - Before judging the draft, inventory every merged PR and direct commit in the release range. Use conventional commit subjects, commit bodies, changed files, linked issues, PR bodies, and contributor identity as source material. Generated or grouped commit lists are a coverage aid, not final release prose. + - Classify each release unit as user-facing and changelog-worthy, internal/maintenance, docs-only, or needing a decision. Do not silently omit uncertain items. + - Compare every meaningful user-facing item in that inventory against `docs/next/CHANGELOG.md`. - Flag missing entries for new features, bug fixes, removals, breaking changes, defaults, compatibility changes, user-visible command/config/API behavior, and security-relevant changes. + - Final entries must be human-written at product height. Describe what users gain or no longer experience rather than copying commit subjects or implementation details. - Do not require changelog entries solely for internal client/server protocol version bumps. Mention protocol only when the release intentionally changes user-facing compatibility guidance beyond the normal restart requirement. - Inspect commit bodies for issue reference lines in the form `refs #`. - Flag normal commits that use GitHub closing keywords like `fixes #`, `closes #`, or `resolves #`, because they close issues before release when they land on `master`. @@ -84,7 +87,7 @@ Process: 9. Apply changes only when asked. - Do not edit files during the audit unless the user explicitly asks you to apply fixes. - - When asked to apply audit fixes, update `docs/next/CHANGELOG.md`, `docs/next/README.md`, and any required staged website docs under `docs/next/website/src/content/docs/`. + - Release preparation is the normal workflow that writes `docs/next/CHANGELOG.md`. When asked to apply audit fixes, human-write the approved changelog entries from the complete release inventory, and update `docs/next/README.md` plus any required staged website docs under `docs/next/website/src/content/docs/`. - When asked to finalize release docs, finalize only the staged files under `docs/next/`, then run `just release-docs-check`. Preview and stable publication remain CI-owned. Output format: diff --git a/AGENTS.md b/AGENTS.md index 92467bad..72755f89 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -189,13 +189,17 @@ When updating libghostty-vt, check every active patch in `vendor/libghostty-vt.p `skills/herdr/SKILL.md` tracks the latest stable Herdr release because the unversioned `npx skills add herdrdev/herdr --skill herdr -g` command installs it from `master`. Do not update this file in feature or preview work. Review and update it only during stable release preparation, and include the change in the release commit with the `Cargo.toml` version bump. Preview builds keep the latest stable skill. -Unreleased docs live in `docs/next/website/src/content/docs/`. Update those when a user-facing change needs docs before the next release. They are committed drafts but are never production website input. `docs/next/README.md` and `docs/next/CHANGELOG.md` stage root README and changelog changes. +Unreleased docs live in `docs/next/website/src/content/docs/`. Update those when a user-facing change needs docs before the next release. They are committed drafts but are never production website input. `docs/next/README.md` stages root README changes. `docs/next/CHANGELOG.md` is curated during stable release preparation, not maintained by normal feature and fix work. The active preview release docs live in `docs/preview/website/`. Preview CI owns this mutable snapshot and commits it atomically with `website/preview.json`; never edit it manually. Validate it with `node website/scripts/docs-preview.mjs check`. Published stable-release documentation lives in `docs/versions/`. Release CI seeds each version from the tagged `docs/next` tree, and maintainers may correct factual documentation errors in a published version afterward. Apply a correction separately to `docs/next` when it also applies to future releases; never replace a published tree with the current draft. The website build generates `/docs/preview/` from the active preview snapshot, `/docs//` from the maintained version directories, and `/docs/` from the version selected by `docs/versions/manifest.json`. Do not edit generated files under `website/src/content/docs/`. -During release review, finalize `docs/next` and run `just release-docs-check`. Do not copy draft docs into preview or published versions manually. Preview CI snapshots the selected commit. After a stable GitHub Release succeeds, release CI seeds a new version from the exact tag, updates `latest.json`, and deploys them together. Normal feature/fix work should not edit root `README.md`, root `CHANGELOG.md`, published version docs, or `website/latest.json` unless it is a focused correction to already-published documentation or explicitly requested. `docs/next/CHANGELOG.md` is for user-facing Herdr runtime changes; do not add entries for website-only, documentation-only, CI, build-pipeline, or repository-maintenance changes. +During release review, finalize `docs/next` and run `just release-docs-check`. Do not copy draft docs into preview or published versions manually. Preview CI snapshots the selected commit. After a stable GitHub Release succeeds, release CI seeds a new version from the exact tag, updates `latest.json`, and deploys them together. + +Normal feature and fix work must not edit `docs/next/CHANGELOG.md`; this keeps long-lived branches from conflicting over one shared release file. When refreshing an older pull request, remove its changelog-only diff. Keep user-facing commit subjects descriptive and include required `refs #` lines so stable release preparation can inventory the full range. During the pre-release audit, use that inventory to human-write and curate the user-facing entries in `docs/next/CHANGELOG.md`; generated commit lists are source material, not final release prose. Do not add changelog entries for website-only, documentation-only, CI, build-pipeline, or repository-maintenance changes. + +Normal feature/fix work should not edit root `README.md`, root `CHANGELOG.md`, published version docs, or `website/latest.json` unless it is a focused correction to already-published documentation or explicitly requested. Put local PRDs, planning notes, and exploratory specs under `.local/prd/`; `.local/` is ignored and locally controlled. -- cgit v1.2.3