Files
caelum/RELEASING.md
Paul HittandClaude Opus 5.5 1e7e8922ac
ci / lint (pull_request) Successful in 10s
ci / server (mysql) (pull_request) Successful in 11s
ci / nox (pull_request) Successful in 11s
ci / sidecar (pull_request) Failing after 8s
ci / server (sqlite) (pull_request) Successful in 13s
ci / client (pull_request) Successful in 26s
ci / image (pull_request) Skipped
ci / sourcemaps (pull_request) Skipped
ci / deploy (pull_request) Skipped
CI: move to Gitea Actions; deploy over SSH from mac1/mac2
Translate .gitlab-ci.yml into .gitea/workflows/ci.yml with the same
coverage (client, lint, nox, server mysql + sqlite advisory, sidecar,
image build, hadolint, sqlite boot smoke test). Images go to the Gitea
registry as caelum and caelum-reduce. Sourcemaps upload straight to
https://bugs.extant2000.com. Deploy copies the compose and runs
deploy/gitea-deploy.sh on the box over SSH with a throwaway registry
login, waits for healthy, and checks gitSha plus the .map exposure on
the public edge. Repository links now point at git.extant2000.com.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-13 11:18:58 -04:00

2.9 KiB

Releasing

This repo ships three artifacts on a release:

  1. A git tag and CHANGELOG entry.
  2. The production Docker image, pushed to the Gitea registry (git.extant2000.com/extant2000/caelum) by the image job in .gitea/workflows/ci.yml, which then deploys it to the box. Secrets live only in /srv/prod/caelum/caelum.env on the box; CI never writes it.
  3. The two npm packages: @caelum/nox-parser and @caelum/nox-runtime.

The Caelum app (server + client) deploys as a Docker image on the VPS (see docker-compose.prod.yaml); others self-host with Docker (see the README).

Versioning

Pre-1.0 SemVer: every minor may break, every patch is safe. Breaking changes go in CHANGELOG.md. All five workspaces share one version number, so keep them in sync.

Release checklist

# 1. Bump versions across all five package.jsons. Pre-1.0 minor bump:
#    root, server, client, nox/parser, nox/runtime
#
#    (Use find + sed, or do them by hand. They should all match.)
#
# 2. Move [Unreleased] to [<version>] in CHANGELOG.md and date it.
#
# 3. Run the test suites.

cd nox/parser  && npm test
cd ../runtime  && npm test
cd ../../client && npx vite build

# 4. Commit and tag.

git add -A
git commit -m "chore: release <version>"
git tag v<version>
git push && git push --tags

# 5. The Gitea workflow builds + pushes the production image
#    (git.extant2000.com/extant2000/caelum:<short sha> + :latest) on main
#    and deploys it.

# 6. Publish npm packages. nox-parser MUST publish first because
#    nox-runtime depends on it.

cd nox/parser
npm publish          # @caelum/nox-parser
cd ../runtime
# Update nox-runtime's "@caelum/nox-parser" dep from file:../parser to ^<version>
# (just for the publish; the in-repo file: link stays for monorepo dev)
npm publish          # @caelum/nox-runtime

First publish (one-time setup)

If you haven't published the @caelum scope before:

npm login                                  # interactive
npm org create caelum                      # if the scope doesn't exist yet
# Confirm publishConfig.access is "public" in both package.jsons (already set)

What gets published

Each package.json has a files field that whitelists what npm includes:

  • @caelum/nox-parser ships: src/, README.md, LICENSE
  • @caelum/nox-runtime ships: src/, bin/, catalogs/, README.md, LICENSE

Tests, build configs, lockfiles, and test/ dirs are excluded.

Verifying a publish

npm pack @caelum/nox-runtime
tar -tzf caelum-nox-runtime-<version>.tgz | head -20

Confirm the tarball contains the expected files and no dev-only paths.

Rollback

If a publish goes out broken, deprecate (don't unpublish) within 24 hours:

npm deprecate @caelum/nox-runtime@<version> "broken release, use <previous>"

After 72 hours npm restricts unpublish for security reasons. Don't get there.