dbflux-release

When to Use

• Cutting a release branch from main
• Tagging a release candidate (-rc.N) or stable version (vX.Y.Z) from a release/vX.Y branch
• Tagging a patch (vX.Y.(Z+1)) from a release/vX.Y branch
• Bumping versions in versioned artifacts (Cargo, Nix, Windows installer) and, on stable releases, the external AUR PKGBUILD

Do not use this skill to cut nightly builds — nightly is fully automated via .github/workflows/nightly.yml (daily cron, no manual steps).

Channels

The -dev.N channel is retired. Do not create new -dev.N tags.

Changelog Model

Two artifacts: CHANGELOG.md in the repository is hand-curated, and the GitHub release body is generated by git-cliff from conventional commits. The skill edits the changelog only where the procedure below says so.

• cliff.toml at the repo root defines which commit types surface in the generated release body (feat, fix, perf) and which are dropped (chore, ci, docs, test, refactor, style).
• Every user-visible change already added its ## [Unreleased] bullet in the PR that made it. The skill does not write those bullets.
• -rc.N and nightly tags are transparent: they neither close the [Unreleased] window nor bound the generated range. git-cliff accumulates commits since the last stable tag.
• At the stable promote the skill renames the top ## [Unreleased] heading to ## [X.Y.0] - <date> (see "Promote to Stable"). Nothing generated is written into CHANGELOG.md there.
• Patch releases (vX.Y.Z, Z > 0) do prepend a generated section with git-cliff --prepend. Never run git-cliff -o CHANGELOG.md — a full regeneration collapses all historical sections into one range from the last stable tag.

v0.7.0 transition: patch sections have been generated by git-cliff since v0.7.x. The ## [0.6.0] and ## [0.6.0-dev.N] sections are hand-written baselines in CHANGELOG.md. They must never be regenerated.

Branching Model (read first — every action depends on this)

DBFlux uses trunk + short-lived release branches.

Inviolable rules:

• A commit is never authored on a release branch. It always lands on main first and is then git cherry-pick -x <sha> into the release branch.
• A release branch is never merged back into main.
• No new features enter a release branch once cut. Only bugfixes and the version bumps the release requires.
• main is always open for development.

Tag → Source-Branch → GitHub Release Mapping

The release workflow (.github/workflows/release.yml — classify job) classifies tags automatically:

The skill MUST refuse to create a tag whose pattern does not match the current branch.

Context Detection (always do this first)

Before any tagging or bumping action:

git rev-parse --abbrev-ref HEAD
git status --porcelain
git describe --tags --abbrev=0
git tag --sort=-v:refname | head -n 10

Resolve the context:

• Branch is main → "dev mode". Allowed: cut a new release/vX.Y.
• Branch matches ^release/v\d+\.\d+$ → "stabilization mode". Allowed: -rc.N, stable vX.Y.Z, patch bump.
• Any other branch → abort. Ask the user to switch to main or the appropriate release branch.

Working tree must be clean before any tag.

Versioning Rules

Source-of-truth for the workspace version is Cargo.toml ([workspace.package].version). All other manifests must be kept in lockstep.

On main:

main always carries X.(Y+1).0-dev.0, where X.Y is the minor currently being stabilized on release/vX.Y. This marker is set when release/vX.Y is cut and stays until the next release branch is cut. The nightly workflow derives the nightly version from it: X.(Y+1).0-nightly+<sha>. No -dev.N releases are published — the marker is development-only.

On release/vX.Y:

• Next RC: if last tag on the branch is vX.Y.Z-rc.N → -rc.(N+1). If none → -rc.0.
• Promote to stable: drop the RC suffix → vX.Y.0.
• Patch: increment Z → vX.Y.(Z+1). Never bump the minor on a release branch.

Cut Procedure: main → release/vX.Y

When stabilization for a minor begins:

1. Verify you are on main, clean tree, up to date with origin/main.
2. Verify .github/workflows/release.yml on main contains the classify job. If missing, fix on main first; otherwise the release branch will inherit a broken workflow and stable tags will publish as drafts.
3. Confirm the target minor vX.Y with the user.

4. Create the branch:

   git checkout -b release/vX.Y

