Skip to content

releasing.md

Latest commit

 

History

History
69 lines (56 loc) · 3.72 KB

releasing.md

File metadata and controls

69 lines (56 loc) · 3.72 KB
Raw
title Release Procedure
description Versioning, cargo-dist artifacts, SBOM, provenance, and supply-chain checks.

Release procedure

Before tagging

  1. Run python3 scripts/check-skill-version.py. It must confirm exact lockstep across the CLI, atla-core, Cargo.lock, skills/atla-cli/compatibility.json, SKILL.md gate, and tag-pinned install docs. The tag-triggered workflow repeats this check with --tag "$GITHUB_REF_NAME".
  2. Rename the combined [Unreleased] section to [0.8.0] with the actual release date and restore an empty [Unreleased] section plus compare links.
  3. Run the workspace test, Python Ruff checks, fmt, Clippy, cargo machete, RustSec, MSRV, doc, CLI-surface, workflow syntax, and workflow-security checks (mise run workflow:check workflow:security).
  4. Run cargo-dist plan/local/global artifact smoke tests. Release CI also executes the host-compatible platform archive on macOS and Windows; a failing platform smoke blocks publication.
  5. Run mise run size:bloat and compare the dist profile crate breakdown with the previous release. This is diagnostic until a target-specific size budget is established.
  6. Run python3 scripts/verify-release-artifacts.py; it checks archive contents, sidecar/manifest hashes, CycloneDX 1.5, and SBOM component hashes. On the Ubuntu release runner, --execute-native also runs atla --version and atla --help from the native archive. The macOS and Windows verification matrix uses --platform-only --execute-native against the local archives before the release host can publish them.
  7. For bounded Jira and Confluence sandbox testing, follow Live Sandbox Smoke Testing. The ledger's finish command must report complete, with every selected remote operation classified and no active or trashed temporary resources.
  8. Confirm every uses: reference in .github/workflows/release.yml is a full commit SHA.
  9. Confirm release-job permissions are scoped (contents: write only on host).

Generated workflow policy

release.yml is based on cargo-dist 0.31.0 but intentionally differs from raw generated output:

  • GitHub Actions are pinned to full commits.
  • cargo-dist, rustup, and cargo-cyclonedx installer scripts are downloaded, checked against pinned SHA-256 values, and only then executed.
  • untrusted GitHub expression values enter shell steps through environment variables.
  • cargo-cyclonedx 0.5.9 is used instead of cargo-dist's older 0.5.5 template because 0.5.9 understands Cargo.lock v4 and includes registry checksums.
  • the SBOM describes the distributed atla binary, is renamed to atla.cdx.xml, and uses CycloneDX 1.5.

For this reason dist-workspace.toml contains allow-dirty = ["ci"]. Never regenerate and commit release.yml without reapplying these controls and rerunning the workflow security scan.

Artifact set

A release must contain platform archives/installers, installer .sha256 sidecars, sha256.sum, atla.cdx.xml, atla.cdx.xml.sha256, and the cargo-dist manifest. GitHub build-provenance attestations cover local and global artifacts. Installers verify archive checksums before installation; users can additionally verify the attestation with GitHub CLI.

Tagging

Use a signed, SemVer-compatible tag only after the release commit is reviewed:

git tag -s v0.8.0 -m 'atla v0.8.0'
git push origin v0.8.0

Do not push a release tag from a dirty or unreviewed tree. After publishing, install from each supported channel and run atla --version, atla completion bash, and a JSON dry-run smoke test. Install the skill from the exact release tag, run atla doctor --skill-version 0.8.0 --output json, and require skillCompatibility.compatible: true before completing the release.