Releasing cadkit
One tag publishes everything. .github/workflows/release.yml builds and tests every
artifact, waits for approval on the release environment, then publishes:
| Channel | Package | Contents |
|---|---|---|
| crates.io | cadkit-geom, cadkit-scene, cadkit-gpu, cadkit-core, cadkit-dgn, cadkit-dxf, cadkit-gml, cadkit-dwg, cadkit, cadkit-cli, cadkit-capi |
Rust sources; docs.rs builds the API documentation |
| PyPI | pycadkit (imports as cadkit) |
abi3 wheels for Linux x86_64/aarch64 (manylinux), macOS arm64/x86_64, Windows x64, and an sdist |
| npm | cadkit-wasm |
one package: cadkit-wasm (ES module, browser and bundlers) and cadkit-wasm/node (CommonJS) |
| GitHub Releases | cadkit-<target> |
CLI for Linux x86_64/aarch64 (static musl), macOS arm64/x86_64, Windows x64 |
| GitHub Releases | cadkit-capi-<target> |
C/C++ headers, shared and static libraries (Linux glibc 2.28+, macOS, Windows x64) |
cadkit-py and cadkit-wasm have publish = false: they are distributed through PyPI and
npm, not crates.io. cadkit-capi is published to crates.io (sources, first published at
0.5.3) and its prebuilt libraries ship on GitHub Releases. The release also carries
SHA256SUMS and GitHub build-provenance attestations for every file
(gh attestation verify <file> -R TNYCL/cadkit). PyPI and npm attach their own
provenance through trusted publishing.
Archive names carry no version, so the newest build always has a stable link, for example
https://github.com/TNYCL/cadkit/releases/latest/download/cadkit-x86_64-pc-windows-msvc.zip.
cargo binstall cadkit-cli downloads these archives.
Dry run
Section titled “Dry run”Run the workflow by hand from the Actions tab (or gh workflow run release.yml --ref <branch>).
It runs every build, test and package step, including cargo publish --dry-run for the whole
workspace, and publishes nothing. Do this before tagging whenever the packaging changed.
One-time setup
Section titled “One-time setup”Registry accounts belong to the maintainer; enable two-factor authentication on each.
- GitHub environment. Settings → Environments →
release: add yourself as a required reviewer and limit deployments to tags matchingv*. Secrets for the first release (below) go into this environment, not the repository. - PyPI. Add a pending trusted publisher at https://pypi.org/manage/account/publishing/:
project
pycadkit, ownerTNYCL, repositorycadkit, workflowrelease.yml, environmentrelease. No token is ever needed. A pending publisher does not reserve the name; the first upload does. - crates.io (trusted publishing works only for crates that already exist). For the
first release, create an API token at https://crates.io/settings/tokens with the scopes
publish-newandpublish-update, crate patterncadkit*and a short expiry, and save it as theCARGO_REGISTRY_TOKENsecret of thereleaseenvironment. After the first release, add a trusted publisher on each crate’s settings page (repositoryTNYCL/cadkit, workflowrelease.yml, environmentrelease), then delete the secret and revoke the token. Without the secret the workflow uses trusted publishing. - npm (same restriction: the package must exist first). For the first release, create a
granular access token at npmjs.com with read and write access, limited to publishing, with
a short expiry, and save it as the
NPM_TOKENsecret of thereleaseenvironment. After the first release, add a trusted publisher in thecadkit-wasmpackage settings (GitHub Actions,TNYCL/cadkit, workflowrelease.yml, environmentrelease), delete the secret and revoke the token.
Each release
Section titled “Each release”- On a branch:
python scripts/release.py bump X.Y.Z. It sets the workspace version and the internal dependency versions, refreshesCargo.lockand turns## [Unreleased]inCHANGELOG.mdinto## [X.Y.Z] - <date>below a new emptyUnreleasedsection. Edit the changelog section; it becomes the GitHub release notes. For the first release (0.1.0), also delete the “not released yet” note at the top ofREADME.md. python scripts/release.py check --tag vX.Y.Zmust pass. Open a pull request, let CI pass, optionally run the dry run on the branch, and merge.- Tag the merge commit on
mainand push the tag:git tag -a vX.Y.Z -m "cadkit X.Y.Z" && git push origin vX.Y.Z. - When the builds pass, approve the
releasedeployment on the workflow run. The three publish jobs start together; the GitHub release is created after all of them succeed. - Check docs.rs, the PyPI and npm pages, and the release assets.
- Update the website to the new version: merge Dependabot’s
cadkit-wasmupdate forsite/(or bump it by hand) once the npm package is published; see WEBSITE.md.
A version with a suffix (0.2.0-rc.1) becomes a GitHub pre-release and npm dist-tag next.
When something fails
Section titled “When something fails”- Before approval nothing is published: fix on
main, delete the tag (git push --delete origin vX.Y.Z && git tag -d vX.Y.Z) and tag again. - After approval, use Re-run failed jobs. Every publish step is idempotent: crates already
on the index are skipped, PyPI uses
skip-existing, npm skips an existing version. - A published version cannot be replaced on any registry. If a release is broken, fix it in
the next patch version;
cargo yankandnpm deprecatemark the bad one.
License copies
Section titled “License copies”Every package carries LICENSE-MIT, LICENSE-APACHE and NOTICE. Cargo and maturin package
only files inside the package directory, so each published crate directory and
crates/cadkit-py hold copies. After editing a root file, run
python scripts/release.py sync-licenses; the release check fails while a copy differs.