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. 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:

   ```bash
   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.
   Only GitHub `NOT_FOUND` references confined to contextual commit-body text, absent from subjects, closing references, provenance, and notes/records, and below the highest resolved number may be omitted and reported as manifest `unavailableReferences` without credit.
   - the manifest is the required input to the rewrite, not an after-the-fact
     audit; it contains every referenced PR, eligible contributor credit,
     inline issue context, every direct commit, and an editorial-eligibility
     classification for PRs and direct commits
   - schema version 3 is the required ephemeral manifest contract. Regenerate
     older manifests; version 2 is not a supported downstream-reader boundary
   - for a historical backfill, add `--seed-ref <pre-backfill-ref>` once so
     contribution records from the prior changelog are retained even when an
     older merged commit omitted its PR number; the verifier excludes records
     for work reverted after the base tag, including beta work reverted before
     the stable release
   - generated provenance reports in-range PRs separately from retained
     seed-only PRs, then states the unique row total. A PR present in both
     inventories counts as in-range; never describe the seed-inclusive total
     as work merged in the current release range
   - add repeatable `--shipped-ref <prior-shipped-tag>` when the reachable main
     closeout differs from the shipped tag or later forward-port commits
     re-associate PRs that were already released. Each tag is a cumulative
     shipped boundary: the verifier unions explicit PR rows from complete
     contribution records in numbered release sections, excludes only overlapping PRs,

From Elogic360/imClaw, MIT.

More from Elogic360/imClaw