Creating a release

The build is fully automated. The maintainer's job is to cut a branch, bump versions, tag, and promote the resulting draft.

This page is the maintainer playbook: a single linear flow for cutting a release, plus a shorter flow for hotfixes.

Branching model

Releases live on their own long-running branch, named models-X.Y.x (e.g. models-5.6.x for the 5.6 line). master is reserved for the next dev cycle.

master ──●──●──●──●──●──●──●──── (dev work, 5.7.x anchor)
               │
               └─ models-5.6.x ──●──●── (release-5.6.0, release-5.6.0.1, ...)

check-pr.yml runs on PRs to both master and any models-*.x branch, so hotfix PRs against the release line get full CI.

Model version fields are bumped per PR during dev, not at release time – see Model version discipline in the developers portal. The release flow below assumes that rule has been followed.

Cutting a new even-minor release

End-to-end flow for release-X.Y.0. Do these in order.

1. Confirm master is ready

Last nightly green on master. No outstanding changes you don't want in the release – revert or hold anything that should wait.

2. Cut the release branch

git checkout master
git pull
git checkout -b models-5.6.x
git push -u origin models-5.6.x

3. Bump master to the next dev anchor

On master, push the next odd-minor release-5.7.0 tag so git describe produces sane version strings during the new dev cycle. Without this, nightly builds carry the wrong version.

git checkout master
git tag release-5.7.0
git push origin release-5.7.0

4. Write release notes (on models-5.6.x)

git checkout models-5.6.x

• Update RELEASE_NOTES.md – one section per task, end-user language. This lands verbatim in the GitHub release body.
• Sanity-check versions. Walk through each model and verify its version in model.yaml reflects what actually changed since the last release. If a model changed but the version didn't move, that's a missed bump on the original PR – fix it here as a catch-up, but it shouldn't be routine work.
• Open a PR to models-5.6.x if the notes need review; otherwise commit straight.

5. Tag the release

git tag release-5.6.0
git push origin release-5.6.0

Even minor only. Odd-minor tags (release-5.5.0, release-5.7.0) are dev anchors and must not trigger a release – the workflow's tag filter excludes them, but don't push one expecting a release.

6. Verify the draft

The release workflow publishes a draft at release-X.Y.Z with .dtmodel artifacts and versions.json attached. Open the draft and verify:

• Every expected .dtmodel is attached.
• versions.json matches what you bumped.
• RELEASE_NOTES.md rendered correctly in the body. Refine wording inline if needed.

7. Publish

Click Publish release. Users running the matching darktable build see updates in preferences → AI – no manual notification needed.

8. Announce

Mention it in the usual darktable channels (matrix/irc, blog, social) with a link to the GitHub release. The release notes body is the source of truth – keep external announcements in sync with what's there.

Cutting a hotfix (release-X.Y.Z.1)

Same automation, shorter flow.

1. Fix on master first

Land the fix on master normally – PR, review, merge. The fix is now in the next dev cycle automatically.

2. Cherry-pick onto the release branch

git checkout models-5.6.x
git pull
git cherry-pick <sha-from-master>
git push origin models-5.6.x

The version bump should already be in the cherry-picked commit (per the version discipline rule). If it isn't, that's a missed bump on the original PR – add it now as a small follow-up commit on models-5.6.x.

3. Tag the hotfix

git tag release-5.6.0.1
git push origin release-5.6.0.1

Four-component form. The release workflow runs the same matrix.

4. Verify and publish the draft

Same as steps 6–8 above – verify the draft, refine the body if needed, publish, announce if the fix is user-visible.

What not to do

• Never git push --force a release tag. To replace a release, cut a new hotfix tag.
• Don't ship a hotfix that isn't on master. The release branch is for backports only; otherwise the next dev cycle silently regresses.
• Don't tag from master once the release branch exists. Release tags belong on models-X.Y.x.
• Don't skip the dev anchor push after cutting the release branch – nightly builds rely on it for version derivation.