Versioning
All packages follow Semantic Versioning (MAJOR.MINOR.PATCH):
| Bump | When |
|---|---|
| MAJOR | Breaking change in the public API or in the OpenAPI schema contract |
| MINOR | New backward-compatible feature or schema addition |
| PATCH | Bug fix, performance improvement, or internal refactor with no API change |
Each package is versioned independently — a change in one package does not require a version bump in the others, unless it affects the shared schema contract or cross-package compatibility. The three lines have drifted apart historically and are not expected to meet: the compatibility that matters is with the contract, not between the package numbers.
The paid package of a library is the exception: it shares the version of the free one and the two are released together. The website has a version of its own, which is not shown on the site.
The OpenAPI contract is versioned through its own info.version field and is bumped together
with any package that introduces a schema-level change.
Changelogs
Changes are tracked per package — free and paid separately — plus one project-level changelog for the contract itself:
| Changelog | Covers |
|---|---|
| Project & API contract | OpenAPI schema changes (versioned [schema X.Y.Z]) and project-level documentation |
| Python library | habarico (PyPI) releases |
| Python library (premium) | habarico-enterprise (PyPI) releases |
| Ruby library | habarico (gem) releases |
| Ruby library (premium) | habarico-enterprise (gem) releases |
| Node library | habarico (npm) releases |
| Node library (premium) | @eluvia/habarico-enterprise (npm) releases |
All of them follow the Keep a Changelog convention:
unreleased work accumulates under [Unreleased], which is renamed to the version on release, and
every release gets an entry. Changes that require action from library users are prefixed with
BREAKING:.
Documentation versions
The documentation is versioned with the library it documents. The site you are reading shows the
newest release of each library; the bar above a page names it — Python 5.11 — and opens a menu
of the other versions of that library, with a link to its changelog, which is where "what changed
between two releases" is answered.
Pages belong to a minor series, not to a single release: the documentation you read under
5.11 describes the whole 5.11 line, including its patch releases.
The paid package of a library shares its version: habarico-enterprise 5.11 goes with
habarico 5.11, so the series on a page is the series of both, and a page of a paid feature
carries a Premium badge and no second number.
The API reference is the newest released contract, which is versioned separately from the libraries — a library release decides which contract you get. The bar above a library page therefore names that contract as well and links to the reference.
Earlier versions
Every publish of the site keeps a snapshot of itself, under /s/<id>/: the whole site as it was
that day — concepts, the three libraries, the API reference, its own search — and it is never
rebuilt afterwards. When a library moves to a new series, the snapshot in which the old series was
last current is what the version menu offers for it. The menu shows the newest series and five
behind it; Versions lists every one.
A snapshot is another build of the site, so switching versions lands on the front page of the version picked, not on the same page — and the version menu of a snapshot still knows about the series released since, because it reads the list of versions from the current site rather than from the snapshot. A fix on an older series is published as a new snapshot of that series, which replaces the one the menu pointed at before.