Versioning Guide

Semantic Versioning for Libraries

Libraries MUST use MAJOR.MINOR.PATCH: increment MAJOR for breaking changes, MINOR for backward-compatible features, and PATCH for fixes. Reset lower components to 0 when incrementing MAJOR or MINOR. Breaking changes MUST still appear under ### Breaking, first in the changelog release section, with migration instructions.

Go Modules

Go libraries use SemVer tags such as v0.x.y or v1.x.y, not vYYYY.M.N. At major version 2 or higher, their module paths MUST end in /vN with the matching major number.

Why

The Go module reference³ states: “If the module is released at major version 2 or higher, the module path must end with a major version suffix like /v2”. A calendar year in the leading position would therefore require a path such as /v2026.

A Go command-line tool that publishes no importable packages MUST use CalVer, with vYYYY.M.N tags. Such a tool MUST be built from its checkout or distributed as release artifacts: go install module@v2026.10.0 fails when the module path has no /v2026 suffix. A Go module that ships a command and importable packages is a library and MUST use SemVer instead.

# Do: build a command-only tool from its checked-out release.
git checkout v2026.10.0
go build ./cmd/mytool

# Don't: request a year-major tag through an unsuffixed module path.
go install example.com/team/mytool/cmd/mytool@v2026.10.0

Calendar Versioning

Release numbers MUST have exactly three dot-separated components:

YYYY.M.N

YYYY is the four-digit release year. M is the release month, from 1 to 12. N is the release’s number within that month, counting from 0. The month and counter MUST NOT contain leading zeros.

Choosing the Next Number

For the release’s year and month, projects MUST inspect the versions already released. If none exists for that month, the counter MUST be 0; otherwise it MUST be one greater than the highest counter already released in that month. Commit types and breaking changes MUST NOT change this calculation.

Compatibility and Dependency Ranges

A CalVer number does not signal compatibility. Breaking changes MUST be documented under Breaking Changes, independently of the release number.

Migration from Semantic Versioning

Non-library projects migrating to CalVer MUST simply follow their last SemVer release with the first CalVer release. Libraries MUST NOT migrate to CalVer. Previously published versions and tags MUST NOT be rewritten or re-tagged. Projects MUST update their version files, release templates, tag references, and changelog comparison links together.

Changelogs

Every project MUST maintain CHANGELOG.md following Keep a Changelog⁴, extended with ### Breaking as the first subsection of each release that contains breaking changes.

Format

The example below is for a CalVer project. Library changelogs MUST declare Semantic Versioning 2.0.0 instead and use SemVer release headings and comparison links.

# Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog,
and this project adheres to calendar versioning (`YYYY.M.N`).

## [Unreleased]

## [2026.10.1] - 2026-10-20

### Breaking
- Removed the legacy login endpoint; use `/api/v2/login`.

### Added
- Added profile editing.

### Changed
- Updated the dashboard layout.

### Deprecated
- Deprecated the old export format in favor of JSON.

### Removed
- Removed an unused example file.

### Fixed
- Fixed concurrent-session handling.

### Security
- Fixed an authentication bypass.

## [2026.10.0] - 2026-10-17

### Added
- First release of October.

[Unreleased]: https://github.com/user/repo/compare/v2026.10.1...HEAD
[2026.10.1]: https://github.com/user/repo/compare/v2026.10.0...v2026.10.1

Git Tags

Release tags MUST be the version prefixed with v:

# Do
git tag v2026.10.0

# Don't
git tag 2026.10.0

Conventional Commits

Projects SHOULD use Conventional Commits⁵ for commit messages. Types classify changes for release notes. For libraries, feat selects MINOR, fix selects PATCH, and a breaking marker takes precedence and selects MAJOR. For CalVer projects, commit types MUST NOT affect release-number arithmetic:

type(scope): description

[optional body]

[optional footer]

Breaking Changes

A breaking commit MUST retain the Conventional Commits ! marker or BREAKING CHANGE: footer. Its changelog entry MUST appear under ### Breaking, first in the release section, and state the migration.

Release Automation

Release automation MUST first classify the project: a library uses a SemVer bump from breaking, feature, or fix changes; anything else uses the next YYYY.M.N from the release date and release history. It MUST update version files, the changelog, and tag references consistently and put breaking changes under ### Breaking in both cases.

API and Package Versions

API URL or header versions identify contracts, not calendar releases:

/api/v1/users
/api/v2/users
Accept: application/vnd.myapi.v1+json

Projects SHOULD maintain at most two API contract versions simultaneously and MUST give at least six months’ notice before removing an old one.

Why

An API contract can survive many releases. Changing its URL every month would force migrations without any corresponding contract change.

Package metadata MUST carry the project’s release version: SemVer for libraries and CalVer for everything else. Publishing an application through a package manager does not make it a library unless other code can depend on its importable packages.

Language	Version location
Python	pyproject.toml, __version__
Ruby	version.rb, .gemspec
Go	Git tags; go.mod declares the module path
Rust	Cargo.toml
C#	.csproj, AssemblyInfo.cs
TypeScript	package.json

Keep a Changelog

A changelog validator MUST accept the additional Breaking section and the project’s SemVer or CalVer preamble. With kacl-cli⁷, commit .kacl.yml alongside CHANGELOG.md; this example configures CalVer, while libraries MUST use their Semantic Versioning 2.0.0 preamble:

# .kacl.yml
kacl:
  allowed_header_titles: [Changelog]
  allowed_version_sections: [Breaking, Added, Changed, Deprecated, Removed, Fixed, Security]
  default_content:
    - All notable changes to this project will be documented in this file.
    - "The format is based on Keep a Changelog,"
    - "and this project adheres to calendar versioning (`YYYY.M.N`)."

The validator image MUST be pinned, and local checks and CI MUST use the same command and working directory:

# Do: the tool reads CHANGELOG.md and .kacl.yml from /workdir.
# Exact release tag; verified from the container registry.
docker run --rm -v "$(pwd)":/workdir:ro -w /workdir mschmieder/kacl-cli:0.7.4 verify

# Don't: the tool cannot find CHANGELOG.md in its working directory.
# Exact release tag; verified from the container registry.
docker run --rm -v "$(pwd)":/src mschmieder/kacl-cli:0.7.4 verify