OpenClaw Changelog Update

Use this for changelog rewrites and GitHub release-note source text. For regular beta/stable, prepare complete notes before final-source qualification when possible; Code SHA may then also be Release SHA. Editorial work may overlap Code validation. If notes change afterward, a genuine CHANGELOG-only descendant may use the existing product-evidence reuse policy. For extended-stable, run it before final exact-head validation and tagging. Do not rerun it for tooling retries, resumed publication, or promotion. Use it with release-openclaw-maintainer; this skill owns changelog content, ordering, grouping, and attribution discipline.

Goal

Rebuild the target CHANGELOG/YYYY.M.PATCH.md release section from a complete, generated history manifest, not stale draft notes. Produce grouped user-facing release notes sorted by user interest while preserving every relevant issue/PR ref and every human Thanks @... attribution.

CHANGELOG.md is the generated release index. The shared owner scripts/lib/release-changelog.mjs resolves release sections and contribution records from a working tree or a pinned Git ref, including historical refs that still contain a monolith. Use node scripts/release-changelog.mjs read --version <version> [--ref <sha-or-tag>] for a section, or add --record for its contribution record. A missing split artifact must not fall back to the root index. Historical releases without records gain no invented provenance. Generated CHANGELOG/** files retain exact migrated or mirrored bytes and are excluded from generic formatting, like the root changelog. Validate them through their owner with pnpm changelog:check.

Current writes use the split layout. To save a complete initial section, use node scripts/release-changelog.mjs write --version <version> --file <section.md>; it updates the release entry, matching CHANGELOG/records/<version>.md when present, and index together. Initial generation retains the section format below. Published docs mirrors follow the separate post-release route at the end of this skill; initial generation must never overwrite them.

Inputs

• Target base version: YYYY.M.PATCH, without beta suffix.
• Base tag: last reachable shipped release tag, usually the previous stable or the previous beta train requested by the operator. It must be an ancestor of the target; a newer but divergent tag is not a valid history boundary. Use an explicit shipped/main-closeout SHA only when it is also reachable from the target.
• Target ref: the exact product-complete history being documented. Its contribution-record target must be an ancestor of the final release target; it need not name a not-yet-created changelog commit. Include any later fixes before finalizing notes. Final notes may be committed before qualification, or afterward as a CHANGELOG-only descendant of a green Code SHA.
• Canonical main ref: current origin/main, fetched before verification. Release notes cite the original merged main PR when the same work is carried by a backport. A release-branch PR is used only while no forward-port exists on current main.

Workflow

1. Confirm the release branch and exact history target:

   • git fetch --tags origin
   • confirm clean git status -sb
   • record git rev-parse HEAD as the history target
   • record the Full Release Validation run id and attempt when qualification already exists
   • finish pending product/version/backport changes before freezing final source; refresh the inventory for actual changes

2. Audit history, including direct commits:

   • git log --topo-order --date=iso-strict --pretty=format:'%h%x09%ad%x09%s' <base-tag>..<target-ref>
   • git log --topo-order --grep='(#' --date=short --pretty=format:'%h%x09%ad%x09%s' <base-tag>..<target-ref>
   • Include every commit reachable from the target but not the base, including merged side branches. Resolve PR associations before deduplicating and subtracting shipped records; retain the existing revert exclusions.
   • also inspect --since='24 hours ago' when main moved during the release.

3. Generate the complete contribution record and editorial manifest before writing grouped prose:

   node --import tsx .agents/skills/openclaw-changelog-update/scripts/verify-release-notes.mjs \
     --base <base-tag> \
     --target <target-ref> \
     --main-ref origin/main \
     --version <YYYY.M.PATCH> \
     --manifest /tmp/openclaw-release-<YYYY.M.PATCH>.json \
     --write-ledger
   

   Add repeatable --release-provenance '<40sha> -> #PR[, #PR]' inputs when release commits cannot carry provenance metadata. These use the same exact marker grammar and current-main validation as commit-body markers.

   The verifier automatically reuses public GitHub GraphQL responses from an exact base/target SHA snapshot under the worktree's git metadata. Iterative rewrites at the same target avoid repeated network discovery. Use --refresh-github-snapshot after suspect API data, --github-snapshot <path> for an explicit artifact, or --no-github-snapshot for a live-only audit. GitHub release bodies are always read live. Explicit CI #, CI run #, Actions run #, and workflow run # references in active source are classified separately only when issue/PR resolution fails and a live same-repository Actions lookup confirms the exact run ID. Any ordinary occurrence of that number in active source, notes, or the contribution record remains a strict issue/PR requirement. Confirmed runs appear as workflowRuns in verification output and the manifest, never as PR associations or contributor credit.

• after the manifest-driven rewrite, regenerate and verify the complete contribution record before committing:

  node --import tsx .agents/skills/openclaw-changelog-update/scripts/verify-release-notes.mjs \
    --base <base-tag> \
    --target <target-ref> \
    --main-ref origin/main \
    --version <YYYY.M.PATCH> \
    --manifest /tmp/openclaw-release-<YYYY.M.PATCH>.json \
    --write-ledger
  

• the command fails when any #NNN reference in release history or the rendered release section cannot resolve, when reverted work is presented as shipped, when a source PR is absent from the contribution record, when direct commits are rendered as a public record dump, when non-editorial PRs appear in grouped prose, or when an eligible PR author or known co-author is missing from that PR's Thanks @... credit. It also fails before history collection when --base is not an ancestor of --target, when ### Highlights has fewer than five or more than eight top-level bullets, or when the existing prose/record names a PR outside the source range. Only an explicit --seed-ref may add historical PR inventory; an explicit repeatable --shipped-ref may subtract PRs proven present in a prior shipped tag
• when grouped prose names a PR, that same bullet must retain every contributor and linked-reporter credit from its generated PR record
• unqualified #NNN references resolve against openclaw/openclaw; cross-repository references such as openclaw/imsg#141 remain literal text and must not be rewritten as local issue links
• after the GitHub release or prerelease is published, verify every matching release page against the same source section:

  node --import tsx .agents/skills/openclaw-changelog-update/scripts/verify-release-notes.mjs \
    --base <base-tag> \
    --target <target-ref> \
    --version <YYYY.M.PATCH> \
    --release-tag v<YYYY.M.PATCH> \
    --check-github
  

• add one --release-tag for every beta, stable, and extended-stable page in the train; a ### Release verification tail is permitted, but any other body drift fails the check
• scripts/render-github-release-notes.mts is the canonical release-body renderer used by candidate validation, publish, and verification. When the complete ## YYYY.M.PATCH section fits GitHub's 125,000-character limit and the renderer's matching 125,000-byte safety ceiling, the body must contain that exact section including its heading
• when the complete source section exceeds either limit, the renderer keeps the exact grouped editorial notes through the line before ### Complete contribution record, then emits that heading with a stable link to the full contribution record in the tag-pinned (historical monolithic tags retain their original record link). Never truncate a bullet or partial record, and never hand-author a different compact form

Post-release docs mirrors

After explicit approval of the docs publication, publish the approved docs sources and their mechanically flattened changelog in the same source PR. This is separate from initial release generation; do not run an editorial rewrite automatically during release preparation or publication.

Render the ordered docs sources into one full Markdown file, even for a large release or a release spanning several docs pages:

pnpm changelog:from-docs --version YYYY.M.PATCH \
  --source docs/releases/YYYY.M.PATCH.md \
  --output CHANGELOG/YYYY.M.PATCH.md
pnpm changelog:check

Repeat --source in the approved reading order for a multipart release. The converter removes presentation wrappers, turns accordion titles into headings, expands docs links, and preserves source text, credits, code, tables, and images. Unsupported markup fails instead of silently dropping content. Its first-line marker binds the ordered source paths and exact source digest. Checks compare only marked mirrors against their sources; untouched historical originals stay in their initial format. Preserve CHANGELOG/records/YYYY.M.PATCH.md as the frozen accounting record when replacing reader prose, and regenerate the mirror in the same PR whenever its docs sources change.

The approved publication bundle owns source merge, verified docs deployment, and the later GitHub Release body update as separate recorded steps. After deployment, freshly read the existing release, then update only its body with version/statistics, Raw changelog and docs links, one alphabetically deduplicated verified human thanks roster, and the unchanged release-verification section. Include verified PR, direct-commit, coauthor, and issue credit, including @steipete; exclude bots. Keep both the 125,000-character and 125,000-byte ceilings without truncating credits or proof. GitHub owns native avatars and assets. Verify the body readback, resume only incomplete steps, and never retag, rebuild, republish assets, or rerun initial publication to replace this body. The initial history verifier rejects docs mirrors; use the docs-publication workflow for their verification.

Extended-Stable Variant

Extended-stable has one release commit and one canonical GitHub Release body. After version prep and approved backports, regenerate CHANGELOG/YYYY.M.P.md with the regular manifest and original-main-PR provenance rules. Land it by PR, then validate the final branch tip before tagging. The release closeout renders that tag-owned section into the shared draft before the parent pipeline publishes the non-Latest release page. Re-audit after a product backport; a tooling-only repair needs no changelog entry. Never rewrite a published tag or changelog.

Quota / API Outage Rule

If GitHub API quota is exhausted, do not idle. Continue work that does not need GitHub API:

• local changelog rewrite and release-note extraction
• local pretag checks and package/build sanity
• git push/tag checks over git protocol
• npm registry npm view checks
• exact workflow-dispatch command preparation

Only GitHub Release creation, workflow dispatch, run polling, artifact download, and issue/PR mutation need API quota.