oad/release

Steps

1. Version target:

• Read app/version.txt.
• Determine the bump from the actual diff content, not the branch name:
  • Feature or new capability: bump minor, e.g. 1.0.0 -> 1.1.0.
  • Bug fix, maintenance, docs, tests, or internal-only change: bump patch, e.g. 1.0.0 -> 1.0.1.
  • Patch-only releases stay patch-only: continue incrementing the patch number, e.g. 1.0.5 -> 1.0.6; do not bump minor just because there have been several patches.
  • Breaking change: ask whether a major bump is intended.
• Propose the calculated version and confirm with the user before applying it.
• Branch prefix (feat/, fix/, chore/) is not signal — judge from diff content.

1. Worktree check:

• Stop if dirty.

git status --short

1. Related GitHub issues:

• Before confirming the release, search for issues related to the actual diff and intended release notes. Do not rely only on branch names or commit subjects.

git branch --show-current
git log --oneline --no-merges main..HEAD
gh issue list --repo khuonghung/evoflux --state open --search "<keyword from diff or feature area>" --limit 20
gh issue list --repo khuonghung/evoflux --state all --search "<keyword from diff or feature area> in:title,body" --limit 20
gh issue view <issue-number> --repo khuonghung/evoflux --comments --json number,title,state,labels,body,comments

• Triage each related issue as included/fixed, partially included, not included, or unrelated.
• If the release fully fixes or ships an issue, include Fixes #<issue-number> or Closes #<issue-number> in the release PR body so GitHub closes it on merge; use Refs #<issue-number> when the release is related but should not close it.
• Tag included issues when useful for tracking. Prefer an existing milestone/label convention if present; otherwise create and apply a version label:

gh label create "included-in-v<version>" --repo khuonghung/evoflux --description "Included in v<version>" --color "0E8A16" || true
gh issue edit <issue-number> --repo khuonghung/evoflux --add-label "included-in-v<version>"

• Add a short issue comment when the relationship is not obvious, especially for partial inclusion or when using Refs instead of Fixes:

gh issue comment <issue-number> --repo khuonghung/evoflux --body "Included in the v<version> release PR: <pr-url>."

1. Documentation readiness:

• Before confirming the release, check whether the diff requires documentation updates. At minimum inspect the canonical feature catalogue and the current architecture/reference pages for touched areas.

git diff --name-only main..HEAD
git diff --stat main..HEAD -- documents/features documents/architecture documents/reference documents/development README.md

• For user-visible features, behavior changes, install/update changes, or removed/deprecated functionality, update documents/features/README.md first; it is the canonical feature catalogue.
• Update the affected current-state pages under documents/features/, documents/architecture/, documents/reference/, or documents/development/. Use documents/plans/ only for design plans, not as the implemented contract.
• Update related files as needed, such as README.md, installation docs, agent/team docs, operation docs, and localized in-app Help for the affected area.
• If no documentation changes are needed, record the rationale in the release PR body (for example: Docs: no user-facing behavior changed).
• Include documentation updates in the feature branch before the version bump PR is created; do not leave release-blocking docs fixes until after publishing.

1. Confirm release:

Ready to release <version>. Proceed? (yes / no)

1. Version PR:

• Reuse the existing feature branch when present; do not spin a fresh release/ branch on top of it.
• Update all eight release-facing version files in lockstep, and include any generated lockfile version updates:
  • app/version.txt — source of truth, drives release.yml, release-desktop.yml, and tag names.
  • pyproject.toml — wheel/sdist version published to PyPI.
  • uv.lock — regenerated by uv sync, contains the new project version.
  • web/package.json — frontend package version (informational; not published).
  • desktop/src-tauri/tauri.conf.json — drives desktop artefact filenames (EVOFLUX_<ver>_*.dmg, .msi, .deb, .AppImage) and the About-panel version in the desktop app.
  • desktop/src-tauri/Cargo.toml — env!("CARGO_PKG_VERSION") in main.rs reads from here for the desktop About panel; keep it equal to tauri.conf.json or the version-consistency check fails.
• Why this matters: app/version.txt drives the tag name both release workflows use (v<X.Y.Z>), but bundled artefacts and app metadata read from the Tauri/Cargo files. If you bump only the Python/web/desktop files, CI fails because artefacts carry stale filenames or About-panel metadata. This actually happened on 1.0.8 for desktop artefact filenames — see the post-mortem commit in v1.0.8's history.
• If uv sync, cargo, or local tooling updates desktop/src-tauri/Cargo.lock for package versions, include those lockfiles in the release commit too.
• Metadata-only title: chore: bump version to <version>.
• User-facing change title: describe change, append range.
• Example: Fix frontend update restart (v0.3.3 -> v0.3.4).
• PR body must be a bullet list summarizing the included user-facing changes, not a single generic sentence.