Add auto-version workflow and version script

Introduce an automated versioning pipeline: add .github/workflows/auto_version.yml that computes the next version (on push to main or manual dispatch with channel=stable|beta|dev), writes VERSION, commits and creates a v<version> tag. Add scripts/next_version.py which inspects git tags and commits (Conventional Commit style) to determine MAJOR/MINOR/PATCH bumps and numeric prerelease build numbers for beta/dev channels. Update .github/workflows/release.yml to detect 4-segment tags as prereleases and pass the prerelease flag to the GitHub Release action. Update docs/RELEASES.md to describe the automated versioning rules, bump logic, and usage (including how to preview or trigger stable releases). This automates consistent numeric-only versioning and prerelease handling for CI releases.

Author: themuffinator

.github/workflows/auto_version.yml

@@ -0,0 +1,65 @@
+name: auto-version
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+    inputs:
+      channel:
+        description: Release channel
+        required: true
+        default: dev
+        type: choice
+        options:
+          - stable
+          - beta
+          - dev
+
+permissions:
+  contents: write
+
+concurrency:
+  group: auto-version
+  cancel-in-progress: false
+
+jobs:
+  tag:
+    if: github.actor != 'github-actions[bot]'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      - name: Compute Version
+        id: version
+        shell: bash
+        run: |
+          channel="${{ github.event.inputs.channel }}"
+          if [[ -z "$channel" ]]; then
+            channel="dev"
+          fi
+          version="$(python scripts/next_version.py --channel "$channel" --write)"
+          echo "version=$version" >> "$GITHUB_OUTPUT"
+
+      - name: Commit and Tag
+        shell: bash
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add VERSION
+          if git diff --cached --quiet; then
+            echo "VERSION unchanged; nothing to tag."
+            exit 0
+          fi
+          git commit -m "chore(release): v${{ steps.version.outputs.version }} [skip release]"
+          git tag "v${{ steps.version.outputs.version }}"
+          git push
+          git push --tags

.github/workflows/release.yml

@@ -71,8 +71,19 @@ jobs:
           path: dist
           merge-multiple: true
 
