Release

/release

Releases are lockstep: every @dunx/* package shares one version and ships together, even the ones a release did not touch. Change detection decides whether to release, never what. The reason is a correctness one - a published range names a concrete version of @dunx/core, so independent versions would let an app end up with two copies of it, and in this container a token is a class object. Full reasoning: architecture/packaging.md, "Versioning is lockstep".

Do not make versions independent again without also solving the duplicate-core problem - see that section for the two alternatives and why each was rejected.

CI runs bun run version on every push to main, and it publishes nothing unless the head commit is a release commit. Ordinary merges run the checks and deploy the docs. This skill is for cutting a release deliberately, and for the failure modes.

Cutting a release

1. /ci-check - build, lint, typecheck, test. A failed build publishes nothing, but a passing build with broken dist/ publishes broken.

2. Run the publish-guard agent over the changed packages.

3. bun run version:dry-run - on a non-release commit this reports that it would skip. It prints the computed bump, the commits it read, and the changed packages.

4. Commit the release trigger and push to main:

   Subject	Bump
   release: <summary>	derived from every commit since the last release
   release(major|minor|patch): <summary>	stated outright
   release!: <summary>	major

   The trigger is matched on the subject only, so a body quoting the word does not publish.

The bump and the changed-package detection both span every commit back to the previous chore(release): bump version to ... marker. That marker is RELEASE_COMMIT_PREFIX in scripts/bump.ts, written by pushVersionCommit in scripts/version.ts - if you change one, change both, or every range becomes "all of history". CI's fetch-depth: 0 is load-bearing for the same reason: a shallow checkout cannot see the marker and silently under-reports the bump to a patch.

Force every package to publish regardless of computed bumps by putting [force-publish] in the commit message. That path bypasses the release gate, and writes no changelog entry: it has no range to describe.

The changelog

Each release prepends a section to the root CHANGELOG.md, from the same commit range the bump was derived from. scripts/changelog.ts owns the format in both directions - renderRelease writes a section, parseChangelog reads them back - and internal/docs renders them at #/releases. Nothing is hand-written.

• The release: commit's own prose becomes the section's summary, so that subject is the release note. A release whose whole range is that one commit still gets a section.
• Commits group by conventional type; an unrecognised one lands under "Other changes" rather than being dropped.
• The generator escapes < and replaces em and en dashes, so a subject written before those rules existed cannot fail no-em-dash.test.ts or lose a type parameter to raw HTML.
• The docs site is built after the release step in ci.yml, so the deployed artifact carries the section this release just wrote. The release commit is [skip ci], so building it earlier would leave the page a release behind.
• Re-running a failed release does not duplicate a section: a version already present is left alone.

The tag and the GitHub release

After the version commit is pushed, scripts/github-release.ts tags v<version> and creates the GitHub release. Before this existed, git tag -l was empty across every release and the repo's Releases page held nothing.

• The notes are read back from CHANGELOG.md by parseChangelog, not re-rendered from the commit range. A second renderer is how the tag, the file and the site would come to disagree about what shipped.
• The body ends with a link to #/releases/<version>, which internal/docs serves as a page per release. The URL is derived from owner/repo, so a fork points at its own Pages site.
• The API call is fetch against the REST API, not the gh CLI: nothing else in scripts/ needs gh, and fetch is native. It needs contents: write, which ci.yml's publishing job already had.
• Neither step throws and neither fails the job. By the time they run the packages are on npm, so a failure here would make a finished publish look broken. Both are idempotent: an existing tag or release is left alone, so a rerun after a partial failure is safe.
• A missing GITHUB_TOKEN skips the release and says so, which is what a local bun run version does.
• [force-publish] gets no tag and no release. It bypasses the release gate and writes no changelog section, so there is no range to describe.