Release Process

How to cut a new TimeTiles release. Versions follow SemVer  and the changelog uses the Keep a Changelog  format.

Versioning

TimeTiles uses standard SemVer : MAJOR.MINOR.PATCH with optional pre-release identifiers (-alpha.N, -beta.N, -rc.N).

• MAJOR — breaking changes to public APIs, data model, or migration path.
• MINOR — new features, backwards-compatible.
• PATCH — bug fixes only.
• Pre-release suffix — -alpha.N, -beta.N, or -rc.N for unstable builds leading up to a target version.

The current pre-1.0 phase is being shipped as v0.1.0-alpha.<N> while the API surface and data model stabilise. Once stable, releases will move to plain MAJOR.MINOR.PATCH tags.

When to release

Cut a new release when one of the following applies:

• A meaningful batch of user-facing changes has accumulated on main since the last tag.
• An integration depends on a fixed reference point.
• A milestone moment is worth marking in the history.

There is no fixed cadence — releases are intentional, not automatic.

Steps

1. Pick the next version

Decide whether the change set is a MAJOR, MINOR, or PATCH bump (or a new pre-release iteration). The Unreleased section of the changelog is the source of truth for what is going in.

2. Move Unreleased to a dated version in the changelog

Edit apps/docs/content/reference/changelog.mdx:

• Rename the ## [Unreleased] heading to the new version and date, e.g.
  ## [1.2.0] - 2026-09-15 or ## [0.1.0-alpha.5] - 2026-05-15
• Add a fresh ## [Unreleased] block above it for the next cycle.
• Group entries under ### Added, ### Changed, ### Fixed, ### Removed, ### Deprecated, ### Security (skip headings with no entries).
• Cross-check against git log <previous-tag>..HEAD --oneline so nothing relevant is missed.

3. Commit the changelog

git add apps/docs/content/reference/changelog.mdx
git commit -m "docs(docs): prepare <version> changelog"

4. Tag the release commit

git tag -a <version> -m "<version>
 
<short summary of the release — copy the headline points from the
changelog entry>"

Annotated tags (-a) are required so the message is preserved on GitHub.

5. Push commit and tag

git push origin main
git push origin <version>

The Deploy Documentation workflow rebuilds the docs site (including the changelog) on push to main. The Release Images workflow builds and publishes container images on tag push.

6. (Optional) Create a GitHub Release

gh release create <version> \
  --title "<version>" \
  --notes-from-tag

Add --prerelease for any version with a pre-release suffix (-alpha, -beta, -rc) so it does not show up as the recommended download.

Backfilling tags

When tagging existing commits after the fact, use the same annotated-tag command but pointed at the historical commit:

git tag -a <version> <commit-sha> -m "<message>"

The tagger date will reflect when the tag was created, which is fine — the commit date stays accurate.

Hotfixes

For urgent fixes between releases:

1. Land the fix on main as usual.
2. Cut a new PATCH release from main (or, post-1.0, from a release branch if maintaining older majors).
3. Note in the release message which prior version the fix supersedes.