Skip to content

Release Process

This project uses Semantic Versioning: MAJOR.MINOR.PATCH.

  • MAJOR: breaking API or operator workflow changes
  • MINOR: backwards-compatible features and new capabilities
  • PATCH: backwards-compatible fixes, docs corrections, and small operational improvements

Workflow

  1. Branch from main for the release. Use a release branch such as release/v0.2.0 if you need a final stabilization pass before tagging.
  2. Update CHANGELOG.md. Move release-ready entries out of Unreleased into a dated version section.
  3. Run verification. At minimum run the checks that match the touched surfaces, such as make test-all, make lint, and any Docker-based smoke tests needed for the stack.
  4. Tag the release. Create an annotated tag like v0.2.0 from the release commit.
  5. Build and publish artifacts. Publish any release outputs affected by the change set, such as Controller and Dispatcher images, reference agent images, and Helm or runtime assets if they changed.
  6. Publish release notes. Open a GitHub release using the tagged version and summarize the shipped changes from CHANGELOG.md.
  7. Merge the release commit back to main if you used a separate release branch.

Breaking Changes

Breaking changes must be called out in three places:

  • CHANGELOG.md under the released version
  • the GitHub release notes for that version
  • any upgrade or operator-facing documentation touched by the change

When a change requires operator action, include the exact migration or rollout steps, not just a warning that something changed.