Releases

Maintainer reference for how agent-of-empires ships: a weekly automated cadence plus a manual emergency path.

Weekly cadence

At least one release per week. Every Wednesday at 09:00 UTC, .github/workflows/open-release-pr.yml opens a release-staging PR with a patch bump by default. Review it, edit the bump if the diff deserves more, and merge. Merging fires tag-release-pr.yml, which tags the merge commit, and the tag push triggers release.yml, which builds the platform binaries and publishes the GitHub release and the ClawHub artifact.

You can trigger the staging PR by hand:

gh workflow run open-release-pr.yml            # default: patch
gh workflow run open-release-pr.yml -f bump=minor

The workflow reads the current version from Cargo.toml, computes the next one, refuses to run if the tag or staging branch exists, bumps Cargo.toml and Cargo.lock on release-staging/vX.Y.Z, regenerates CHANGELOG.md with git cliff in the same commit, dumps every commit since the last v* tag into the PR body as a review summary, and opens the PR labeled release-staging with a <!-- release-version: X.Y.Z --> marker.

The PR body’s commit list is for maintainer review only. The user-facing CHANGELOG.md and release body are generated by git-cliff, grouped by conventional-commit prefix; see cliff.toml and CONTRIBUTING.md.

Adjusting the bump in flight. Edit Cargo.toml and Cargo.lock on the staging branch, update the marker in the PR body to match, and re-run git cliff --config cliff.toml --tag "vX.Y.Z" --output CHANGELOG.md. The tagger reads the version from Cargo.toml at the merge commit and cross-checks it against the marker, refusing to tag when they disagree.

Post-merge tagging

tag-release-pr.yml listens for merged PRs labeled release-staging on main. It checks out merge_commit_sha (immutable, whatever lands on main afterwards), reads the version from Cargo.toml, verifies Cargo.lock and the PR marker agree, refuses to tag an existing version, warns if main advanced, and pushes an annotated tag using RELEASE_TOKEN so downstream workflows fire (GITHUB_TOKEN would not).

Tagging the merge SHA rather than origin/main is what dissolves the race: a PR landing between the merge and the tag would otherwise leave the tag on a commit whose Cargo.toml no longer matches, failing release.yml’s validate step.

Emergency releases

prepare-release.yml is a manual workflow_dispatch that bumps the version, regenerates the changelog into the same commit, and pushes the tag directly to main, bypassing the staging PR. Use it for a critical fix that cannot wait for Wednesday, or when the weekly workflow is broken.

gh workflow run prepare-release.yml -f version=1.7.2

Versioning

Semver, with patch as the autopick. Go minor for user-visible features, new CLI subcommands, new config sections, anything behind a feat: commit. Go major for breaking config changes, removed CLI subcommands, or on-disk breakage needing maintainer attention beyond a migration. When uncertain, take the bigger bump.

Skill hubs

aoe ships a coding-agent management skill to two hubs from contrib/, and cargo xtask check-skill (run in CI) validates that both reference real CLI commands and follow each hub’s frontmatter rules.

  • ClawHub (contrib/openclaw-skill/) is published automatically by release.yml on every release. Its frontmatter must carry no top-level version:; ClawHub’s _meta.json and the --version flag are the source of truth.
  • Hermes (contrib/hermes-skill/) is PR-based and published by hand, so the in-repo copy is the source of truth and the hub copy drifts until you re-publish. Its frontmatter must carry a version:. Bump it, then run hermes skills publish contrib/hermes-skill --to github --repo NousResearch/hermes-agent (needs the hermes CLI and a GitHub token with fork permissions). Cadence is on change, not every release.