Minor changes to version tracking between release and master

.github/workflows/master-push.yml

@@ -34,17 +34,26 @@ jobs:
       - name: 'Update release branch with current master'
         run: |
           git checkout -B release origin/release
+          # The release branch owns the version counter. master carries sentinel
+          # 0.0.0 and should not be changed by any scripts. Release branch reads
+          # the prior version (from release) and bumps it. `--strategy-option=ours`
+          # keeps the release branch's version files when they conflict with master.
+          # See docs/dev/releasing.md
           prior_version=$(cat package/version)
-          old_master="$(git merge-base origin/master origin/release)"
-          new_master="$(git rev-parse origin/master)"
-          # otherwise bump the prior_version
-          if git diff --exit-code ${old_master} ${new_master} -- package/version; then
-              git merge --no-edit origin/master
-              package/version.sh bump ${prior_version}
-          else
-              # if the version has changed on master, use it unmodified
-              git merge --no-edit --strategy-option=theirs origin/master
+
+          bump_level=patch  # default bump level, may be overwritten
+          new_commits="origin/release..origin/master"
+          if git log --format='%B' "${new_commits}" | grep -qiE '^[[:space:]]*Bump:[[:space:]]*major[[:space:]]*$'; then
+              bump_level=major
+          elif git log --format='%B' "${new_commits}" | grep -qiE '^[[:space:]]*Bump:[[:space:]]*minor[[:space:]]*$'; then
+              bump_level=minor
           fi
+          echo "Release bump level: ${bump_level}"
+
+          # `ours` resolves conflicts in favour of release; only the version
+          # files should ever conflict (release = master + version commits).
+          git merge --no-edit --strategy-option=ours origin/master
+          package/version.sh bump ${prior_version} ${bump_level}
           # substitute the version in all relevant files
           package/version.sh sub
           uv --directory kmir lock --no-upgrade

.github/workflows/update-dependencies.yml

