dbflux-release

name	dbflux-release
description	Prepare and create DBFlux releases under the trunk + short-lived release-branch model with git-cliff-generated changelogs and an automated nightly channel. Trigger: When user asks to create a release, bump version, tag a release, cut a release branch, or prepare release notes for DBFlux.
license	MIT

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

Channel	Tag pattern	Source branch	How it ships
nightly	nightly (rolling)	main HEAD	Automated cron — no skill action needed
rc	vX.Y.Z-rc.N	release/vX.Y	Tag push → CI
stable	vX.Y.Z	release/vX.Y	Tag push → CI

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

Changelog Model

The changelog is generated by git-cliff from conventional commits. The skill does not hand-edit CHANGELOG.md or rename [Unreleased] headers.

• cliff.toml at the repo root defines which commit types surface (feat, fix, perf) and which are dropped (chore, ci, docs, test, refactor, style).
• -rc.N and nightly tags are transparent: they do not close the [Unreleased] window. git-cliff accumulates commits since the last stable tag.
• The stable release body is git-cliff's rendering of every user-visible commit since the previous stable tag.
• CHANGELOG.md is kept in the repository and updated at release time by prepending 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: git-cliff changelog generation applies from v0.7.0 onward. 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.

Branch	Lifetime	Accepts	Tags produced
main	permanent	every new commit (features, fixes, refactors)	(none — nightly is rolling)
release/vX.Y	until EOL	cherry-picked fixes only (no new features)	vX.Y.Z-rc.N, vX.Y.Z, vX.Y.(Z+1)

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:

Tag pattern	Allowed source branch	GitHub release kind
vX.Y.Z-rc.N	release/vX.Y	prerelease
vX.Y.Z	release/vX.Y	stable (published)
anything else	(refuse)	draft (safety net)

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").

   • Prepend the new RC section to CHANGELOG.md:

     git-cliff --tag vX.Y.0-rc.0 --unreleased --prepend CHANGELOG.md
     git add CHANGELOG.md
     # fold into the same chore(release) commit as the version bump
     

     Do NOT use git-cliff -o CHANGELOG.md — that collapses all historical sections.

   • 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. Tag vX.Y.0-rc.0 on the release branch (see "Tag Procedure").

No CHANGELOG rename is needed. 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. Prepend the stable section to CHANGELOG.md:

   git-cliff --tag vX.Y.0 --unreleased --prepend CHANGELOG.md
   git add CHANGELOG.md
   # fold into the same chore(release) commit as the version bump
   

   Do NOT use git-cliff -o CHANGELOG.md — that collapses all historical sections.

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).

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
   cargo fmt --all -- --check
   cargo clippy --workspace -- -D warnings
   cargo test --workspace
   

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.

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

Tag kind	GitHub Release	AUR	Nix flake (this repo)	nixpkgs (future)
-rc.N	prerelease	skip	bump release branch's + main's release-info	skip
Stable vX.Y.Z	published	bump + push	bump release branch's + main's release-info	bump + PR

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).
• Cutting a release/vX.Y branch from a main HEAD where .github/workflows/release.yml is missing the classify job.

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)