Prepare and publish a TypeScript release
A release is a pull request. Label it major, minor, patch, or no-release, write its description as the release notes, and merge it to main with a merge commit. The publish workflow does the rest; you do not edit versions, create tags, or run npm publish.
How a release runs
Section titled “How a release runs”Merging a labeled pull request to main runs .github/workflows/publish.yml:
cratis/release-actionreads the label, computes the next version from the existing releases, and creates the GitHub release with the pull request description as its notes. Ano-releasepull request creates no release and publishes nothing.- A publish job runs
node scripts/set-version.mjs <version> --allow-major, which writes the version into every versioned workspace manifest, the internal dependency ranges, and the three documentation version statements. - The job then runs
node scripts/publish-npm.mjs. It packs every non-private workspace package and publishes them in dependency order through npm trusted publishing (OIDC) with provenance. It skips any version already on the registry, so a re-run after a partial failure publishes only what is missing.
The publish job sets the version in its own checkout, so do not bump versions in a feature pull request. Run yarn set-version --check to verify that manifests, internal ranges, and the version statements agree with each other. yarn set-version <MAJOR.MINOR.PATCH> accepts only stable versions, refuses a major change without --allow-major, and updates the three statements (README, documentation index, and package reference) and yarn.lock.
Labels and approval
Section titled “Labels and approval”- Pick exactly one of
major,minor,patch, orno-releasewhen you create the pull request. Useno-releasefor documentation, CI, and other changes with no outward-facing effect. - Major releases are never automatic. A maintainer must explicitly merge a pull request labeled
major; never enable auto-merge on one or merge it on someone’s behalf.--allow-majorlets the script write the version; it grants no approval. - Merge with a merge commit, not squash or rebase.
- Write the description for framework users: only nonempty
## Added,## Changed,## Fixed,## Removed,## Security, and## Deprecatedsections, each with specific bullets. It is published verbatim as the release notes.
Check a change locally
Section titled “Check a change locally”-
Write the pull request description for framework users. Keep only nonempty
## Added,## Changed,## Fixed,## Removed,## Security, and## Deprecatedsections, each with a specific bullet. Useno-releasefor documentation, CI, and other changes with no outward-facing effect. Do not submit a release preview forno-releasework. -
Run the release guard specifications:
Terminal window node --test scripts/for_release/*.test.mjs -
Run the same build and test gate as the hosted CI workflow:
Terminal window corepack enableyarn install --immutableyarn ciyarn cialso runsyarn set-version --checkandyarn check:consumersafter the build. It installs tarballs in disposable projects outside the workspace, checks public exports and package contents, type-checks NodeNext and Bundler consumers, and exercises native ESM HTTP and CLI usage (including core without optional RxJS). Runyarn check:consumers --self-testseparately to prove the package-content guard rejects a planted violation. Neither check publishes a package. A passing guard specification alone does not mean the framework has passed CI.The Chronicle and Drizzle consumer files skip library checks only for known third-party declaration errors. CONTRIBUTING.md lists them.
Optional dry run: release preview
Section titled “Optional dry run: release preview”The release preview is an optional dry run. It never publishes, tags, or creates a release. Save the verified user-facing notes from the merged pull request in a UTF-8 Markdown file, for example .ai-work/keep/release-notes.md (ignored). The file requires supported sections such as this illustrative format (not actual release notes):
## Added- Describe a specific public capability that shipped
## Fixed- Describe a specific user-visible bug that was fixedReplace both illustrative bullets with changes that actually shipped. Dispatch Release preview (no publication) from the current default branch; replace main below if that branch differs:
gh workflow run release-preview.yml --ref main \ -F intent=patch \ -F release_notes=@.ai-work/keep/release-notes.mdThe -F flag reads the file contents, including newlines, as a single workflow input; -f would pass the @ text literally. This command starts a hosted workflow: run it only when you intend to spend a CI run. An optional -F expected_current_version=1.2.3 (without the v) makes the preview fail if the latest stable tag disagrees. The workflow runs the release guard specifications and yarn ci before printing its plan. It checks that the dispatch commit is still the default-branch head, reads existing vMAJOR.MINOR.PATCH tags, and computes the next tag. With no tags, it starts from 0.0.0. Other tag shapes, placeholder or empty notes, a stale branch head, and any attempt to enable npm publishing fail closed.
The workflow is manual only, not triggered by pushes or pull requests. The preview uses read-only permissions and prints a plan; it does not update package manifests, apply labels, tag, create a release, or publish to npm. The displayed version is derived from Git tags alone. The separate yarn set-version --check gate verifies local manifest and documentation consistency, but the preview does not establish that its proposed tag matches the manifest version or that any package is ready to publish. Do not describe a preview as a completed release.
After a release
Section titled “After a release”Check that the GitHub release exists and that npm view @cratis/arc.core version shows the new version. The Chronicle integration (@cratis/arc.chronicle) and @cratis/platform are published with every release but stay documented as bounded in the capability reference. If the publish job fails after some packages are published, re-run it: the script skips versions already on the registry. A release must fail rather than report success after a partial publish.