Skip to content

Release process

Automax releases are cut from master after the local release check passes. The release check keeps source, generated documentation, runbook indexes, package metadata and operator-facing docs aligned before a tag is created.

Version policy

Use semantic version numbers in pyproject.toml.

  • Patch releases keep the public command and YAML contracts compatible.
  • Minor releases may add commands, plugin families or documented YAML features.
  • Major releases are reserved for deliberate public contract breaks.

Every released version must have a matching CHANGELOG.md section:

## 1.0.0

Release check

Run the full local gate before tagging:

scripts/release-check.sh

For package-only release validation:

scripts/package-release-smoke.sh --output-dir dist/package-release-smoke

The script verifies:

  • the CHANGELOG.md section for the package version;
  • generated plugin reference freshness;
  • example and documentation indexes through scripts/check-example-indexes.sh;
  • capability documentation through scripts/check-capability-docs.sh;
  • external plugin index policy through scripts/check-plugin-index-policy.sh;
  • public documentation freeze through scripts/public-docs-freeze-check.sh;
  • plugin smoke runbook index freshness;
  • policy/risk preflight for committed examples;
  • SQLite database smoke through scripts/database-smoke.sh;
  • Python source compilation;
  • Python 3.9 compatibility guardrails;
  • Ruff checks;
  • unit and documentation regression tests;
  • automax plugins coverage --strict;
  • strict MkDocs build;
  • source distribution and wheel package release smoke.

For a metadata-only pass while debugging documentation or CI wiring:

AUTOMAX_RELEASE_CHECK_SKIP_DOCS=1 \
AUTOMAX_RELEASE_CHECK_SKIP_PACKAGE=1 \
  scripts/release-check.sh

Tagging

After the release check passes and CHANGELOG.md describes the shipped changes:

git status
git tag -s v1.0.0 -m "Automax 1.0.0"
git push origin master v1.0.0

Use an unsigned tag only in repositories where signing is not configured:

git tag v1.0.0 -m "Automax 1.0.0"

Release evidence

Keep the following with the release record:

  • scripts/release-check.sh output;
  • runtime evidence from disposable hosts when the release changes runtime behavior;
  • dist/runtime-evidence-index.json generated with checksum verification;
  • JSONL run event stream exported with automax runs events;
  • runtime validation pack output from scripts/runtime-validation-packs.sh;
  • policy/risk preflight output from scripts/policy-risk-preflight.sh;
  • database smoke summaries when database behavior changed;
  • approval gate files for release operations that require sign-off;
  • automax plugins coverage --strict output for builtin and release-loaded plugins;
  • package smoke output for the built sdist and wheel;
  • scripts/release-readiness-report.sh output for the release record.