Releasing

Versioning and publishing strategy for actup-ts.

Status: the project is pre-1.0 with no tagged release yet. This document defines the intended strategy. Steps marked (planned) are not yet implemented in the repo.

Versioning

• Semantic Versioning 2.0.0.
• Pre-1.0: the CLI surface, config schema, and exit codes may change in any release. Breaking changes bump the minor while 0.x.
• A single project version is released. The workspace @actup/* package versions (0.1.0) are an internal implementation detail and are not the published version; the released artifact is the bundled CLI.
• CHANGELOG.md follows Keep a Changelog 1.1.0. All work accrues under ## [Unreleased]. On release, that section is renamed to ## [X.Y.Z] - YYYY-MM-DD, a fresh empty ## [Unreleased] is added above it, and the link references at the bottom are updated.

Distribution channels

1. Standalone binaries (primary)

bun build --compile produces a self-contained executable with no Node/Bun runtime dependency. Verified working:

bun build packages/cli/src/index.ts --compile --outfile .build/actup
.build/actup --help          # runnable ELF, no node_modules required

Per-platform binaries are built and attached to the GitHub Release.

Target matrix (built via bun build --compile --target):

Asset	--target
actup-linux-x64	bun-linux-x64
actup-linux-arm64	bun-linux-arm64
actup-darwin-x64	bun-darwin-x64
actup-darwin-arm64	bun-darwin-arm64
actup-windows-x64.exe	bun-windows-x64

Attach SHA-256 checksums alongside each asset. (planned: release workflow)

2. Single bundled npm package (secondary)

For bunx actup / npx actup users a single bundled package is published.

Why a bundle, not the workspace packages: every @actup/* package is "private": true and depends on siblings via workspace:* (e.g. @actup/cli -> @actup/core, @actup/providers). workspace:* is a protocol the registry cannot resolve — publishing the packages as-is would yield an uninstallable tree. Rather than un-privatizing five packages, rewriting workspace:* to real version ranges, and coordinating five version bumps per release, the CLI entrypoint is bundled into one self-contained package that has no @actup/* dependencies.

Published name: actup (decided, 2026-05-18). Unscoped, distinct from the private @actup/cli. https://registry.npmjs.org/actup returned 404 (unclaimed) at decision time, so no scope is needed. The release workflow's bundled dist/package.json already hardcodes this name — the decision and the implementation are in sync.

Published package shape (as built by .github/workflows/release.yml's npm job — written, not yet exercised against a real tag):

• name: actup; version = the release tag without the v.
• bin.actup -> the Node-target bundle of bun build packages/cli/src/index.ts --target=node --outfile dist/actup.js with a #!/usr/bin/env node shebang prepended, chmod +x.
• license: MIT; engines.node: >=20.
• A fresh standalone dist/package.json is written (no @actup/* deps, no workspace:*); every packages/* stays "private" and unpublished. files is limited to actup.js.

3. GitHub Action wrapper

Consumers can run actup in CI without installing anything:

- uses: kjanat/actup@v1

The action pins to a release tag and invokes a downloaded binary (channel 1). (planned: action.yml + a major-version moving tag, e.g. v1 updated to point at the latest v1.y.z.)

Tagging

• Tags are GPG-signed annotated tags, v-prefixed: git tag -s vX.Y.Z -m "vX.Y.Z — short summary".
• The tag points at the actual work commit. There is no dedicated version-bump commit.
• The tag message is the version plus an optional one-line summary.

Release checklist (maintainer)

1. Confirm main/release branch is green: bun run typecheck && bun run test.
2. Verify the compile build still works: bun build packages/cli/src/index.ts --compile --outfile .build/actup && .build/actup --help.
3. Update CHANGELOG.md:
   • Rename ## [Unreleased] -> ## [X.Y.Z] - YYYY-MM-DD.
   • Add a new empty ## [Unreleased] above it.
   • Update/add the link references at the bottom of the file.
4. Commit the changelog edit (this is the work commit the tag will point at; no separate bump commit).
5. Tag: git tag -s vX.Y.Z -m "vX.Y.Z — <summary>".
6. Push commit and tag: git push && git push --tags.
7. CI release workflow (planned):
   • Builds the per-platform binaries and checksums; creates the GitHub Release with the changelog section as the body and attaches the assets.
   • Builds and publishes the bundled npm package with npm provenance (npm publish --provenance, OIDC-authenticated via the workflow; the id-token: write permission must be granted).
   • Moves the Action major tag (vX) to the new release.
8. Smoke-test a published binary and bunx actup@X.Y.Z --help.

npm provenance

The bundled package is published from the release workflow with --provenance so the registry records a verifiable link between the published tarball and the GitHub-hosted build. This requires:

• The publish job runs in GitHub Actions with permissions: id-token: write.
• The package version equals the release tag (X.Y.Z).

(planned: the publish workflow.)

Open items

• Bundled npm package name — decided: actup (unscoped; registry 404 at decision time). Definition implemented in release.yml.
• Release workflow (binary matrix + npm provenance publish) — written in .github/workflows/release.yml; not yet exercised against a real v* tag (binary upload + publish paths unverified end-to-end).
• action.yml wrapper exists; the vX moving tag is created on first tagged release.