Release

Auwai uses semantic versioning for the product, the skill scripts, the knowledge schema, the ledger schema, and the four plugin bundles.

One version source drives the release:

VERSION;
skills/auwai/scripts/version.py;
extensions/plugin_common/capabilities.json;
generated plugin manifests and bundles;
the knowledge service health response;
package metadata.

make version-check fails if the first three disagree.

Before a release

Update VERSION and skills/auwai/scripts/version.py.
Update extensions/plugin_common/capabilities.json if the feature contract changed.
Run make plugins to regenerate the four bundles and the capability matrix.
Run make release-check.
Run the storage suite with disposable PostgreSQL, MySQL, and MariaDB URLs.
Run the local v6 regression and record the gates in docs/70-benchmarks/results.md.
Complete security sign-off.
Update CHANGELOG.md with the version, date, and migration notes.
Run make dist and make install-test on Python 3.10 and 3.13.
Commit the release branch and merge it before tagging.

Build artifacts

python -m pip install build
make dist

The dist/ directory contains:

auwai_kernel-<version>-py3-none-any.whl;
auwai_kernel-<version>.tar.gz;
auwai-plugins-<version>.zip;
auwai-plugins-<version>.tar.gz;
SHA256SUMS.

Verify the checksums:

cd dist && sha256sum -c SHA256SUMS

Clean install gate

make PY=python3.11 install-test

The target creates a fresh virtual environment, installs only the wheel, runs auwai --version, auwai doctor, indexes a fixture repository, builds a full-read plan, and starts a local knowledge service for a health check.

CI

The required matrix is:

Python 3.10, 3.11, 3.12, 3.13: lint, doctor, full unit suite;
PostgreSQL 16, MySQL 8.4, MariaDB 11.4: contracts and migrations;
macOS: the FSEvents watcher path;
plugin generation, parity, hook vectors, and installer dry runs;
wheel and sdist build, clean install, and release smoke;
documentation links, release claims, the static docs site, and the benchmark mock path. The static site build uses the same Markdown tree.

The release job runs only for a v* tag and depends on every required job. It builds the same artifacts and creates the GitHub release. A failed gate publishes nothing.

Tag and publish

git tag -a v1.0.0 -m "Auwai 1.0.0"
git push origin v1.0.0

The tag workflow rebuilds the artifacts from the tagged commit. Do not upload a local build in place of the workflow output.

Migration notes

Knowledge schema 1 through 3 is applied automatically. Use auwai serve --database "$AUWAI_DATABASE" --check and --migrate.
Startup refuses a schema newer than the release.
Local ledgers keep a schema_version meta key and refuse a database that belongs to another repository root.
A failed SQLite or PostgreSQL migration leaves the prior version. MySQL DDL can implicitly commit; take a backup first.

Rollback

Keep the previous wheel, plugin bundle, database backup, and checksum file. Do not downgrade a knowledge database in place. Restore the backup, install the previous wheel, and run --check before starting the service.