@@ -28,7 +28,9 @@ jobs:
           UV_VERSION=$(curl -s https://raw.githubusercontent.com/pyproject-nix/uv2nix/$(cat deps/uv2nix)/pkgs/uv-bin/srcs.json | jq -r .version)
           [[ "$UV_VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]
           echo $UV_VERSION > deps/uv_release
-          git add deps/uv_release && git commit -m "Sync uv version: uv ${UV_VERSION}" || true
+          # keep the [tool.uv] required-version guard in kmir/pyproject.toml in lockstep
+          sed --in-place 's/^required-version = ".*"$/required-version = "'"${UV_VERSION}"'"/' kmir/pyproject.toml
+          git add deps/uv_release kmir/pyproject.toml && git commit -m "Sync uv version: uv ${UV_VERSION}" || true
           echo uv_version=$UV_VERSION >> "${GITHUB_OUTPUT}"
       - name: 'Install uv'
         uses: astral-sh/setup-uv@v6

README.md

@@ -9,7 +9,7 @@ For semantics details and specialized workflows, see [Further Reading](#further-
 ### Prerequisites
 
 - [Python](https://www.python.org/) `>= 3.10`
-- [`uv`](https://docs.astral.sh/uv/)
+- [`uv`](https://docs.astral.sh/uv/), pinned in [`deps/uv_release`](deps/uv_release); if yours differs, run `uv self update <version>`
 - [`pip`](https://pip.pypa.io/) `>= 20.0.2`
 - [`gcc`](https://gcc.gnu.org/) `>= 11.4.0`
 - [Rust](https://rustup.rs/) via `rustup`
@@ -152,6 +152,7 @@ RUSTC=deps/.stable-mir-json/debug.sh cargo build
 - [docs/semantics-of-mir.md](docs/semantics-of-mir.md)
 - [docs/example-mir-execution-flow.md](docs/example-mir-execution-flow.md)
 - [docs/dev/adding-intrinsics.md](docs/dev/adding-intrinsics.md)
+- [docs/dev/releasing.md](docs/dev/releasing.md)
 - [docs/feature-checklist.md](docs/feature-checklist.md)
 - [Stable-MIR-JSON repository](https://github.com/runtimeverification/stable-mir-json/)
 

docs/dev/releasing.md

@@ -0,0 +1,11 @@
+# Releasing
+
+- **`release` branch owns the version.** Every push to `master` auto-bumps the patch, tags it, and ships docker (`master-push.yml` -> `release.yml`).
+- **`master` version files are `0.0.0` placeholders.** Never hand-edit `package/version`, `kmir/pyproject.toml`, or `kmir/uv.lock`. They only ever hold `0.0.0`. So `kmir --version` is `0.0.0` on a local master build, and the real version in nix/docker builds.
+- **Want minor/major instead of patch?** Put a trailer on its own line in a commit (or the squash/PR description) that lands on master e.g.:
+
+  ```
+  Bump: minor
+  ```
+
+  `major` > `minor` > `patch`; anything else defaults to patch.

kmir/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "kmir"
-version = "0.3.181"
+version = "0.0.0"
 description = ""
 requires-python = ">=3.10"
 dependencies = [
@@ -47,6 +47,10 @@ dev = [
     "pyupgrade",
 ]
 
+[tool.uv]
+# Pinned uv version for local builds, kept in sync with deps/uv_release
+required-version = "0.9.22"
+
 [tool.hatch.metadata]
 allow-direct-references = true
 

kmir/src/kmir/__main__.py

@@ -15,6 +15,7 @@
 from pyk.proof.show import APRProofShow
 from pyk.proof.tui import APRProofViewer
 
+from . import __version__
 from .cargo import CargoProject
 from .kmir import KMIR, KMIRAPRNodePrinter
 from .linker import link
@@ -325,6 +326,7 @@ def kmir(args: Sequence[str]) -> None:
 
 def _arg_parser() -> ArgumentParser:
     parser = ArgumentParser(prog='kmir')
+    parser.add_argument('-V', '--version', action='version', version=f'kmir {__version__}')
 
     command_parser = parser.add_subparsers(dest='command', required=True)
     kcli_args = KCLIArgs()

package/test-package.sh

@@ -4,9 +4,7 @@ set -xueo pipefail
 
 which kmir
 kmir --help
-
-# there is no `kmir version` implemented yet
-# kmir version
+kmir --version
 
 # ( \
 #      cd kmir/src/tests/integration/data/crate-tests/single-bin/main-crate \

package/version

@@ -1 +1 @@
-0.4.0
+0.0.0

package/version.sh

@@ -7,24 +7,23 @@ fatal() { echo "[FATAL] $@" ; exit 1 ; }
 
 version_file="package/version"
 
+# Bump the given version by the requested level and write it to the version file.
+# Usage: version_bump <version> [major|minor|patch]  (defaults to patch)
+# The version counter lives on the `release` branch, so <version> is always the
+# prior released version -- see docs/dev/releasing.md
 version_bump() {
-    local version release_commit version_major version_minor version_patch new_version current_version current_version_major current_version_minor current_version_patch
+    local version level version_major version_minor version_patch new_version
     version="$1" ; shift
+    level="${1:-patch}"
     version_major="$(echo ${version} | cut --delimiter '.' --field 1)"
     version_minor="$(echo ${version} | cut --delimiter '.' --field 2)"
     version_patch="$(echo ${version} | cut --delimiter '.' --field 3)"
-    current_version="$(cat ${version_file})"
-    current_version_major="$(echo ${current_version} | cut --delimiter '.' --field 1)"
-    current_version_minor="$(echo ${current_version} | cut --delimiter '.' --field 2)"
-    current_version_patch="$(echo ${current_version} | cut --delimiter '.' --field 3)"
-    new_version="${version}"
-    if [[ "${version_major}" == "${current_version_major}" ]] && [[ "${version_minor}" == "${current_version_minor}" ]]; then
-        new_version="${version_major}.${version_minor}.$((version_patch + 1))"
-    fi
-    # If the file being commited increases the major or minor, then take that version as it is
-    if [[ "${version_major}" < "${current_version_major}" ]] || [[ "${version_minor}" < "${current_version_minor}" ]]; then
-        new_version="${current_version}"
-    fi
+    case "${level}" in
+        major) new_version="$((version_major + 1)).0.0"                              ;;
+        minor) new_version="${version_major}.$((version_minor + 1)).0"               ;;
+        patch) new_version="${version_major}.${version_minor}.$((version_patch + 1))" ;;
+        *)     fatal "Unknown bump level: ${level} (expected major, minor or patch)" ;;
+    esac
     echo "${new_version}" > "${version_file}"
     notif "Version: ${new_version}"
 }