ossuminc/riddl / .claude/skills/ship
ship
VerifiedShip Skill
Executes a full release cycle for the riddl project. Follow each step in order. STOP immediately if any assertion fails and report the problem.
Arguments
The user should provide a version number (e.g., 1.10.1). If
not provided:
- Run
git tag --sort=-v:refname | head -5to find the actual latest tag (not just reachable from current branch) - Run
git log --oneline <latest-tag>..HEADto see changes - Analyze per semver and recommend a version (don't ask the user to choose — present your recommendation and let them confirm or override)
Pre-Flight Checks
-
Always ship a FINAL release from
main. Ordinary work commits directly tomain, so in the usual case there is nothing to bring forward and you are already where you need to be:git checkout main git pull origin main git branch --show-currentThere is no
developmentbranch. It was deleted (local and remote) on 2026-08-27, having been 0 commits ahead ofmain; the GitFlow pre-flight this step used to prescribe — fast-forwardingmainup todevelopment— was a no-op or contrary to policy for every release from 1.30.0 onward, and was skipped by hand each time. SeeCLAUDE.md§ Branch Strategy.When the release IS on a branch, which is the case for a large change such as
release/2, merge that branch intomainand tagmain. Do not tag the branch:git checkout main && git pull origin main git merge --no-ff release/2Release CANDIDATES are the documented exception and may be tagged on the release branch — an RC is a prerelease on GitHub, an
@rcformula in the tap and anrcdist-tag on npm, so nothing resolves to it unless asked for by name. See the/rcskill. -
Assert working tree is clean:
git status --porcelainIf dirty, list the uncommitted files and ask the user how to proceed. Scratch/test files that aren't part of the release should be removed or set aside, not committed.
-
GITHUB_TOKEN handling: Do NOT
unset GITHUB_TOKENglobally — sbt needs it for GitHub Packages resolution. Only unset it immediately beforeghcommands:unset GITHUB_TOKEN && gh ... -
Verify the version tag does not already exist:
git tag -l <VERSION>
Ship Steps
-
Ensure the working tree is clean before tagging. sbt-dynver derives the version from
git describe; any dirty tree causes it to append a<VERSION>-N-<hash>-<timestamp>suffix instead of the clean<VERSION>. This suffix would propagate to BuildInfo, all published artifacts, and npm packages. Check:git status --porcelainIf any files are modified or untracked, commit them now before proceeding.
-
Create an annotated git tag:
git tag -a <VERSION> -m "Release <VERSION>" -
Verify dynver resolves to the clean version:
sbt 'show riddlc/version'The output must be exactly
<VERSION>with no suffix. If it has a suffix, do NOT proceed — delete the tag (git tag -d <VERSION>), fix the issue, and re-tag.
8a. Check binary compatibility against the previous release (MiMa).
This is the ONLY place MiMa runs — not in tJVM, not in CI (Reid,
2026-11-07). It is what gives the backward-compatibility policy in
CLAUDE.md a tool behind it:
sbt "; utils/mimaReportBinaryIssues ; language/mimaReportBinaryIssues ; passes/mimaReportBinaryIssues ; testkit/mimaReportBinaryIssues ; riddlLib/mimaReportBinaryIssues ; commands/mimaReportBinaryIssues"
It compares each JVM artifact against V.previous in
project/Dependencies.scala, which must name the LAST RELEASE (step
13a keeps it there). Expect six clean reports. Any Problem is a
removed or changed public signature: stop, delete the tag, and
restore the old signature (deprecate, don't delete). Never
silence a problem with a MiMa filter unless Reid approves that
specific one.
A clean run proves nothing if it never compared anything. If you
doubt it, calibrate the way it was calibrated on 2026-10-31: rename a
public method (e.g. ThirdPartyNotices.noticesFile), confirm
utils/mimaReportBinaryIssues reports a DirectMissingMethodProblem,
then revert.
-
Run the full test suite and publish all modules:
sbt "; clean; tJVM; tJS; tNative; publish"NEVER
sbt clean test publish. That was prescribed here until 2026-08-27 and it is a gate that can skip most of the suite while reporting success. In sbt 2 baretestresolves totestQuick, which skips suites it judges unaffected — and that judgement survivesclean, because the action cache does. It once left the JS row of a GREEN run executing 109 of 567 tests, withlanguageJS,passesJSandtestkitJSnever running at all.tJVM/tJS/tNativeexist precisely to defeat this: they aretestOnly *, which ignores incremental state. See the alias comments inbuild.sbt.Count what ran. One
Suites: completed Nline per module in each alias, and zeroNo tests to run. A short count means a module was skipped or the;chain aborted at a failure — either way, look.For a MAJOR release, certify from a genuinely cold cache first (Reid, 2026-08-27, shipping 2.0.0).
cleanremovestarget/but NOT the shared store at~/.cache/sbt/v2(or~/Library/Caches/sbt/v2), so results can still be replayed:sbt -batch shutdown # a warm server IGNORES the -D sbt --server -Dsbt.global.localcache=/tmp/sbt-verify-<ver> -batch "; clean; tJVM; tJS; tNative"The property applies only at server boot, so the shutdown is not optional. Afterwards the throwaway directory must EXIST and have GROWN (
du -sh) — an empty one means the run was served from the shared cache and certified nothing.Because the tag is on HEAD and the tree is clean, BuildInfo and all published artifacts will carry the clean
<VERSION>. Verify in the sbt output. If tests fail, delete the tag (git tag -d <VERSION>) — do NOT push a broken release. -
Push commits and tag to origin:
git push origin main <VERSION> -
Write detailed release notes and create the GitHub release. Do NOT use
--generate-notes— the auto-generated notes are just commit titles and are not suitable for a public repository.Instead, read all commits since the previous tag:
git log --format="%H %s" <PREV_TAG>..<VERSION>Then read the diffs for any non-trivial commits to understand what actually changed. Write human-readable release notes in this format:
## What's New ### Features - **Feature name** — Clear description of what was added and why it matters to users. ### Bug Fixes - **Area affected** — What was broken and how it's fixed. ### Improvements - **Area affected** — What changed and why it's better. ### Internal - Dependency upgrades, CI fixes, documentation updates, and other changes that don't affect end users directly.Omit any section that has no entries. Focus on what users and consumers of the library need to know. Use clear, complete sentences — not just commit message echo.
Create the release:
unset GITHUB_TOKEN && gh release create <VERSION> \ --title "Release <VERSION>" --notes "$(cat <<'EOF' <release notes here> EOF )"This triggers the Release Artifacts workflow (native builds, Homebrew formula update) and the npm-publish workflow automatically.
Post-Release Verification
-
Confirm the release exists:
unset GITHUB_TOKEN && gh release view <VERSION> -
Run
git statusto confirm the working tree is clean. Known issue: Thesbt cleanstep in the build may trigger sbt-ossuminc's copyright header formatter, which updates files that still have stale headers (e.g.,"Ossum, Inc."→"Ossum Inc."). Ifgit statusshows modified files that are only copyright header changes:- Commit them:
git add -u && git commit -m "Fix copyright headers" - Push:
git push origin mainThese changes are harmless formatting fixes and should be committed straight tomain.
- Commit them:
13a. Move the MiMa baseline to the version just shipped. Set
V.previous in project/Dependencies.scala to <VERSION>, then
commit to main and push. Without this the next release is
compared against an older baseline, and anything added in this
release can be removed with no warning. The artifacts must already
be resolvable, which step 9's publish ensures.
-
Delete the release branch, if the release came from one. There is no merge-back step:
mainIS the working branch, so there is nowhere to merge the tag forward TO. This step used to saygit checkout development && git merge main, which since 1.30.0 has been either a no-op or contrary to policy.git branch -d <release-branch> git push origin --delete <release-branch> -
Report a summary: tag, commit SHA, release URL, and any CI workflows triggered.
-
Drop upgrade tasks in dependent projects. Invoke
/ossuminc-skills:bump-consumerswith libraryriddland the version just released. That skill owns the consumer list (skills/bump-consumers/consumers.md) and the task-file format — do not maintain a repo list here. riddl has more consumers than any other library (Scala viaproject/Dependencies.scala; npm via@ossuminc/riddl-libinpackage.json), so let the skill apply its usual restraint: it asks before writing and proposes skipping patch releases rather than filing a task in every consumer for a bugfix. Requires theossuminc-skillsplugin installed (claude plugin list | grep ossuminc-skills).
If Something Fails
- If tests fail in step 9: delete the local tag
(
git tag -d <VERSION>), fix, and restart from step 6. Do NOT push a broken tag. - If dynver shows a suffix in step 8: delete the tag, fix the dirty tree, and re-tag.
- If tag push fails in step 10: check if tag exists remotely.
- If publish fails in step 9: check credentials and retry (tag is still local, safe to retry).
- If
gh release createfails in step 11: the tag is already pushed, so the release can be created manually or retried. - Never force-push tags without explicit user approval.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |