Changelog
Post-release docs sync — regenerate CHANGELOG.md from git tags, install the post-tag GitHub Actions hook, and diagnose drift. Use when a release just landed and the CHANGELOG didn't update, when a project wants to adopt shipyard-managed release notes, or when CI flags "CHANGELOG.md out of date".From its SKILL.md
npx -y skills add danielraffel/Shipyard --skill changelogAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
One thing to look at
- 3 stars3 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
SKILL.md
4.8 KB, as published. Nobody here has run it
Post-release docs sync
Shipyard-owned changelog regeneration + post-tag commit-back. Opt-in via [release.changelog] + [release.post_tag_hook] in .shipyard/config.toml. Absent sections = no behavior change.
Quick reference
| Task | Command |
|---|---|
| Scaffold config + warn about existing CHANGELOG | shipyard changelog init |
| Regenerate CHANGELOG.md | shipyard changelog regenerate |
| CI drift check | shipyard changelog check (exit 1 on drift) |
| Print release notes for one tag | shipyard changelog regenerate --release-notes v0.9.0 |
| Render to stdout instead of writing | shipyard changelog regenerate --stdout |
| Install post-tag workflow | shipyard release-bot hook install |
| Run the hook locally (dry tag) | shipyard release-bot hook run --tag v0.9.0 |
When to run regen
- Hook didn't fire. A tag landed but
CHANGELOG.mdis still stale — eitherRELEASE_BOT_TOKENis missing, the workflow was uninstalled, or the tag didn't matchonly_for_tag_pattern. Runshipyard changelog regeneratelocally to catch up, then PR it in. - Previewing the next release. Merge candidate landed in a PR branch. Run regen locally to see what the bullet will look like.
- CI drift gate.
shipyard changelog checkin a PR workflow lights up red if a human hand-edited the wrong block and the generator would have produced different output.
How drift is caught
shipyard changelog check rebuilds from scratch and compares to the file on disk. Any difference is "drift." Wire it into CI:
- name: Check CHANGELOG.md is in sync with tags
run: shipyard changelog check
Exit codes: 0 clean, 1 drift, 2 config missing / tag missing.
Config reference — [release.changelog]
| Field | Meaning | Default |
|---|---|---|
enabled | Opt-in switch. Absent = no behavior change. | false |
repo_url | GitHub repo URL used for PR links + release backlinks. | auto-detect |
path | CHANGELOG path to overwrite. | CHANGELOG.md |
tag_filter | Glob of tags to walk. Restricts further to strict PREFIX + vMAJOR.MINOR.PATCH. | v* |
product | Name in the CHANGELOG header "All notable changes to {product}…". | project name |
skip_commit_patterns | Subjects dropped from entries (regex list, case-insensitive). | chore/release bumps |
title | H1 text. | Changelog |
header_comment | Full <!-- … --> block emitted between intro and first entry. Default omits the block — keeps shipyard-identifying text out of the rendered file. Migrating off another generator? Set this to the previous header verbatim for byte-identity. | None |
Config reference — [release.post_tag_hook]
| Field | Meaning | Default |
|---|---|---|
enabled | Opt-in switch. | false |
command | Shell command the workflow runs. Swap for a custom script if you don't want shipyard's generator. | shipyard changelog regenerate |
watch | Files to stage-and-commit if diffed after command. | ["CHANGELOG.md"] |
trailers | Commit trailers appended to the docs-sync commit. | three *: skip trailers |
only_for_tag_pattern | Glob restricting which tags trigger sync. | v* |
max_push_attempts | Rebase-retry attempts before giving up. | 5 |
bot_identity.name / bot_identity.email | git committer identity for the bot commit. | shipyard-release-bot |
Two capabilities, separately usable
- Hook only — point
commandat your own script, keep shipyard's rebase-retry + trailer plumbing. - Generator only — run
shipyard changelog regeneratefrom your own workflow if you don't want shipyard to own the committing side.
Workflow-file upgrades are explicit
The shipped .github/workflows/post-tag-sync.yml pins SHIPYARD_VERSION to whatever shipyard rendered it. Re-run shipyard release-bot hook install after upgrading the local CLI to refresh the pin — otherwise the workflow keeps installing the older version even after you upgrade. Pinning is intentional (consumer protection from drift); explicit re-install is the upgrade path.
The install step pipes to bash, not sh — dash (Ubuntu's /bin/sh) rejects set -o pipefail used by the install script. Tests guard this.
Skill-sync gotcha
Anything under src/changelog.rs, src/app/changelog_cmd.rs, or commands/changelog.md touches this skill's path map. Update this file in the same PR, or pass --skip-skill-update changelog --skill-reason "..." to shipyard pr (only when the change is genuinely mechanical).