Releases

Cardinal keeps a hand-written CHANGELOG.md in the repository. Start there rather than with the generated release notes.

Why hand-written

The GitHub release for each tag lists the commit subjects since the previous one. That is a record of work, not of consequences: it cannot tell you that one entry means tokens issued before the upgrade are still outstanding, and another is a documentation fix.

For an identity system that distinction is the only reason to read a changelog, so the file marks Security entries separately and says what to do about them (re-run an erasure, treat old tokens as live) rather than leaving the reader to infer it from a subject line.

Before you upgrade

• Read the Security section for every version between yours and the target. Some entries need an action beyond deploying the new image.
• Migrations are expand-only: they never drop, rename, retype or narrow a column, and that is enforced by a test rather than by review. The previous build therefore keeps working against a newer schema, so rolling back is deploying the old image and nothing else.
• A change that cannot be additive declares itself in the migration header, and the reason is written into schema_migrations when applied, so an older build refuses to start against it rather than misreading it.

There is no supported upgrade path between pre-1.0 versions beyond that. The API can change in any release.

Version numbers

Semantic versioning, with the pre-1.0 caveat that the major number is 0 and so the minor number carries breaking changes. cardinal version reports the release, and every HTTP response carries X-Cardinal-Version. The agent sends its own in User-Agent, so a server can log when a host is running something newer than it.

Documentation for older releases

These pages describe the current release, and this site publishes only that. Cardinal is pre-1.0 and there is no supported upgrade path, so a reader on an older version is not doing anything wrong, but a page about a flag their binary rejects helps nobody, and keeping a tree of old documentation implies an old release is a reasonable one to be running when the gap includes schema changes and security fixes.

The documentation for a previous release is not gone: it is in the Cardinal repository's own history, at the tag for that release, which is where the code for it lives too. Read it there, against the version you actually run.