SIGNIA v0.1.5 — Initial Public Release

Releases

This document defines how SIGNIA is versioned, built, verified, and published. It is written for maintainers and release managers, but it is also useful for contributors who want to understand the release lifecycle.

Recommended file path: docs/release.md or RELEASES.md at repo root.
This file is intentionally detailed and prescriptive to keep releases consistent and auditable.

---

Table of contents

• Release goals
• Versioning policy
• Release artifacts
• Branching and tags
• Release cadence
• Pre-release checklist
• Build and verification pipeline
• Changelog process
• Publishing to GitHub Releases
• Crate publishing (optional)
• NPM publishing (optional)
• Python publishing (optional)
• Solana program releases
• Schema versioning and compatibility
• Security and signing
• Rollback and hotfixes
• Release roles and responsibilities
• FAQ

---

Release goals

SIGNIA releases should be:

1. Deterministic
   Builds should be reproducible and verifiable from source.

2. Verifiable
   Hashes, checksums, and (optionally) signatures must be published for binaries and packages.

3. Auditable
   Each release must document:

   • what changed
   • how it was built
   • what artifacts were produced
   • any breaking changes and migration paths

4. Composable
   Release artifacts must remain compatible across tooling:

   • CLI ↔ API ↔ SDK ↔ Console ↔ Registry program
   • schema/manifest/proof versioning must be explicit

5. Safe
   No secrets in CI logs, no unreviewed workflows, minimal permissions, dependency updates tracked.

---

Versioning policy

SIGNIA uses Semantic Versioning (SemVer): MAJOR.MINOR.PATCH

• MAJOR: breaking changes (public APIs, schemas, CLI flags, registry instruction ABI)
• MINOR: backwards-compatible features
• PATCH: backwards-compatible bug fixes

What counts as “public API”?

The following are public and semver-governed:

