Skip to content
agents-cli

Releases

agents-cli follows Semantic Versioning 2.0.0 and Conventional Commits 1.0.0. The full process is documented in RELEASING.md in the repo; this page summarises the rules.

Versioning

A version is MAJOR.MINOR.PATCH:

BumpWhen
MAJORBackwards-incompatible change to the CLI surface, on-disk layout, audit-log schema, or installer contract.
MINORNew feature, fully backwards compatible.
PATCHBug fix, internal refactor, doc/CI change. No behaviour change for users.

The version is enforced by a CI guard against the scripts/commit-lint.sh output: a feat!: or BREAKING CHANGE footer requires a major bump; a feat: requires at least a minor bump.

Commits

All commits on main use Conventional Commits:

<type>(<scope>): <imperative summary>


<body explaining why>


<trailers>
TypeUse for
featNew feature for users.
fixBug fix.
docsDocumentation only.
refactorCode change without behaviour change.
testAdding or updating tests.
choreMaintenance, deps, config.
perfPerformance improvement.
ciCI/CD config.

Breaking changes use ! after the type (feat!:) and an explicit BREAKING CHANGE: footer with the migration steps.

Changelog

Every release adds a section to CHANGELOG.md following Keep a Changelog 1.1.0. The next release’s section lives under ## [Unreleased] until the bump.

Process

  1. Open an MR with the change. Title and commits follow Conventional Commits.

  2. Update CHANGELOG.md under ## [Unreleased] with a one-line entry per change. Reference the issue or MR number.

  3. Get CI green. Get an approval.

  4. Merge to main.

  5. When ready to release, run the bump helper:

    Terminal window
    scripts/release.sh vX.Y.Z

    The helper:

    • Verifies you’re on main with a clean working tree.
    • Verifies the bump matches the changes since the last tag (feat! → major required, feat → minor required, otherwise patch is fine).
    • Renames the Unreleased section to [X.Y.Z] - YYYY-MM-DD.
    • Commits and tags vX.Y.Z.
    • Prints the next steps (push tag, watch pipeline).

  6. Push the tag. The CI pipeline picks it up and runs release → publish:

    • release — GoReleaser builds for Linux/macOS × amd64/arm64, generates checksums.txt, publishes the GitLab Release.
    • publish:r2 — Mirrors the binary archives + install.sh + latest.txt to chagbrasil-installers (R2). See ADR-005.
    • publish:site — Builds this site and uploads it to chagbrasil-acli-site (R2) under docs/vX.Y.Z/. Syncs docs/latest/. Updates docs/latest.txt. See ADR-006.
    • verify:install-url + verify:acli-site — Smoke checks (allow_failure: true).

  7. Once the pipeline is green, the Releases page shows the new version, acli.chagbrasil.com/install/ serves it, and this site is reachable at /docs/vX.Y.Z/.

Artefacts

SurfaceURL
Release notes (canonical)GitLab Releases
Installer + binarieshttps://acli.chagbrasil.com/install/...
This site (current)https://acli.chagbrasil.com/docs/latest/
This site (per version)https://acli.chagbrasil.com/docs/vX.Y.Z/
ChangelogCHANGELOG.md

Pre-release versions

Pre-releases use SemVer pre-release suffixes (v2.1.0-rc.1). The CI pipeline tag matcher is ^v\d+\.\d+\.\d+$ — pre-releases do not trigger release or publish. To publish a pre-release, push a final tag (v2.1.0-rc.1 → v2.1.0).