Menu
Cut a Velvet release — close the CHANGELOG, bump the package version, dispatch the UPM workflow, and verify the published release. Use whenever a release, a version bump, or a tag is asked for, and when a published release needs its notes checked or repaired.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
| name | release |
| description | Cut a Velvet release — close the CHANGELOG, bump the package version, dispatch the UPM workflow, and verify the published release. Use whenever a release, a version bump, or a tag is asked for, and when a published release needs its notes checked or repaired. |
The UPM workflow does the tagging, the upm branch split and the GitHub release. What it cannot
do is decide what the release contains, so the whole job here is getting CHANGELOG.md right and
then dispatching.
Packages/com.velvet.core/CHANGELOG.md is the single source of truth for the release note.
scripts/release/release_notes.py turns one version's section into the published body — Highlights, install
instructions, the long-form entries collapsed, the compare link. Nothing about a release is written
twice, and nothing is written straight into the GitHub release.
Rename the working section to ## [X.Y.Z] - YYYY-MM-DD and give it a ### Highlights block above
its ### Added / ### Changed / ### Fixed headings.
Highlights is what the release note leads with, and the release fails without it. Five to nine
bullets, one short paragraph each, ordered by what a user notices first — a fix for something that
was silently broken outranks a new utility. Lead the last bullet with **Breaking:** and list every
breaking change in it. Write them fresh: a bullet copied verbatim from a long-form entry below fails
scripts/release/test_release_notes.py, because the note would then say the same thing twice.
Bump version in Packages/com.velvet.core/package.json to match. SemVer against the previous
release: a feat on main makes it a minor, a breaking change makes it a major.
Check the note before opening the pull request:
python3 scripts/release/test_release_notes.py && python3 scripts/release/release_notes.py --version X.Y.Z --repo s4k10503/velvet
Branch, pull request, squash merge — main and upm both refuse a direct push, whatever the change
is. Merging to main re-runs the split into the upm branch on its own; never edit upm by hand,
it is a generated mirror.
gh workflow run upm.yml -f version=X.Y.Z
This is the only step that publishes. It verifies the version against package.json, builds the
note, splits the package to upm, tags vX.Y.Z on the split commit and vX.Y.Z-main on the main
commit, and creates the release.
Do not run gh release create yourself — the dispatch has already made the tag, so it fails with
tag already exists, and the note it would attach is the one the workflow builds anyway.
Two tags exist per release because the vX.Y.Z tags are one-off snapshots of an amended split with
no ancestor relation to each other, so they cannot anchor a "since the last release" compare. The
-main pair does that.
gh release view vX.Y.Z --json body -q .body | head -20
A body of a few dozen characters means only the compare link landed — which is what the release notes used to be, before this was automated. If a published release needs repairing, rebuild it from the CHANGELOG rather than writing prose into the release:
python3 scripts/release/release_notes.py --version X.Y.Z --repo s4k10503/velvet \
--compare-tag vX.Y.Z-main --previous-compare-tag vW.V.U-main --output /tmp/notes.md
gh release edit vX.Y.Z --notes-file /tmp/notes.md
Omit --previous-compare-tag for the first release; the footer then links the whole history instead
of a compare.