Releases and changes
Every version’s changes are written down in two places in the repository: a short entry in the changelog, and a longer file of release notes.
The changelog
Section titled “The changelog”CHANGELOG.md lists every release of TomeCMS, newest first, with its date. Its format follows Keep a Changelog, and versions follow Semantic Versioning. What has changed since the last release waits under “Unreleased”.
From 0.8.0 on, an entry is split into what was added, changed and fixed, how to upgrade, and what changed for theme, plugin and headless authors. Earlier entries are a short list. Every entry ends with a link to the version’s full notes.
Release notes
Section titled “Release notes”docs/releases/ holds one file per version, from 0.2.0.md on. Each file opens with the version’s date and its status. From 0.3.0 on, an “Upgrading” section says what the upgrade needs, such as the migrations to run and any new setting or dependency, and later files say what changed for theme, plugin and headless authors. Each of these files ends with a “Validation boundary” section: what was tested for that version, and what is still required before a production tag.
Before you upgrade an install, read the notes of every version after yours. Updating goes through the upgrade itself.
docs/releases/1.0.0.md also sets out the update path 1.0.0 supports, and records the acceptance runs of the managed install on real servers.
How a version is released
Section titled “How a version is released”Work happens on the develop branch. main holds released code, and changes only when develop is merged into it.
To release, bump the version in package.json on develop, turn the changelog’s “Unreleased” section into that version, write its notes in docs/releases/<version>.md, and set TOMECMS_VERSION in deploy/cloud-init.yaml to the new tag. CI fails until that line matches. Merging that into main releases it. CI runs on develop and on pull requests, not on main: the merge is a fast-forward, so the commit on main is one CI has already run on. A workflow waits until CI has passed on that commit, then tags it vX.Y.Z and builds the release from the tag: the image, its attestations, the update manifest and the GitHub release, whose notes are the version’s file. A merge that keeps the version releases nothing, a new version with no notes file stops before it is tagged, and a commit CI never ran on, such as a merge commit or a fix pushed straight to main, is not released.
What 1.x means
Section titled “What 1.x means”From 1.0.0, versions follow Semantic Versioning. A patch release, such as 1.0.1, only fixes. A minor release, such as 1.1.0, adds features and keeps everything that worked working, including the content API under /api/v1. A breaking change waits for 2.0.0. A managed install takes each of them from the admin, as Updating describes.
What 0.x meant
Section titled “What 0.x meant”The changelog’s header says that every 0.x version is a pre-1.0 release candidate, and none is meant for production. Up to 0.12.0, each set of release notes carries the status “Release candidate; not tagged for production”. From 0.12.1 on, each version is also tagged and published as a GitHub release, so an install’s “System” screen can check for it, and its notes say “Release candidate; tagged and published as a GitHub release, not for production”.
A 0.x install is upgraded in place, by running the deploy helper again on a newer checkout, as Updating describes.
The line does not carry over into 1.0.0. A 0.x install cannot become a managed 1.0.0 install in place: that move needs a fresh server, as Installing on a VPS explains.
From 0.11.0 to 1.0.0, TomeCMS was in a feature freeze and only fixes were merged. From 1.0.0, features are welcome again. How to contribute says what a pull request needs.