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”
Terminal window
./scripts/release.sh <X.Y.Z>

The script:

  1. Checks version number consistency (package.json, adapters/inbound/web/ui/package.json).
  2. Updates CHANGELOG.md ([Unreleased] section → [X.Y.Z] - <date>).
  3. Creates the chore(release): vX.Y.Z commit.
  4. Creates the signed vX.Y.Z tag.

Step 2 — Push

Section titled “Step 2 — Push”
Terminal window
git push origin main
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 the arka-deck-X.Y.Z.tar.gz tarball with expected files (dist/, bin/, docs/, LICENSE, NOTICE, README.md, CHANGELOG.md, SECURITY.md, CONTRIBUTING.md, CODE_OF_CONDUCT.md, AGENT-INSTALL.md, ROADMAP.md, .env.example, package.json).
  4. Audits the tarball (scripts/check-release-tarball.mjs) — refuses leaked internal files.
  5. Computes the SHA256.
  6. Creates the GitHub Release with the tarball, SHA256 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: ./scripts/release.sh X.Y.Z+1 then git push origin vX.Y.Z+1.

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”