Skip to content
Arka Platform

Release procedure

arka-deck is distributed exclusively via GitHub Releases (ADR 0004). The npm package stays intentionally private.

Prerequisites

Section titled “Prerequisites”
  • Push rights on main (maintainer).
  • GitHub token with write permissions on releases.
  • Clean local environment (git status clean).
  • All CI gates green on the branch to publish.

Step 1 — Prepare the version

Section titled “Step 1 — Prepare the version”

Before running the script, CHANGELOG.md must already contain an exact section for the target version:

## [X.Y.Z] - YYYY-MM-DD
Terminal window
./scripts/release.sh <X.Y.Z>

The script:

  1. Refuses to run outside main or with a dirty worktree.
  2. Verifies that the CHANGELOG.md section already exists for the version.
  3. Bumps package.json, root package-lock.json, adapters/inbound/web/ui/package.json and the UI lockfile.
  4. Runs npm run lint and npm test.
  5. Creates the DCO-signed release commit chore: release vX.Y.Z.

The script does not create a tag.

Step 2 — Push

Section titled “Step 2 — Push”
Terminal window
git push origin main
git tag vX.Y.Z
git push origin vX.Y.Z

The tag push automatically triggers the .github/workflows/release.yml workflow.

Step 3 — Automatic release workflow

Section titled “Step 3 — Automatic release workflow”

The workflow:

  1. Re-runs all CI gates.
  2. Builds dist + UI.
  3. Generates release SBOMs for root, UI and cortex-lite.
  4. Generates the arka-deck-X.Y.Z.tar.gz tarball with expected files (dist/, bin/, docs/, LICENSE, NOTICE, README.md, README.fr.md, CHANGELOG.md, SECURITY.md, CONTRIBUTING.md, CODE_OF_CONDUCT.md, AGENT-INSTALL.md, AGENT-INSTALL.fr.md, ROADMAP.md, .env.example, sbom/, package.json).
  5. Audits the tarball (scripts/check-release-tarball.mjs) — refuses leaked internal files and missing SBOMs.
  6. Computes the SHA256.
  7. Creates the GitHub Release with the tarball, SHA256, SBOMs and CHANGELOG.

Step 4 — Announce

Section titled “Step 4 — Announce”
  • Update the README version badge if needed.
  • Announce the release on GitHub Discussions / community channels.
  • Check the eventual doc static site deployment (if enabled).

Hotfix case

Section titled “Hotfix case”

For an urgent patch on the X.Y.Z version:

  1. Branch from the tag: git checkout -b hotfix/X.Y.Z+1 vX.Y.Z.
  2. Apply the fix.
  3. PR to main.
  4. Once merged: add the CHANGELOG.md section, run ./scripts/release.sh X.Y.Z+1, then push main, create git tag vX.Y.Z+1, and push the tag.

Signing and provenance

Section titled “Signing and provenance”
  • DCO sign-off on each commit (checked in CI).
  • GitHub Actions attestations on release artifacts (provenance).
  • Sigstore / cosign: planned but not yet active (see ROADMAP.md).

Versioning (SemVer)

Section titled “Versioning (SemVer)”

The project follows Semantic Versioning :

  • MAJOR: public breaking change (e.g. v2.0.0 = TUI removal).
  • MINOR: backward-compatible additions (e.g. new addon).
  • PATCH: backward-compatible fixes.

Sub-package versions (addons/cortex-lite/) may intentionally diverge (e.g. 0.1.0 for a pre-release module).

See also

Section titled “See also”