Release Changelog Harness

Release & changelog harness

Make releases understandable: every version bump has structured intent that agents and humans can read in git—not only in a maintainer’s head or a GitHub Releases textarea.

This skill is meta harness culture (which tool, which gates, which docs). It is not a full tutorial for every package manager.

Mixture of experts — critique your idea

Improved framing (use this):

Adopt the release legibility contract first; pick the ecosystem-native generator second (Changesets is one excellent generator for JS workspaces, not the universal hammer).

See mixture-of-experts.md for extended debate and anti-patterns.

Release legibility contract (normative)

Before picking a tool, agree the repo obeys:

1. Notes in git — Changelog or changeset files are versioned; not release-notes-only in a web UI.
2. Structured contributor input — Contributors add intent in a fixed shape (e.g. .changeset/foo.md, conventional commit scope, or ADR note)—not “bump version when you remember.”
3. Mechanical publish path — One documented command sequence in DX_FAQ; CI is the source of truth for “can ship.”
4. Agent-readable output — Post-release, CHANGELOG.md (or per-package changelogs) reflects what shipped; agents can answer “what changed in vX?”
5. Why is recorded — Non-obvious toolchain choice → short ADR or DESIGN_FAQ Q&A.
6. Install trust matches release truth — The latest GitHub Release, release assets, checksums, package versions, and install docs must agree; stale pinned install examples are release drift.

Ecosystem router (default patterns)

Full matrix: ecosystem-tooling.md. Binary/install: binary-release-contract.md.

When to use this skill

• “We should use Changesets like the JS community”
• Release process is unclear, versions drift, or agents can’t tell what shipped
• Adding release CI, versioning policy, or monorepo publish workflow
• Auditing whether changelog tooling matches repo archetype (repo-quality-system-lifecycle)

Workflow

1. Classify the repo

Use repo-quality-system-lifecycle archetypes (app, library, CLI/tool, plugin, harness, meta/governance). Meta and harness repos need legibility; app repos need legibility and runtime compatibility notes.

2. Choose generator (ADR if non-obvious)

Record choice in docs/decisions/NNNN-release-changelog-tooling.md when more than one option is reasonable.

3. Wire harness surfaces

4. Minimal Changesets shape (JS monorepos and private packages)

Contributor adds:

---
"package-name": patch
---

Short imperative summary agents can quote in release notes.

Private Packages and Public Tags

By default, Changesets ignores packages marked with "private": true in package.json. To allow version bumps for a private root package or private workspace modules, update .changeset/config.json to include:

  "privatePackages": {
    "version": true,
    "tag": false
  }

Use "tag": false when a custom release script owns the public vX.Y.Z tag. Use "tag": true only when Changesets itself should create package-scoped tags.

Maintainer flow:

pnpm changeset          # or npx @changesets/cli
pnpm changeset version
pnpm install            # if lockfile must update
git commit -am "chore: version packages"

Publish: project-specific (changeset publish, GitHub Action, or npm provenance)—document exact commands in DX_FAQ, not here.

For automated Changesets releases, prefer:

merge feature PR with changeset
→ CI opens/updates Version PR
→ merge Version PR
→ same Release workflow creates vX.Y.Z, builds artifacts, creates/updates GitHub Release, verifies latest release state

If the tag is pushed with GITHUB_TOKEN, do not depend on a separate on: push: tags workflow to build assets; GitHub suppresses recursive workflow triggers for that token.

5. Choose distribution surface

Skill Steward: skills via npx skills; steward_cli precompiled AOT binaries via GitHub Releases & install.sh (ADR 0014).

6. Verify legibility

• Agent can read “what’s unreleased” from git without GitHub API
• CI fails when a version bump lacks notes
• DX_FAQ lists commands copy-paste ready
• No duplicate version sources (e.g. hand bump + bot bump)
• If binaries: tag assets match version SSOT; latest GitHub Release points to the package version; install.sh defaults to latest and pinned examples use placeholders or generated checks

Anti-patterns

Related skills

Install

npx skills add arenukvern/skill_steward --skill release-changelog-harness

Sources

references/sources.md