Skip to content

Versioning & Changelog

Summary

Every Aetos artifact — library or service — is versioned with Semantic Versioning and documents its releases in a Keep a Changelog file. The version file is the source of truth, the git tag must equal it, and a Drone guard enforces that equality before anything is published. Releases are cut manually; a tag is what triggers the pipeline.

This page pairs with 90 – Drone Pipelines: the version and tag contract is exactly what those three CI shapes consume.

The version contract

Artifact Source of truth Notes
Library (PyPI package) version in pyproject.toml check-version also reads it to skip duplicates
Library (npm package) version in package.json check-version also queries the registry to skip duplicates
Service (Docker) VERSION file at the repo root one line, x.y.z; the service reads it (build-arg) — never hardcode the version

Rules:

  1. One version per repository. No per-module versions.
  2. Tag = version. The git tag is bare SemVer (0.0.6), no v prefix, and it MUST match the version file byte-for-byte. The Drone guard fails the build otherwise — this is what stops a tag from silently publishing nothing.
  3. A release is a tag, created after the change is merged. The version bump and the changelog promotion travel inside the merge request (MR); the tag is added on the merged commit and pushed. See Tagging strategy.
  4. Never reuse a tag. If a release is wrong, cut a new patch version.

Pre-1.0 (0.y.z)

While a package is 0.y.z, 0.y is treated as the major line:

  • breaking change → 0.(y+1).0
  • new feature → 0.y.(z+1)
  • bug fix → 0.y.(z+1)

Once a package reaches 1.0.0, normal SemVer applies. Do not ship 1.0.0 until the public API is considered stable.

The changelog

CHANGELOG.md at the repo root, in Keep a Changelog form. It always has exactly one open [Unreleased] section with the change categories that apply:

1
2
3
4
5
6
7
8
## [Unreleased]

### Added
### Changed
### Deprecated
### Removed
### Fixed
### Security

On release you promote it — never delete history:

1
2
3
4
## [0.0.6] - 2026-03-07

### Added
- ...

and add a link reference at the bottom:

1
2
[Unreleased]: https://git.aetoskia.com/aetos/<repo>/compare/0.0.6...HEAD
[0.0.6]: https://git.aetoskia.com/aetos/<repo>/compare/0.0.5...0.0.6

Conventions:

  • Write entries for humans: one line each, imperative, referencing the user impact, not the commit hash.
  • Categories: Added, Changed, Deprecated, Removed, Fixed, Security. Omit empty categories.
  • Security fixes get their own entry even if the change is otherwise a bug fix.
  • Keep [Unreleased] current: add an entry in the same change that introduces the behaviour, not later.
  • The [Unreleased] heading is never renamed; copy its content into the new version heading and clear it.

Reconcile before releasing

[Unreleased] is a draft, not the source of truth. It is only trustworthy when it was maintained alongside each change; a long-running branch or a change that skipped the changelog leaves it stale, so it can silently under-report a release. Verify it against the change before you promote:

  1. List what actually changed since the last release: git log <last-tag>..HEAD and git diff --stat <last-tag>..HEAD.
  2. Compare that against [Unreleased]; add an entry for every user-facing change that is missing.
  3. Always show the proposed additions to the user and wait for approval before promoting. If an entry is ambiguous, ask rather than guess.

Only then promote. Never cut a release with a known gap between the diff and the changelog.

Tagging strategy (MR-based)

The release version is known while the change is still a merge request, so the bump travels with the change and only the tag is added afterwards:

  1. In the MR — reconcile [Unreleased] against the change (see Reconcile before releasing) and get the user's approval for any additions. Then set the intended release version: version in pyproject.toml or package.json (or the VERSION file) to x.y.z, and promote the changelog (below). Changelog entries and link references name the version/tag, never a commit id.
  2. Merge or squash the MR into main.
  3. Create the tag x.y.z on the resulting commit (the merge/squash commit).
  4. Push the tag (git push origin x.y.z) — Drone builds the release.

Because the version bump is inside the tagged commit, the guard's tag == version check can only fail if the wrong commit was tagged.

Agent-assisted tagging

The agent neither authors nor merges the MR, and never tags before the merge. After the user confirms the MR is merged/squashed and says to proceed:

  1. Wait for that explicit go-ahead.
  2. Find the commit that introduced the version bump:
  3. Python packages: git log -S 'version = "x.y.z"' -n 1 --format='%H %s' -- pyproject.toml
  4. npm packages: git log -S '"version": "x.y.z"' -n 1 --format='%H %s' -- package.json
  5. services: git log -S 'x.y.z' -n 1 --format='%H %s' -- VERSION
  6. Confirm that commit's version file equals x.y.z, then tag only that commit, lightweight and bare: git tag x.y.z <sha>.
  7. Do not push. Ask the user to push the tag: git push origin x.y.z.

Release checklist

  1. Confirm the quality gate is green and main is up to date.
  2. In the MR: reconcile [Unreleased] against the change being released — git log <last-tag>..HEAD and git diff --stat <last-tag>..HEAD — add any missing user-facing entries, and get the user's approval for the additions. Then move every [Unreleased] entry under the new version heading with the target date (## [x.y.z] - YYYY-MM-DD) and restore an empty [Unreleased] on top.
  3. In the MR: add the two compare-link references at the bottom of the changelog, naming the version/tag (never a commit id).
  4. In the MR: set the version file — pyproject.toml (version = "x.y.z"), package.json ("version": "x.y.z"), or VERSION — to the intended release version.
  5. Merge or squash the MR into main.
  6. Create the tag on the resulting commit: lightweight git tag x.y.z.
  7. Push the tag (git push origin x.y.z). Watch Drone: Type A publishes the wheel/sdist, Type B publishes the npm package, Type C builds and deploys the image; all three first assert tag == version.
  8. Do not reuse the tag if the run fails — fix and cut x.y.(z+1).

Why the guard matters

The version file and the tag are two facts that must agree; nothing in git enforces that by itself. A mismatch is not a theoretical risk — a package can be tagged 0.0.2 while its pyproject.toml still says 0.0.1, and the publish step (which compares the file against the index) then skips the build entirely, so 0.0.2 never reaches the index while looking like a release. The Drone guard turns that silent no-op into a hard failure.