Package Tag Release Process

Package Tag Release Process

This repository contains the OpenCapTable DAML package and npm bindings. Releases use package-scoped tags, for example:

OpenCapTable-v34-v0.0.2

The last -v<semver> segment must match OpenCapTable-v34/daml.yaml. The package prefix must be a configured package from scripts/packages.ts; today that is ocp / OpenCapTable-v34.

Automated Release

Pushing a matching tag runs .github/workflows/release.yml.

The workflow:

1. Parses the tag with scripts/parse-release-tag.ts.
2. Fails early if the release tag is not the current origin/main commit.
3. Fails early if the current root package.json version is already published to npm.
4. Builds the package, backs up the current DAR, and runs the same lint, codegen, package, and DAML test checks used by CI.
5. Uploads the DAR to devnet and mainnet with npm run upload-dar.
6. Detects which networks (devnet/mainnet) already have factories for the current DAR package ID.
7. Creates factories on networks where they are missing with scripts/create-ocp-factory.ts.
8. Verifies dars/dars.lock.
9. Prepares npm package artifacts and publishes the npm package.
10. Commits changed release artifacts back to main when the tag still points at the current origin/main.

The tag version is the DAML package version from OpenCapTable-v34/daml.yaml. The npm version is the root package.json version and must be bumped before tagging when a new npm publication is expected.

Required GitHub Secrets

The workflow uses the committed public Canton topology in scripts/config/cantonPublic.ts. Secrets only need to provide OAuth client secrets for the providers:

CANTON_DEVNET_INTELLECT_LEDGER_JSON_API_CLIENT_SECRET
CANTON_DEVNET_5N_LEDGER_JSON_API_CLIENT_SECRET
CANTON_MAINNET_INTELLECT_LEDGER_JSON_API_CLIENT_SECRET
CANTON_MAINNET_5N_LEDGER_JSON_API_CLIENT_SECRET
NPM_TOKEN

The older generic names DEVNET_AUTH_TOKEN and MAINNET_AUTH_TOKEN are not enough for this repo's current client configuration because the upload script targets both Intellect and 5n provider clients.

Manual Checks

Before pushing a release tag, use Node.js 20, matching .github/workflows/release.yml, when running these checks locally.

node --version
npx tsx scripts/parse-release-tag.ts OpenCapTable-v34-v0.0.2
npm run build
npm run test

After a workflow run, confirm that dars/dars.lock, any new dars/ artifact, and generated/ocp-factory-contract-id.json were committed when they changed.