Release Process

This page is a practical checklist for cutting a v0.1-style public release.

Before tagging

• Build the server.
• Run the main tests selected for the release.
• Run documentation build.
• Build and verify the local product archive.
• Run license checks.
• Run at least one benchmark smoke test.
• Confirm the README points to the right docs.
• Confirm limitations and roadmap are current.
• Confirm the license change date is correct for the release.

Do not tag from memory. The release should be reproducible from the commands in this page and the repository state at the tag.

Documentation checks

python3 docs/build.py

Review:

• home page;
• tutorial;
• limitations;
• license;
• benchmarks;
• release notes.

Also click through the documentation sidebar. The first impression matters: a broken docs navigation makes the database look less credible before anyone runs a query.

Artifact checks

make package-verify

This builds the release binary, creates target/aiondb-local-<os>-<arch>.tar.gz, writes a .sha256 checksum file, writes a .files.sha256 content checksum file, writes a .manifest, writes a .manifest.json, verifies the archive checksum, checks that the manifests match the checksum files, checks that the archive contains the expected binary, README, license, security, governance, integration smoke, install notes, Kubernetes profile, systemd service, and systemd environment example files, then extracts the archive and verifies every packaged file before checking aiondb --version and aiondb --help first-run surface. The tarball normalizes file order, owner/group metadata, mtimes, and gzip headers for reproducible packaging from the same inputs. A public release should publish the archive, checksum, content checksum, manifests, and release notes together.

The local manifests are deliberately simple. They record the archive name, binary version output, git commit when available, worktree dirty status, archive path, archive checksum path, content checksum path, dependency inventory path, SPDX SBOM path, inline archive SHA256, inline dependency inventory SHA256, and inline SPDX SBOM SHA256. The JSON manifest also links to the dependency inventory and SPDX SBOM, and lists each packaged file with its SHA256 digest for release tooling. Signed provenance is a later hardening step, but unsigned archives without checksums should not be treated as release artifacts.

To explicitly check that local packaging is reproducible for unchanged inputs:

make package-reproducible

To collect the publishable local files into one directory:

make release-local

This creates target/release-artifacts/aiondb-local-<os>-<arch>/ after running package-verify. Publish that directory's archive, checksum files, manifests, dependency inventory, SPDX SBOM, SHA256SUMS, and README.txt together. The dependency inventory is generated from Cargo.lock by make dependency-inventory; the SPDX SBOM is generated by make spdx-sbom.

To verify a release artifact directory after it has already been created:

make release-verify RELEASE_VERIFY_DIR=target/release-artifacts/aiondb-local-<os>-<arch>

This checks the directory's exact file set, SHA256SUMS, archive checksum, legacy manifest, JSON manifest, dependency inventory, SPDX SBOM, content checksum file, and the tarball's actual file digests.

CI runs make product-smoke in the Product Surface job and uploads target/release-artifacts/ as the aiondb-local-release-artifacts workflow artifact. The upload action is pinned by commit. Use that artifact for review evidence; cut public release assets from a clean tagged checkout.

Check workflow action pinning explicitly:

make ci-policy

This requires GitHub Actions to be pinned by commit SHA, with only documented exceptions such as the Rust toolchain installer channel.

Validate the deployment profiles:

make deployment-validate

This always runs the static AionDB Docker, Compose, Kubernetes, and systemd policy check. It rejects untagged or latest Docker/Compose/Kubernetes image references. Where Docker is available, it also runs docker compose config. make docker-validate remains available as a compatibility alias.

Product smoke gate

make product-smoke

This is the local release-candidate smoke gate. It runs formatting checks, workspace compilation, CI policy checks, storage compatibility tests, observability route tests, CLI dump/restore checks, static documentation generation with local link checking, package reproducibility checks, verified package creation, and local release artifact collection. It also validates the local deployment profiles. It does not replace full CI, clippy, coverage, ecosystem compatibility, or long-running benchmarks.

Release notes

The release notes should include:

• included surfaces;
• known limits;
• compatibility status;
• benchmark caveats;
• license summary;
• upgrade warning for alpha data directories.

Release notes should avoid vague claims. Prefer "pgwire server surface is available for evaluation" over "PostgreSQL compatible database" unless the compatibility matrix supports the broader claim.

Benchmark checks

At minimum, a public release should include one benchmark smoke command that can run from a fresh checkout. The output does not need to prove superiority; it needs to prove reproducibility.

Record:

• commit hash;
• command;
• hardware summary;
• durability mode;
• raw output location.

Tagging

Use a normal semantic version tag:

git tag v0.1.0

Only tag after the worktree contains the intended license and docs.

Before tagging, inspect the diff for accidental generated files, local data directories, secrets, and obsolete debug notes.

After release

• Keep benchmark commands reproducible.
• Capture external feedback as reduced issues.
• Prioritize bugs that block first-run experience, driver compatibility, or the tutorial.

Hotfix policy

For v0.1, hotfixes should be narrow:

• build failure;
• broken quickstart;
• license or packaging mistake;
• crash in the tutorial path;
• severe documentation error that misleads users.

Do not use a hotfix release for broad refactors.