openclaw-changelog-update

Files (2)

• SKILL.md
• verify-release-notes.mjs · scripts/

SKILL.md (first lines)

# 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. Do not rerun it per validation-recovery backport; when backports
replace the Code SHA, rerun it once after the final Code SHA is green, as a
genuine CHANGELOG-only descendant under the existing product-evidence reuse
policy ([timing](../release-openclaw-maintainer/references/preparation.md#changelog-and-release-notes)). 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/<version>.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 verified 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 version: exact `YYYY.M.PATCH-beta.N` for a beta delta; `YYYY.M.PATCH`
  for cumulative stable notes. Beta entries and records are separate frozen
  artifacts, never copies of the stable-base section.
- Beta base tag: capture the version currently selected by public npm
  `openclaw@beta` before publication, not the last GitHub prerelease or the
  highest beta-suffixed version. The selector may name a stable version also
  selected by `latest`. Omit `--base` (or use `--base npm-beta`) with an exact
  beta version to resolve it once; preserve the resolved tag from the generated
  manifest and reuse that explicit `--base` for edits, verification and recovery.
  If npm already selects the candidate or a newer version, generation refuses
  to guess historical selector state; supply the previously captured tag. When
  that tag is not an ancestor (for example a stable closeout forward-port), the
  verifier uses its reachable merge base and subtracts the captured shipped
  tag's cumulative PR record through `--shipped-ref` semantics. The manifest and
  record retain both boundaries; replay with the captured tag to resolve the
  same range, never select an older GitHub beta instead.
- Stable base tag: last reachable shipped stable release tag. 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:

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

   For beta generation, use `--version YYYY.M.PATCH-beta.N` and omit `--base`
   on the first inventory run. Start an exact-version section with Highlights,
   Changes and Fixes using the shared writer; generate the delta manifest, then
   write prose for that range only. Subsequent runs use the captured npm baseline
   tag explicitly (not only a divergent range's merge-base SHA). Do not query npm again after publication or overwrite the
   cumulative stable entry. Regenerate cumulative stable notes at stable prep.

   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

From openclaw/openclaw, MIT.

More from openclaw/openclaw