• signia-cli commands, flags, and output formats (unless explicitly marked experimental)
• signia-api HTTP endpoints, DTOs, and OpenAPI spec under docs/api/openapi.yaml
• sdk/ts and sdk/python exported APIs
• schema formats: schemas/v1/* and docs under docs/schemas/*
• determinism rules under docs/determinism/*
• on-chain registry interface: Anchor program instructions and account layouts

Internal refactors inside signia-core may be non-breaking unless they change outputs or determinism guarantees.

Pre-release versions

For early iteration:

• 0.y.z: APIs may still evolve more rapidly
• Pre-release tags: vX.Y.Z-alpha.N, vX.Y.Z-beta.N, vX.Y.Z-rc.N

Pre-release tags must still produce full artifacts and checksums.

---

Release artifacts

A SIGNIA release can include:

Rust

• signia CLI binary
• optional signia-api binary
• optional signia-interface binary (if a Rust service exists; otherwise Node build artifacts are used)

Container images

• signia-api image
• signia-console image
• signia-interface image (optional)

SDK packages

• TypeScript package from sdk/ts
• Python package from sdk/python

On-chain program

• signia-registry program build artifacts
• program ID, cluster, IDL hash, upgrade authority

Schemas and docs

• schemas/v1/*.json bundled in the release
• OpenAPI spec and docs snapshot (optional but recommended)

Checksums and provenance

• SHA256SUMS file for release artifacts
• SBOM (software bill of materials) if supported
• provenance attestation (SLSA) if enabled in CI

---

Branching and tags

• Development happens on main.
• Release tags are created on the commit that passed all required checks:
  • vX.Y.Z
  • or vX.Y.Z-rc.N

Tags should be annotated:

git tag -a vX.Y.Z -m "SIGNIA vX.Y.Z"
git push origin vX.Y.Z

---

Release cadence

No strict cadence is required, but recommended:

• Patch releases: as needed (bug fixes, security)
• Minor releases: every 2–6 weeks during active development
• Major releases: when APIs stabilize or a compatibility boundary is crossed

---

Pre-release checklist

Repository hygiene

• All workflows green on main
• No unreviewed workflow changes
• pnpm-lock.yaml present and consistent
• Rust builds use --locked
• cargo deny / cargo audit checks pass
• CodeQL completes successfully (if enabled)

Version bumps

• Update VERSION file
• Update crate versions (if publishing crates)
• Update sdk/ts version (if publishing NPM)
• Update sdk/python version (if publishing PyPI)
• Update CHANGELOG.md

Compatibility checks

• CLI compiles on Linux/macOS/Windows (at least CI targets)
• API boots and passes integration tests
• Console builds successfully
• Example flows pass (compile → verify → publish(devnet))
• Determinism roundtrip tests pass
• Schema validation tests pass against schemas/v1/*

Solana program (if included)

• anchor test passes
• Account layout changes documented
• Upgrade strategy decided (upgrade authority, timelock if used)
• Program ID and cluster recorded

---

Build and verification pipeline

This section mirrors typical CI behavior. Local builds should follow the same steps.

1) Clean build

./scripts/build_all.sh

2) Run all tests

./scripts/test_all.sh

3) Lint

./scripts/lint_all.sh

4) Produce release binaries

Recommended:

• Build CLI:

  cargo build --release --locked -p signia-cli

• Build API:

  cargo build --release --locked -p signia-api

5) Produce checksums

From a directory containing release outputs:

sha256sum * > SHA256SUMS

6) Verification gates

Before publishing, confirm:

• SHA256SUMS matches artifacts
• example outputs match expected fixtures where applicable
• schema validation passes

---

Changelog process

CHANGELOG.md should include:

• Added / Changed / Fixed / Deprecated / Removed / Security sections
• Links to PRs and issues (if public)
• Explicit mention of breaking changes and migration notes
• For on-chain changes, list:
  • instruction ABI changes
  • account layout changes
  • PDA seed changes
  • program ID changes (if any)

Recommended workflow:

1. Contributors add a short changelog entry in PR body
2. Maintainers curate into CHANGELOG.md at release time

---

Publishing to GitHub Releases

What to attach

Attach a predictable set of artifacts:

• signia-<os>-<arch>.tar.gz (CLI)
• signia-api-<os>-<arch>.tar.gz (optional)
• SHA256SUMS
• RELEASE_NOTES.md (optional)
• schemas-v1.tar.gz (optional)
• openapi.yaml (optional)
• SBOM/provenance (optional)

Release notes template

Include:

• Summary
• Breaking changes
• Notable changes
• Fixes
• Upgrade notes
• Checksums and verification instructions

---

Crate publishing (optional)

If you publish Rust crates to crates.io:

• signia-core
• signia-plugins
• signia-store
• signia-solana-client

Best practices:

• publish leaf crates first (core) then dependents
• use cargo publish --dry-run before publishing
• ensure README and license metadata are correct

Example order:

1. signia-core
2. signia-plugins
3. signia-store
4. signia-solana-client

signia-api and signia-cli are typically not published as libraries.

---

NPM publishing (optional)

If you publish sdk/ts to NPM:

1. Ensure package.json version matches VERSION
2. Build:

   cd sdk/ts
   pnpm install --frozen-lockfile
   pnpm build

3. Publish:

   pnpm publish --access public

CI should publish only from tags and only with protected secrets.

---

Python publishing (optional)

If you publish sdk/python to PyPI:

1. Ensure pyproject.toml version matches VERSION
2. Build:

   cd sdk/python
   python -m pip install -U build twine
   python -m build

3. Publish:

python -m twine upload dist/*

---

## Solana program releases

The on-chain program is a special case: deploying code is not the same as tagging source.

### What must be recorded

For every program deployment:

- Cluster: `devnet` / `mainnet-beta` / localnet
- Program ID
- Deployed commit SHA
- Anchor version
- IDL hash
- Upgrade authority and signer policy
- Any post-deploy migrations or registry initializations

### Upgrade policy

- If upgradeable: define who holds upgrade authority and how upgrades are approved
- If immutable: explicitly document immutability and why

### Recommended “program release note” fields

- instruction changes
- account layout changes
- seed derivation changes
- event/log changes (if any)
- compatibility notes for clients

---

## Schema versioning and compatibility

Schemas live under `schemas/v1/`. A release must not silently change schema semantics.

Rules:

- `schemas/v1/*` only changes in backwards-compatible ways unless MAJOR bump
- new optional fields are allowed
- removing fie...