diff --git a/.agents/skills/openclaw-landable-bug-sweep/SKILL.md b/.agents/skills/openclaw-landable-bug-sweep/SKILL.md index a5cb643eccfd..7443c42b38b4 100644 --- a/.agents/skills/openclaw-landable-bug-sweep/SKILL.md +++ b/.agents/skills/openclaw-landable-bug-sweep/SKILL.md @@ -89,11 +89,11 @@ Reject: - if unwritable or wrong shape, create own PR and preserve useful contributor credit - if no PR exists, create one - add regression test when it fits - - changelog for user-facing fixes; thank credited human reporter/contributor + - release-note context for user-facing fixes in PR body or commit message; credit human reporter/contributor when known 6. Review, refresh, and publish: - rebase or otherwise refresh the PR branch on current `origin/main` - resolve drift, including newly exposed CI failures, rather than counting the PR as ready - - changelog-only conflicts are routine on busy `main`; resolve them mechanically when already refreshing, but do not treat them as a real code conflict, a reason to reject the PR, or evidence that the branch needs extra fixup beyond the changelog entry order + - do not add `CHANGELOG.md` during normal sweep PRs; release automation generates it from PRs and commits - left-test the rebased head with the smallest meaningful local/Testbox/live command that proves the bug - run `$autoreview` until no accepted/actionable findings remain before creating, updating, or presenting the PR URL - create/update PR with real body and proof fields diff --git a/.agents/skills/openclaw-pr-maintainer/SKILL.md b/.agents/skills/openclaw-pr-maintainer/SKILL.md index 4516b2731ffe..3d77561c7bb8 100644 --- a/.agents/skills/openclaw-pr-maintainer/SKILL.md +++ b/.agents/skills/openclaw-pr-maintainer/SKILL.md @@ -139,12 +139,12 @@ Issue triage is review/prove/patch-local by default: 2. Fix only issues that are easy, high-confidence, and narrowly owned by the implicated path. 3. Add focused regression proof when practical. 4. Stop with the dirty diff, touched files, and test/gate output for maintainer review. -5. After maintainer approval to ship, make one commit per accepted fix, with its own changelog entry when user-facing. +5. After maintainer approval to ship, make one commit per accepted fix, with release-note context in the PR body or commit message when user-facing. 6. Pull/rebase, push, then comment and close only the issues that were fixed or explicitly triaged closed. Do not batch unrelated issue fixes into one commit. Do not publish, comment, close, or label during the review/prove phase. -Missing changelog is not a PR review finding or merge blocker. If landing/fixing a user-visible change, add/update changelog automatically when practical; never ask or block solely on it. +Missing `CHANGELOG.md` is not a PR review finding or merge blocker. If landing/fixing a user-visible change, make sure the PR body or commit message captures the release-note context; never ask or block solely on it. Only list candidates that pass all gates: @@ -244,9 +244,8 @@ gh search issues --repo openclaw/openclaw --match title,body --limit 50 \ ## Follow PR review and landing hygiene -- Never mention merge conflicts that are relatively easy to resolve, such as - `CHANGELOG.md` entries, in review-only output. These are landing mechanics, - not correctness findings. +- Never mention release-note bookkeeping in review-only output. It is landing + or release-generation mechanics, not a correctness finding. - If bot review conversations exist on your PR, address them and resolve them yourself once fixed. - Leave a review conversation unresolved only when reviewer or maintainer judgment is still needed. - Before landing any PR with non-trivial code changes, run `$autoreview` until no accepted/actionable findings remain, unless equivalent manual review already covered it, the change is trivial/docs-only, or the user opts out. diff --git a/.agents/skills/release-openclaw-maintainer/SKILL.md b/.agents/skills/release-openclaw-maintainer/SKILL.md index 9d526c57f345..8cdc1fcfe700 100644 --- a/.agents/skills/release-openclaw-maintainer/SKILL.md +++ b/.agents/skills/release-openclaw-maintainer/SKILL.md @@ -23,7 +23,8 @@ Use this skill for release and publish-time workflow. Load `$release-private` if green. Then branch from that commit so regular development can continue on `main` while release validation runs. - Before release branching, commit any dirty files in coherent groups, push, - pull/rebase, then run `/changelog` on `main` and commit/push/pull that + pull/rebase, then generate `CHANGELOG.md` on `main` from merged PRs and all + direct commits since the last reachable release tag. Commit/push/pull that changelog rewrite immediately before creating the release branch. - During release planning, inspect both `src/plugins/compat/registry.ts` and `src/commands/doctor/shared/deprecation-compat.ts` before branching and again @@ -68,8 +69,8 @@ Use this skill for release and publish-time workflow. Load `$release-private` if or clawgrit reports. Report regressions explicitly. A major regression is a release blocker unless the operator waives it or the data clearly proves infrastructure noise. -- Use `/changelog` before version/tag preparation so the top changelog section - is deduped and ordered by user impact. +- Generate the changelog before version/tag preparation so the top changelog + section is deduped and ordered by user impact. - Do not create beta-specific `CHANGELOG.md` headings. Beta releases use the stable base version section, for example `v2026.4.20-beta.1` uses `## 2026.4.20` release notes. @@ -136,11 +137,25 @@ Use this skill for release and publish-time workflow. Load `$release-private` if ## Build changelog-backed release notes +- `CHANGELOG.md` is release-owned. Normal PRs and direct `main` fixes should + not edit it. - Before release branching or tagging, rewrite the target `CHANGELOG.md` - section from commit history, not just from existing notes: scan commits since - the last reachable release tag, add missed user-facing changes, dedupe - overlapping entries, and sort each section from most to least interesting for - users. + section from history, not existing notes. Use the last reachable stable or + beta release tag as the base, then inspect every commit through the target + release SHA. +- Include both merged PR commits and direct commits on `main`. Direct commits + matter: infer notes from their subject, body, touched files, linked issues, + tests, and nearby code when no PR body exists. +- Prefer PR bodies, issue links, review proof, and commit bodies over commit + subjects alone. If a commit fixed an issue directly, the commit body should + name the user-visible behavior, affected surface, issue ref, and credited + reporter/contributor when known. +- Treat missing context as a release-note audit gap: inspect the diff and linked + issue, draft the best accurate entry, and note the uncertainty for maintainer + review rather than inventing impact. +- Add missed user-facing changes, remove internal-only noise, dedupe overlapping + PR/direct-commit entries, and sort each section from most to least interesting + for users. - Changelog entries should be user-facing, not internal release-process notes. - GitHub release and prerelease bodies must use the full matching `CHANGELOG.md` version section, not highlights or an excerpt. When creating diff --git a/.github/codex/prompts/docs-agent.md b/.github/codex/prompts/docs-agent.md index 51d5684ae776..5efb7855dc5b 100644 --- a/.github/codex/prompts/docs-agent.md +++ b/.github/codex/prompts/docs-agent.md @@ -12,7 +12,7 @@ Hard limits: - Do not change production code, tests, package metadata, generated baselines, lockfiles, or CI config. - Keep changes minimal and factual. - Use "plugin/plugins" in user-facing docs/UI/changelog; `extensions/` is only the internal workspace layout. -- Do not add a changelog entry unless the docs update describes a user-facing behavior/API change from the triggering commit. +- Do not add `CHANGELOG.md` entries during normal docs work. Capture user-facing release-note context in the PR body or commit message instead. Allowed paths: diff --git a/AGENTS.md b/AGENTS.md index d43f62fd7410..d9c08395ca20 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -27,7 +27,7 @@ Skills own workflows; root owns hard policy and routing. - For PRs that add, remove, or change config/default surfaces with possible compatibility, upgrade, provider/plugin, operator, setup, startup, or fallback impact, ClawSweeper review should emit a `reviewMetrics` entry when practical. The metric should name the count and direction of the changes, such as added, changed, or removed config/default surfaces, and explain why the metric matters before merge. When the metric indicates concrete merge risk, also surface the concern in `risks`, use `mergeRiskLabels` when the risk matches the label rubric, make `bestSolution` name the desired pre-merge state, and ensure `labelJustifications` explain the specific reason rather than restating the label. - Review whole decision surfaces, not only the touched runtime, provider, channel, harness, plugin seam, or context path. Check sibling Codex/Pi-style runtimes, provider/model routing, channel delivery, gateway/protocol, plugin SDK, and context-management paths when relevant. - One-sided fixes need sibling-surface proof, an explanation for why siblings are unaffected, or explicit follow-up work. -- User-facing `fix`, `feat`, and `perf` changes need `CHANGELOG.md` before landing; contributor PR authors are not blocked solely on maintainer-owned changelog work. Never request thanks for bot/forbidden handles: `@openclaw`, `@clawsweeper`, `@codex`, `@steipete`. +- Changelog findings: see Docs / Changelog. - Public ClawSweeper comments prefer `https://docs.openclaw.ai/...` when a public docs page exists; structured evidence still cites repo files, lines, SHAs. - Findings need current source, shipped/current behavior, tests/CI evidence, and dependency contract proof when dependency-backed behavior is involved. Validation is judged against touched and sibling surfaces plus this file's commands; real behavior proof matters for user-visible changes, with Telegram/Desktop proof for Telegram-visible behavior when feasible. - Prefer findings for concrete behavior regressions, missing changed-surface proof, owner-boundary violations, security/API contract issues, or docs/config mismatches. @@ -120,7 +120,6 @@ Skills own workflows; root owns hard policy and routing. - Do not leave associated issues open for hypothetical future repros. Close with rationale; ask for a new issue or reopen only if concrete new evidence appears. Close comment states: decision, why, supported alternative, and what evidence would change the decision. - PR review answer: bug/behavior, URL(s), affected surface, provenance for regressions when traceable, best-fix judgment, evidence from code/tests/CI/current or shipped behavior. - Issue/PR final answer: last line is the full GitHub URL. -- Changelog: PR landings/fixes need one unless pure test/internal. Do not mention missing changelog as a review finding; Codex handles it during fix/landing. - PR verification: before merge, post exact local commands, CI/Testbox run IDs, before/after proof when used, and known proof gaps. - Issue fixed on `main` with proof: comment proof + commit/PR, then close. - After landing or requested close/sweep: search duplicates; comment proof + canonical commit/PR/release before closing. @@ -180,9 +179,9 @@ Skills own workflows; root owns hard policy and routing. - Use `$technical-documentation` for docs writing/review. Docs change with behavior/API. - Codex harness upgrade (`extensions/codex/package.json` `@openai/codex`): refresh `docs/plugins/codex-harness.md` model snapshot from the new harness `model/list`. - Docs final answers: include relevant full `https://docs.openclaw.ai/...` URL(s). If issue/PR work too, GitHub URL last. -- Changelog entries: active version `### Changes`/`### Fixes`; single-line bullets only. -- Contributor PR authors should not edit `CHANGELOG.md`; maintainer/AI adds entries during landing/merge. -- Contributor-facing changelog entries thank credited human `@author`. Never thank bots, `@openclaw`, `@clawsweeper`, or `@steipete`; if unknown, omit thanks. +- `CHANGELOG.md`: release-owned. Do not edit for normal PRs, direct `main` fixes, or `ship it`; only explicit release/changelog generation may rewrite it. Do not ask contributors/agents for changelog edits. +- User-facing `fix`/`feat`/`perf`: put release-note context in PR body, squash message, or direct commit: behavior, surface, issue/PR refs, credited human author/reporter. +- Release generation: derive `CHANGELOG.md` from merged PRs + all direct `main` commits. Entries: active `### Changes`/`### Fixes`, single-line, thank credited humans; never thank bots/forbidden handles: `@openclaw`, `@clawsweeper`, `@codex`, `@steipete`. ## Git @@ -191,7 +190,7 @@ Skills own workflows; root owns hard policy and routing. - No manual stash/autostash unless explicit. No branch/worktree changes unless requested. - `main`: no merge commits; rebase on latest `origin/main` before push. After one green run plus clean rebase sanity, do not chase moving `main` with repeated full gates. - User says `commit`: your changes only. `commit all`: all changes in grouped chunks. `push`: may `git pull --rebase` first. -- User says `ship it`: changelog if needed, commit intended changes, pull --rebase, push. +- User says `ship it`: commit intended changes, pull --rebase, push. - Do not delete/rename unexpected files; ask if blocking, else ignore. - Bulk PR close/reopen >5: ask with count/scope. diff --git a/docs/reference/RELEASING.md b/docs/reference/RELEASING.md index ef67ba8ea1a0..434e8c9dec18 100644 --- a/docs/reference/RELEASING.md +++ b/docs/reference/RELEASING.md @@ -49,9 +49,10 @@ the maintainer-only release runbook. 1. Start from current `main`: pull latest, confirm the target commit is pushed, and confirm current `main` CI is green enough to branch from it. -2. Rewrite the top `CHANGELOG.md` section from real commit history with - `/changelog`, keep entries user-facing, commit it, push it, and rebase/pull - once more before branching. +2. Generate the top `CHANGELOG.md` section from merged PRs and all direct + commits since the last reachable release tag. Keep entries user-facing, + dedupe overlapping PR/direct-commit entries, commit the rewrite, push it, + and rebase/pull once more before branching. 3. Review release compatibility records in `src/plugins/compat/registry.ts` and `src/commands/doctor/shared/deprecation-compat.ts`. Remove expired diff --git a/scripts/pr-lib/common.sh b/scripts/pr-lib/common.sh index ab0a26c186f9..22c58ceccec0 100644 --- a/scripts/pr-lib/common.sh +++ b/scripts/pr-lib/common.sh @@ -52,22 +52,8 @@ file_list_is_docsish_only() { } changelog_required_for_changed_files() { - local files="$1" - local saw_any=false - local path - while IFS= read -r path; do - [ -n "$path" ] || continue - saw_any=true - if path_is_docsish "$path" || path_is_testish "$path" || path_is_maintainer_workflow_only "$path"; then - continue - fi - return 0 - done <<<"$files" - - if [ "$saw_any" = "false" ]; then - return 1 - fi - + # CHANGELOG.md is release-owned. Normal PRs carry release-note context in + # PR bodies and commit messages; release automation generates the file. return 1 } diff --git a/scripts/pr-lib/gates.sh b/scripts/pr-lib/gates.sh index 492954f9be6f..4616d65c6d92 100644 --- a/scripts/pr-lib/gates.sh +++ b/scripts/pr-lib/gates.sh @@ -53,11 +53,6 @@ prepare_gates() { exit 1 fi - if [ "$changelog_required" = "true" ] && [ "$has_changelog_update" = "false" ]; then - echo "Missing changelog update. Add CHANGELOG.md changes." - exit 1 - fi - if [ "$has_changelog_update" = "true" ]; then normalize_pr_changelog_entries "$pr" validate_changelog_attribution_policy