Release cycle

How releases get cut, in detail.

Tag conventions

darktable-ai piggybacks on darktable's version scheme:

• Even minor (release-5.6.0, release-5.6.0.1) – real release. The release workflow fires and publishes a draft.
• Odd minor (release-5.5.0, release-5.7.0) – dev anchor only. Used by tools/get_git_version_string.sh so git describe produces useful strings during a dev cycle. The release workflow ignores odd-minor tags.

Hotfixes use a four-component tag: release-X.Y.Z.W – same workflow, same matrix.

Workflows

.github/workflows/:

Workflow	Trigger	Behavior
check-pr.yml	PRs to master or models-*.x	Runs setup → convert → validate → demo on every model touched. Per-PR concurrency – new pushes cancel in-progress runs.
nightly.yml	Push to master (dev cycles only), manual dispatch	Builds the full model matrix and publishes a rolling nightly-X.Y.Z pre-release. Concurrency: new master pushes cancel previous nightlies.
release.yml	Tags release-X.Y.Z with even Y (and release-X.Y.Z.W hotfix form)	Builds, publishes a draft release for the maintainer to promote from the GitHub UI.

Nightly behavior

The nightly publish step deletes every existing nightly-* release before publishing the new one. That's deliberate – it gives the new release a fresh created_at, which keeps the rolling pre-release at the top of the GitHub /releases page. Updating in place would freeze the timestamp at the original creation date and the nightly would slip down the page over time.

Nightly tag is nightly-X.Y.Z – derived from the X.Y.Z prefix of git describe. darktable parses this as a regular semver, so its release-discovery code matches it against the running build.

Dev-cycle gate

nightly.yml only fires on dev cycles (odd minor). The check happens early in the workflow: derive X.Y.Z from tools/get_git_version_string.sh, look at the minor digit, set is_dev=true for 1|3|5|7|9. Even-minor master pushes (i.e. between a release tag and the next dev cycle) skip the build matrix entirely.

Sync with darktable

Each release-X.Y.Z corresponds to a darktable release with the same version. Users on darktable 5.6.0 see versions.json from release-5.6.0 and download .dtmodel files from that release. Pre-release darktable builds (5.7.x) pick up the matching nightly-5.7.Z.

What "model update" means

If you bump a model's version in model.yaml between releases, the next nightly publishes both:

1. The rebuilt .dtmodel, with the new version baked into config.json.
2. The updated versions.json listing the new version.

darktable compares the installed model's version against the manifest. A mismatch surfaces as "update available" in the AI preferences pane.

Forks

All three workflows have a guard:

if: github.repository == 'darktable-org/darktable-ai' || github.event_name == 'workflow_dispatch'

Forks don't auto-build on push or tag. To build models on a fork (e.g. for testing), trigger the workflow manually via the Actions tab.