From faaddfe18d571ce5f7abb942655c686a9cfdfe99 Mon Sep 17 00:00:00 2001 From: Ogulcan Celik Date: Fri, 29 May 2026 21:35:16 +0300 Subject: docs: finalize release docs --- .codex/skills/herdr-pre-release-audit/SKILL.md | 20 ++++ .../references/pre-release-audit.md | 121 +++++++++++++++++++++ 2 files changed, 141 insertions(+) create mode 100644 .codex/skills/herdr-pre-release-audit/SKILL.md create mode 100644 .codex/skills/herdr-pre-release-audit/references/pre-release-audit.md (limited to '.codex/skills') diff --git a/.codex/skills/herdr-pre-release-audit/SKILL.md b/.codex/skills/herdr-pre-release-audit/SKILL.md new file mode 100644 index 00000000..d3a24d46 --- /dev/null +++ b/.codex/skills/herdr-pre-release-audit/SKILL.md @@ -0,0 +1,20 @@ +--- +name: herdr-pre-release-audit +description: Audit herdr release readiness by comparing commits since the base release against next-release changelog and docs. Use when asked to run or apply the repo's pre-release audit, validate docs/next before release, inspect issue refs that release CI will close, or finalize release docs for herdr. +--- + +# Herdr Pre-release Audit + +Use this skill only inside the herdr repository. + +Read `references/pre-release-audit.md` and follow its workflow. Treat it as the source of truth for: + +- choosing the release base ref +- inspecting first-parent history and merged PRs +- auditing `docs/next/CHANGELOG.md` +- auditing `docs/next/README.md` and staged website docs +- checking issue reference lines +- deciding when to run `just release-docs-check` +- producing the final release-readiness report + +Do not edit files during the audit unless the user explicitly asks to apply fixes. When applying fixes, keep changes scoped to the files named in the reference workflow. diff --git a/.codex/skills/herdr-pre-release-audit/references/pre-release-audit.md b/.codex/skills/herdr-pre-release-audit/references/pre-release-audit.md new file mode 100644 index 00000000..4858f598 --- /dev/null +++ b/.codex/skills/herdr-pre-release-audit/references/pre-release-audit.md @@ -0,0 +1,121 @@ +--- +description: Audit next-release docs and changelog before release +--- +Audit release readiness for this repo. + +Optional starting ref override: `$1` +Extra user intent/context: `${@:2}` + +Process: + +1. Determine the base ref. + - If `$1` is non-empty and looks like a ref/tag, use it. + - Otherwise use the latest release tag, preferring the repo's semver tag style: + ```bash + git describe --tags --abbrev=0 + ``` + +2. Inspect the range from base ref to `HEAD`. + - Use first-parent history for release context: + ```bash + git log --first-parent --reverse --format='%H%x09%s' ..HEAD + ``` + - Also inspect full commits and commit bodies when needed: + ```bash + git log --reverse --format='%H%x09%s%n%b' ..HEAD + ``` + +3. Detect merged PRs if any. + - Look for first-parent subjects that indicate PR merges, including squash merges like `title (#123)`. + - If GitHub CLI is available and the PR number is known, use it to fetch PR title/body for context. + - Treat a merged PR as the primary release unit. + - Do **not** also list individual commits that belong to that PR. + +4. Handle direct commits separately. + - Any commit in the range not represented by a merged PR should be considered on its own. + +5. Infer what matters. + - For each PR or direct commit, inspect changed files and diff stats. + - Read the most relevant files in full when needed to understand user-facing impact. + - Ignore pure housekeeping unless it has release value: + - version bumps + - release/tag commits + - changelog-only commits + - 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`. + - Flag missing entries for new features, bug fixes, removals, breaking changes, defaults, compatibility changes, user-visible command/config/API behavior, and security-relevant changes. + - 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`. + - For each shipped issue reference, check whether the changelog has a matching user-facing entry that mentions `#` when appropriate. + - For each merged external human PR, check whether the changelog entry mentions the PR number and thanks the contributor in the existing style, e.g. `(#129, thanks @username)`. If the PR primarily ships an issue fix, include both the issue and PR numbers when useful, e.g. `(#128, #129, thanks @username)`. Do not add thanks text for maintainer-owned bots or automation accounts such as `kangal-bot` or `dependabot`. + - Do not require or add GitHub closing keywords like `fixes #`, `closes #`, or `resolves #` to changelog entries or release notes. + - List shipped issue references under `Issue references to close after release:` so the release operator can verify what release CI will close after the GitHub Release is published. + - Flag stale entries that do not appear to correspond to shipped changes in the range. + - Flag entries that are too implementation-focused or unclear for end users. + - Preserve the existing changelog style and sections: `Added`, `Changed`, `Fixed`, `Removed`, and `Breaking Changes` when applicable. + +7. Audit next-release public docs. + - Treat root `README.md` and `website/src/content/docs/` as the latest released public docs. + - Treat `docs/next/README.md` as the next-release root README, and `docs/next/website/src/content/docs/` as the full next-release mirror of website docs. + - Compare meaningful user-facing changes in the range against next-release docs first. + - Flag missing release docs for new or changed features, commands, config keys, protocol behavior, integrations, defaults, and compatibility notes. + - Compare `docs/next/README.md` against root `README.md`, and compare the staged website-doc mirror against `website/src/content/docs/`. Flag each difference as intended to ship in this release, stale, or needing user decision. + - Also audit example config snippets for release readiness. + +8. Verify finalization state. + - Before `just release`, approved `docs/next/README.md` must be copied to root `README.md`, approved staged website docs must be copied from `docs/next/website/src/content/docs/` to `website/src/content/docs/`, and the deleted root doc files must stay deleted. + - Run or recommend: + ```bash + just release-docs-check + ``` + - This check must include root `README.md`, root `CHANGELOG.md`, the removed root doc files, and exact 1:1 sync between `docs/next/website/src/content/docs/` and `website/src/content/docs/`. + - Do not run `just release` unless the working tree is clean and the docs check passes. + +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/`. + - When asked to finalize release docs, copy approved next-release README and changelog into root, copy approved staged website docs into `website/src/content/docs/`, then run `just release-docs-check`. + +Output format: + +```md +Release readiness: READY | NOT READY + +Base: +Range: ..HEAD +Meaningful shipped changes: yes | no + +Changelog: OK | MISSING ENTRIES | NEEDS ATTENTION +Missing: +- + +Docs: OK | MISSING | INACCURATE | NEEDS DECISION +Missing: +- + +Wrong or questionable: +- + +Issue refs: OK | NEEDS ATTENTION +Will close after release: +- # + +Accepted/no action: +- + +Root docs finalized: YES | NO + + +Required before release: +1. +``` + +Keep the main output glanceable. Put commit inventories, excluded housekeeping, and commands run in an appendix only when they materially help the operator. + +If the range has no meaningful user-facing changes, say that plainly instead of forcing entries. -- cgit v1.2.3