5. On release/vX.Y:
   • Bump every versioned artifact to X.Y.0-rc.0 (see "Files to Bump").
   • Do not touch CHANGELOG.md here. The branch keeps the [Unreleased] block it inherited from main; the rename happens at the stable promote.
   • Commit: chore(release): cut release/vX.Y at vX.Y.0-rc.0.
   • Push: git push -u origin release/vX.Y.
6. Back on main:
   • Bump every versioned artifact to X.(Y+1).0-dev.0 (main now targets the next minor).
   • Commit: chore(version): move main to X.(Y+1).0-dev.0 marker.
   • Push.

7. Still on main, register the minor on the website (see "Website"). Only after step 5's push: the ref must exist on origin or every site deploy from main fails. Add the entry right after nightly in web/versions.json, without current (an RC is not the current release):

   { "id": "nightly", "ref": "main", "noindex": true },
   { "id": "vX.Y", "ref": "release/vX.Y" },
   { "id": "vX.(Y-1)", "ref": "release/vX.(Y-1)", "current": true },

   • Commit: chore(web): add vX.Y to the site versions.
   • Push.
8. Tag vX.Y.0-rc.0 on the release branch (see "Tag Procedure").

No CHANGELOG edit is needed at an RC. git-cliff generates RC notes from conventional commits automatically.

Promote to Stable

Run on release/vX.Y when the RC is clean:

1. Bump every versioned artifact from X.Y.0-rc.N to X.Y.0.

2. Rename the top CHANGELOG.md heading from ## [Unreleased] to ## [X.Y.0] - <today>, in the same commit as the version bump. Do not prepend a generated section here, and do not run git-cliff -o CHANGELOG.md.

   ## [Unreleased]     ->     ## [X.Y.0] - 2026-07-31

   The release job fails if this section is missing for the tag, so the step cannot be skipped silently.

3. Commit: chore(release): promote release/vX.Y to vX.Y.0.
4. Tag vX.Y.0 on the release branch and push branch + tag.
5. CI generates the stable release body via git-cliff (all user-visible commits since the previous stable tag).

6. On main, make vX.Y the site's current release: in web/versions.json, move "current": true from vX.(Y-1) to vX.Y.

   { "id": "vX.Y", "ref": "release/vX.Y", "current": true },
   { "id": "vX.(Y-1)", "ref": "release/vX.(Y-1)" },

   • Commit: chore(web): make vX.Y the current site version.
   • Push. The site deploys from main, so this switches /docs/ to vX.Y and the product version shown on the landing and compare pages to X.Y.0.

After the GitHub Release publishes, run post-release steps (see "Post-Release Channels").

Next Dev Cycle

main is bumped to X.(Y+1).0-dev.0 when release/vX.Y is cut (step 6 of the Cut Procedure). No further bump to main is needed after the stable tag ships. main has already been targeting the next minor throughout stabilization.

Tag Procedure (any tag)

1. Run local validation:

   cargo check --workspace
   python3 scripts/lint.py fmt --check
   python3 scripts/lint.py clippy
   cargo test --workspace

   scripts/lint.py covers only the first-party crates under crates/ and never lints or reformats the vendored crates under vendor/.

2. Confirm the versioned files match the tag exactly.

3. Create an annotated tag:

   git tag -a vX.Y.Z[-suffix.N] -m "vX.Y.Z[-suffix.N]"
   git push origin vX.Y.Z[-suffix.N]

4. The GitHub Actions release workflow takes over (build, git-cliff notes, publish/prerelease).
5. Only after the workflow completes and the release is verified, do the post-release steps.

Files to Bump

These must all carry the exact same version number per release:

• Cargo.toml — [workspace.package].version. Workspace crates inherit via version.workspace = true.
• flake.nix
• resources/windows/installer.iss
• Review (does not inherit workspace version): examples/custom_driver/Cargo.toml.

Post-release (requires published artifacts):

• nix/release-info.nix — see "Nix Bump" below.

Not per release: web/versions.json changes only at the cut, the stable promote and the EOL of a minor (see "Website").

Website

