Intentional Versioning 1.0.0

IntVer (repo) — bzgCC0 1.0

intver.svg

A release is a message

Intentional Versioning uses versions to tell who should care about a release. Version u.i.m addresses three audiences:

uUsers
The people who use the software. Incrementing u says: "Users, this release is for you."
iIntegrators
The people who build on top of the software: API consumers, plugin authors, packagers. Incrementing i says: "Integrators, this release is for you."
mMaintainers
The people who work on the software itself. Incrementing m says: "Maintainers, this release is for you."

Rules

  1. A version has the form u.i.m where u, i and m are non-negative integers.
  2. An increment means "this release deserves your attention", with "your" referring to users/integrators/maintainers, or integrators/maintainers or just maintainers.

Audiences

The default audiences – users, integrators, maintainers – fit most projects. If yours doesn't have distinct integrators, the i won't change much, and that's fine.

If you want to be explicit, define your audiences in your README:

This project uses Intentional Versioning (intver.org):

- Users: teachers and students
- Integrators: LMS plugin developers
- Maintainers: maintainers and core contributors

Badge for README.md:
[![versioning: intver.org](https://img.shields.io/badge/versioning-intver.org-blue.svg)](https://intver.org)

Badge for README.org:
[[https://intver.org][https://img.shields.io/badge/versioning-intver.org-blue.svg]]

Breaking changes

Version numbers say who should pay attention.

To say what breaks, you can use the git trailing BREAKING-CHANGE:, as recommended in conventional commits. Or you can use more specific git trailers:

feat!: Redesign the dashboard

New layout with improved accessibility.

Breaks-Users: The settings page has moved to the profile menu.
Breaks-Integrators: DashboardConfig.load() now returns a Result type.

Three trailers are available, one per audience:

The absence of a trailer means that nothing breaks.

FAQ

How is this different from Semantic Versioning?
SemVer encodes what changed, also trying to encode the importance (major/minor). IntVer encodes who should care. Semver tries to describe the code and signal its audiences at the same time, which creates tension: a bugfix can be breaking for some users and a major API change can be irrelevant to most. IntVer separates these concerns: the version number addresses audiences, git trailers describe what breaks.
Does incrementing u mean a breaking change?
No. It means users should pay attention to this release. It might be a new feature, a redesign or a breaking change. The nature of the change belongs in the changelog and in git trailers, not in the version number.
What if my project only has two audiences?
Then one of the three components won't change often. A CLI tool with no plugin system will rarely increment i. The scheme still works, it reflects the reality that this project doesn't have a distinct integrator audience.
What if a change is for users and integrators?
Then update the 'u' part. Implicitly, changes for users also deserve the attention of integrators and maintainers, and changes for integrators also deserve the attention of maintainers.
Can I use pre-release or build metadata (e.g. 1.2.3-beta)?
IntVer does not specify pre-release or build metadata conventions. You are free to adopt whatever convention suits your project.
Is IntVer compatible with tools that expect semver?
The format u.i.m is identical, so most tools will accept IntVer version strings. The meaning is different, but the structure is the same.