+      - name: Determine Release Type
+        shell: bash
+        run: |
+          tag="${GITHUB_REF_NAME}"
+          if [[ "$tag" =~ ^v[0-9]+\.[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+            echo "PAKFU_PRERELEASE=true" >> "$GITHUB_ENV"
+          else
+            echo "PAKFU_PRERELEASE=false" >> "$GITHUB_ENV"
+          fi
+
       - name: Publish Release
         uses: softprops/action-gh-release@v2
         with:
           files: dist/**
           generate_release_notes: true
+          prerelease: ${{ env.PAKFU_PRERELEASE == 'true' }}

docs/RELEASES.md

@@ -1,26 +1,43 @@
 # PakFu Releases
 
 ## Versioning
-PakFu follows SemVer with an updater-friendly, numeric-only identifier.
+PakFu follows SemVer with an updater-friendly, numeric-only identifier. Versions
+are computed automatically from git history by GitHub Actions.
 
 Rules:
-- `VERSION` is the source of truth and must be strictly numeric dot segments
+- `VERSION` is written by automation and must stay strictly numeric dot segments
   (no leading `v`, no `-beta`/`-rc`, no `+git` metadata).
-- Git tags must be `v<version>` and match `VERSION` exactly.
+- Git tags are `v<version>` and must match `VERSION` exactly.
 - Stable releases use `MAJOR.MINOR.PATCH` (example: `1.4.0`).
 - Beta/dev releases use `MAJOR.MINOR.PATCH.BUILD` (example: `1.5.0.3`), and the
-  GitHub Release must be marked as **prerelease**.
+  GitHub Release is marked **prerelease** automatically.
 - Always increment the numeric portion for every published build; never reuse
   a version number.
 
 Why: the auto-updater compares versions using Qt's numeric `QVersionNumber`
 parsing, which ignores suffixes like `-beta`. Numeric-only identifiers keep
 update ordering reliable.
 
+Automatic bump rules (based on Conventional Commit style since the last stable
+tag):
+- Breaking change (`type!:` in the subject or `BREAKING CHANGE` in the body)
+  bumps **MAJOR** (or **MINOR** if `MAJOR=0`).
+- `feat:` bumps **MINOR**.
+- Everything else bumps **PATCH**.
+
+Stage/maturity rule:
+- While `MAJOR=0` (pre-1.0), breaking changes advance **MINOR** instead of
+  **MAJOR** to reflect ongoing development.
+
 Examples:
 - Stable: `1.2.0`
 - Beta/dev for the next stable: `1.3.0.1`, `1.3.0.2`
 
+Preview the next version locally:
+```sh
+python scripts/next_version.py --channel dev
+```
+
 ## Release Assets
 To enable in-app updates, attach platform packages to each GitHub Release.
 Current packaging targets:
@@ -32,12 +49,12 @@ Asset names should include platform hints (e.g. `win`, `mac`, `linux`, `x64`) so
 the updater can select the correct file automatically.
 
 ## Release Workflow
-1. Update `VERSION`.
-2. Commit changes and create a tag: `git tag vX.Y.Z` (or `vX.Y.Z.BUILD`).
-3. Push commits and tag: `git push && git push --tags`.
-4. GitHub Actions builds and uploads platform packages automatically.
-5. For beta/dev builds, ensure the GitHub Release is marked **prerelease** so
-   non-stable update channels can see it.
+1. Push to `main` (default: auto-creates a **dev** prerelease).
+2. The `auto-version` workflow computes the next version, updates `VERSION`,
+   commits, and tags it.
+3. The `release` workflow builds and publishes packages for the tag.
+4. For a stable release, run the `auto-version` workflow manually with
+   `channel=stable`.
 
 The release workflow uses the repository name as the update source and publishes
 the artifacts to the GitHub Release matching the tag.

scripts/next_version.py

@@ -0,0 +1,175 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+VERSION_RE = re.compile(r"^v?(\d+)(?:\.(\d+))?(?:\.(\d+))?(?:\.(\d+))?$")
+FEATURE_RE = re.compile(r"^feat(\(.+\))?:", re.IGNORECASE)
+BREAKING_RE = re.compile(r"^\w+(\(.+\))?!:")
+
+
+def run_git(args: list[str], cwd: Path) -> str:
+    try:
+        return subprocess.check_output(["git", *args], cwd=cwd, text=True).strip()
+    except subprocess.CalledProcessError as exc:
+        msg = exc.output if exc.output else str(exc)
+        raise RuntimeError(msg) from exc
+
+
+def parse_version(text: str) -> list[int] | None:
+    match = VERSION_RE.match(text.strip())
+    if not match:
+        return None
+    parts = [int(group) for group in match.groups() if group is not None]
+    if len(parts) < 3:
+        return None
+    return parts
+
+
+def format_version(parts: list[int]) -> str:
+    return ".".join(str(p) for p in parts)
+
+
+def read_version_file(path: Path) -> list[int]:
+    raw = path.read_text(encoding="utf-8").strip()
+    parts = parse_version(raw)
+    if not parts:
+        raise RuntimeError(f"VERSION is not numeric: {raw!r}")
+    return parts[:3]
+
+
+def list_tags(repo: Path) -> list[tuple[str, list[int]]]:
+    tags_raw = run_git(["tag", "--list", "v*"], cwd=repo)
+    tags = []
+    for tag in tags_raw.splitlines():
+        parts = parse_version(tag)
+        if parts:
+            tags.append((tag, parts))
+    return tags
+
+
+def latest_stable_tag(tags: list[tuple[str, list[int]]]) -> tuple[str, list[int]] | None:
+    stable = [(tag, parts) for tag, parts in tags if len(parts) == 3]
+    if not stable:
+        return None
+    return max(stable, key=lambda item: tuple(item[1]))
+
+
+def commits_since(repo: Path, base_tag: str | None) -> list[tuple[str, str]]:
+    if base_tag:
+        range_spec = f"{base_tag}..HEAD"
+    else:
+        range_spec = "HEAD"
+    log = run_git(["log", range_spec, "--pretty=format:%s%n%b%n==END=="], cwd=repo)
+    entries = [entry.strip() for entry in log.split("==END==") if entry.strip()]
+    commits = []
+    for entry in entries:
+        lines = entry.splitlines()
+        subject = lines[0] if lines else ""
+        body = "\n".join(lines[1:]) if len(lines) > 1 else ""
+        commits.append((subject.strip(), body))
+    return commits
+
+
+def classify_bump(commits: list[tuple[str, str]]) -> str | None:
+    if not commits:
+        return None
+    bump = "patch"
+    for subject, body in commits:
+        if BREAKING_RE.match(subject) or "BREAKING CHANGE" in body:
+            return "major"
+        if FEATURE_RE.match(subject):
+            bump = "minor"
+    return bump
+
+
+def bump_version(base: list[int], bump: str) -> list[int]:
+    major, minor, patch = base
+    if bump == "major":
+        if major == 0:
+            minor += 1
+            patch = 0
+        else:
+            major += 1
+            minor = 0
+            patch = 0
+    elif bump == "minor":
+        minor += 1
+        patch = 0
+    else:
+        patch += 1
+    return [major, minor, patch]
+
+
+def next_build_for_base(tags: list[tuple[str, list[int]]], base: list[int]) -> int:
+    max_build = 0
+    for _, parts in tags:
+        if len(parts) != 4:
+            continue
+        if parts[:3] == base:
+            max_build = max(max_build, parts[3])
+    return max_build + 1
+
+
+def compute_next_version(repo: Path, channel: str, allow_empty: bool) -> list[int]:
+    tags = list_tags(repo)
+    stable_tag = latest_stable_tag(tags)
+    if stable_tag:
+        base_tag, base_version = stable_tag
+    else:
+        base_tag = None
+        base_version = read_version_file(repo / "VERSION")
+
+    commits = commits_since(repo, base_tag)
+    bump = classify_bump(commits)
+    if bump is None:
+        if not allow_empty:
+            raise RuntimeError("No commits found since last stable tag.")
+        bump = "patch"
+
+    next_base = bump_version(base_version, bump)
+    if channel != "stable":
+        build = next_build_for_base(tags, next_base)
+        return next_base + [build]
+    return next_base
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="Compute the next PakFu version from git history.",
+    )
+    parser.add_argument(
+        "--channel",
+        choices=["stable", "beta", "dev"],
+        default="stable",
+        help="Release channel. Beta/dev produce a numeric prerelease build.",
+    )
+    parser.add_argument(
+        "--write",
+        action="store_true",
+        help="Write the computed version to VERSION.",
+    )
+    parser.add_argument(
+        "--allow-empty",
+        action="store_true",
+        help="Allow version bumps even if no commits were found.",
+    )
+    args = parser.parse_args()
+
+    repo = Path(__file__).resolve().parent.parent
+    version_parts = compute_next_version(repo, args.channel, args.allow_empty)
+    version = format_version(version_parts)
+
+    if args.write:
+        (repo / "VERSION").write_text(version + "\n", encoding="utf-8")
+
+    print(version)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())