web/versions.json lists the documentation sets the site publishes, one per minor (fields documented in web/src/data/versions.ts). Every change is a commit on main, because the site deploys from main (.github/workflows/web.yml).

• The ref must exist on origin. web/scripts/fetch-docs.ts skips an unreadable ref with a warning, then the build fails rendering that version (No materialised documentation for version "vX.Y").
• The product version is read from each ref's Cargo.toml; never type it into the site.
• Site copy describing features of vX.Y lands on main no earlier than the commit that makes vX.Y current.

Cherry-Pick Discipline

A release branch should never contain commits that don't exist on main, except release-only commits (chore(release): ..., chore(version): ...).

# On main: land the fix.
git checkout main
# ...commit, push...

# On release branch: cherry-pick with -x to record the source SHA.
git checkout release/vX.Y
git cherry-pick -x <sha>

Sanity check: every non-release commit on release/vX.Y since branch-off should mention (cherry picked from commit ...) in its message.

Nix Bump

The flake exposes a prebuilt-binary package (dbflux-bin, default) backed by nix/release-info.nix. Refresh it after any published tag (rc or stable):

ver=X.Y.Z   # or X.Y.Z-rc.N
for arch in amd64 arm64; do
  hex=$(curl -fsSL "https://github.com/0xErwin1/dbflux/releases/download/v$ver/dbflux-linux-$arch.tar.gz.sha256" | awk '{print $1}')
  nix-hash --to-sri --type sha256 "$hex"
done

Update nix/release-info.nix: version, both url lines, both hash lines.

Verify locally before committing:

nix build .#dbflux-bin --no-link --print-out-paths

AUR Bump

AUR is bumped only for stable tags (vX.Y.Z without suffix), in an external AUR repository (no PKGBUILD in this repo).

AUR pkgver does not allow -. For stable releases: pkgver=X.Y.Z (no translation needed).

Steps:

1. Update PKGBUILD: pkgver=X.Y.Z, reset pkgrel=1.
2. Regenerate .SRCINFO: makepkg --printsrcinfo > .SRCINFO.
3. Commit + push to the AUR remote: git commit -am "release: vX.Y.Z" && git push origin master.

Post-Release Channels

Anti-Patterns (explicit refusals)

Refuse, with a clear message, if any of these are requested:

• Tagging vX.Y.Z or vX.Y.Z-rc.N while HEAD is on main.
• Merging release/vX.Y back into main.
• Creating new features (non-fix commits) on a release/* branch.
• Bumping minor or major version inside a release/* branch.
• Pushing a tag without the working tree being clean.
• Pushing the AUR bump with pkgver containing a hyphen.
• Creating a new -dev.N tag (this channel is retired; use nightly instead).
• Running git-cliff --prepend CHANGELOG.md at a stable promote: that file is curated, and the heading rename is the only edit there. --prepend belongs to patch releases.
• Cutting a release/vX.Y branch from a main HEAD where .github/workflows/release.yml is missing the classify job.
• Marking an RC minor "current": true in web/versions.json, or leaving the previous minor current after vX.Y.0 is published.
• Adding a web/versions.json entry before its ref is on origin, or deleting a release/vX.Y branch that an entry still points at.

Inspection Commands

# Current branch and cleanliness
git rev-parse --abbrev-ref HEAD
git status --porcelain

# Most recent tag and last 10 tags by version
git describe --tags --abbrev=0
git tag --sort=-v:refname | head -n 10

# Commits since last tag
git log "$(git describe --tags --abbrev=0)"..HEAD --oneline

# Preview what git-cliff would generate for the unreleased range
git-cliff --config cliff.toml --unreleased --strip header

# Cherry-pick provenance audit on a release branch
git log --grep='cherry picked from' release/vX.Y

Resources

• .github/workflows/release.yml — classification logic and artifact publishing
• .github/workflows/nightly.yml — daily automated nightly build
• .github/workflows/build.yml — reusable build jobs
• .github/release-template.md — installation section appended to every release body
• cliff.toml — git-cliff configuration
• Cargo.toml, flake.nix, nix/release-info.nix, resources/windows/installer.iss
• examples/custom_driver/Cargo.toml (standalone, review manually)
• web/versions.json — documentation versions the site publishes, and which one is current