Skip to content

0004 changelog and versioning

github-actions[bot] edited this page Nov 18, 2026 · 1 revision

Conventional Commits, Keep a Changelog and Semantic Versioning

Status: accepted · Implementation: done · Date: 2026-11-18

From LibreLifts ADR 0017. How a version is chosen and which files carry it are spelled out here; LibreLifts left them open. Built 2026-11-18: CHANGELOG.md, the version 0.0.0 in package.json, and the rules in docs/workflow.md.

Context

A commit message describes a change for the people who work on the code. Someone who uses LibreBars needs something else: what changed between one release and the next, and what a version number means. A changelog can be generated from commits, but commits are written for developers, and one change a person notices is often many commits.

Decision

  • Commit messages follow Conventional Commits 1.0.0: <type>(<scope>): <description>. The types in use are feat, fix, docs, chore, ci, refactor and test. The scope is the app or package the commit changes (app, api, web, engine, ui, data, contracts), or decisions, and is left out when the commit is about the repository as a whole. A breaking change takes ! after the type and a BREAKING CHANGE: footer.
  • One changelog, CHANGELOG.md at the root, in the Keep a Changelog 1.1.0 format. It is written by hand, for the people who use LibreBars.
  • Changes are collected under [Unreleased], grouped as Added, Changed, Deprecated, Removed, Fixed and Security. A commit that changes something a person using the product would notice adds its line in that same commit.
  • Versions follow Semantic Versioning 2.0.0. The repository has one version, carried by every package.json and by the app's configuration, and they change together. It is 0.0.0 until the first release.
  • The version is chosen at release time from the commits since the last release: a feat raises the minor number, and a release with only fixes raises the patch number. While the version is 0.y.z, a breaking change raises the minor number too. 1.0.0 is the first release of the app in the stores.
  • A release is one commit, chore(release): X.Y.Z, that renames [Unreleased] to [X.Y.Z] - YYYY-MM-DD, updates the links at the foot of the changelog and sets the version. main is then moved to it and tagged (0003).

Consequences

  • A commit has one more thing to do when it changes something a person would notice. Changes that only matter to developers stay out of the changelog.
  • The changelog and the history can disagree. The pull request checklist is the reminder; nothing enforces it.
  • One version covers the app, the website and the API. Releasing them separately would take a new record.
  • Until 1.0.0 anything may change between two releases.

LibreBars

Clone this wiki locally