feat: consolidate version source of truth and add release tooling

- Make pyproject.toml the single source of truth for version
- Use importlib.metadata in __init__.py to read version at runtime
- Add scripts/bump_version.py (stdlib-only) for version bumping
- Add Makefile targets: version, bump-patch, bump-minor, bump-major, release
- Add RELEASE.md documenting the full release process
- Update README.md with new Makefile targets and link to RELEASE.md
- Replace hardcoded version assertion in tests with dynamic check
- Remove stale [tool.hatch.build.targets.wheel] from pyproject.toml
- Bump version to 0.3.1

Author: smorin

Makefile

@@ -1,4 +1,4 @@
-.PHONY: test lint format typecheck coverage build clean help completions-bash completions-zsh completions-fish
+.PHONY: test lint format typecheck coverage build clean help completions-bash completions-zsh completions-fish version bump-patch bump-minor bump-major release
 
 help: ## Show this help message
 	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-15s\033[0m %s\n", $$1, $$2}'
@@ -28,6 +28,30 @@ clean: ## Remove build artifacts
 	find . -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true
 	find . -type f -name '*.pyc' -delete 2>/dev/null || true
 
+version: ## Show current version
+	@uv run python -c "from importlib.metadata import version; print(version('worktreeflow'))"
+
+bump-patch: ## Bump patch version (e.g. 0.3.0 → 0.3.1)
+	@uv run python scripts/bump_version.py patch
+
+bump-minor: ## Bump minor version (e.g. 0.3.0 → 0.4.0)
+	@uv run python scripts/bump_version.py minor
+
+bump-major: ## Bump major version (e.g. 0.3.0 → 1.0.0)
+	@uv run python scripts/bump_version.py major
+
+release: ## Bump, sync, commit, tag (usage: make release BUMP=patch)
+	@BUMP=$${BUMP:-patch}; \
+	$(MAKE) bump-$$BUMP; \
+	uv sync; \
+	VERSION=$$(uv run python -c "from importlib.metadata import version; print(version('worktreeflow'))"); \
+	git add pyproject.toml; \
+	git commit -m "chore: bump version to $$VERSION"; \
+	git tag "v$$VERSION"; \
+	echo ""; \
+	echo "Created tag v$$VERSION."; \
+	echo "Run 'git push && git push --tags' to publish."
+
 completions-bash: ## Generate bash completions
 	_WTF_COMPLETE=bash_source uv run wtf
 

README.md

@@ -163,6 +163,11 @@ make typecheck   # Run ty type checking
 make coverage    # Run tests with coverage (35% threshold)
 make build       # Build the package
 make clean       # Remove build artifacts
+make version     # Show current version
+make bump-patch  # Bump patch version (0.3.0 → 0.3.1)
+make bump-minor  # Bump minor version (0.3.0 → 0.4.0)
+make bump-major  # Bump major version (0.3.0 → 1.0.0)
+make release     # Bump, commit, tag (usage: make release BUMP=minor)
 ```
 
 ### Shell Completions
@@ -182,27 +187,17 @@ _WTF_COMPLETE=fish_source wtf | source
 
 Or generate completion scripts via `make completions-bash`, `make completions-zsh`, or `make completions-fish`.
 
-### Building and Publishing
+### Versioning and Releasing
 
-1. **Build the package**:
-   ```bash
-   uv build
-   ```
-   This creates `dist/worktreeflow-0.1.0-py3-none-any.whl` and `dist/worktreeflow-0.1.0.tar.gz`
-
-2. **Test locally**:
-   ```bash
-   uv pip install dist/worktreeflow-0.1.0-py3-none-any.whl
-   wtf --help
-   ```
+Version bumping, tagging, and publishing are documented in **[RELEASE.md](RELEASE.md)**.
 
-3. **Publish to PyPI**:
-   ```bash
-   # First time: Get API token from https://pypi.org/manage/account/token/
-   # Then set it in your environment or use --token flag
+Quick reference:
 
-   uv publish
-   ```
+```bash
+make version       # Show current version
+make bump-patch    # Bump patch version
+make release       # Bump, commit, and tag (then push manually)
+```
 
 ### Dual Functionality
 

RELEASE.md

@@ -0,0 +1,93 @@
+# Release Process
+
+## Versioning
+
+worktreeflow follows [Semantic Versioning](https://semver.org/) (`MAJOR.MINOR.PATCH`).
+
+The **single source of truth** for the version is `pyproject.toml`. The Python package reads the version at runtime via `importlib.metadata`, so there is only one place to update.
+
+## Bump Version
+
+Use the Makefile targets to bump the version:
+
+```bash
+# Show current version
+make version
+
+# Bump patch (0.3.0 → 0.3.1) — bug fixes
+make bump-patch
+
+# Bump minor (0.3.0 → 0.4.0) — new features, backwards compatible
+make bump-minor
+
+# Bump major (0.3.0 → 1.0.0) — breaking changes
+make bump-major
+```
+
+After bumping, run `uv sync` to refresh the editable install so `wtf version` reflects the new version.
+
+## Full Release
+
+The `make release` target automates: bump → sync → commit → tag.
+
+```bash
+# Patch release (default)
+make release
+
+# Minor release
+make release BUMP=minor
+
+# Major release
+make release BUMP=major
+```
+
+This will:
+1. Bump the version in `pyproject.toml`
+2. Run `uv sync` to update the local install
+3. Commit the version change
+4. Create a git tag (e.g., `v0.4.0`)
+
+It does **not** push automatically. Review the commit and tag, then:
+
+```bash
+git push && git push --tags
+```
+
+## Publishing to PyPI
+
+### Automated (Recommended)
+
+Publishing is handled by GitHub Actions. The workflow (`.github/workflows/publish.yml`) triggers when a **GitHub Release** is published:
+
+1. Push the version bump and tag (see above)
+2. Go to [GitHub Releases](https://github.com/smorinlabs/worktreeflow/releases)
+3. Click **Draft a new release**
+4. Select the tag you just pushed (e.g., `v0.4.0`)
+5. Add release notes
+6. Click **Publish release**
+
+The CI will automatically:
+- Run the test suite
+- Build the package with `uv build`
+- Publish to PyPI via OIDC (trusted publisher)
+
+### Manual
+
+If you need to publish manually:
+
+```bash
+uv build
+uv publish  # requires PyPI API token
+```
+
+## Pre-Release Checklist
+
+- [ ] All tests pass (`make test`)
+- [ ] Linting passes (`make lint`)
+- [ ] Type checking passes (`make typecheck`)
+- [ ] Version bumped (`make bump-patch` / `bump-minor` / `bump-major`)
+- [ ] `uv sync` run after bump
+- [ ] `wtf version` shows correct version
+- [ ] Changes committed and tagged (`make release`)
+- [ ] Pushed to remote (`git push && git push --tags`)
+- [ ] GitHub Release created

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "worktreeflow"
-version = "0.3.0"
+version = "0.3.1"
 description = "Git workflow manager for feature branches using worktrees, shows you cli equivalent commands"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -78,6 +78,3 @@ exclude_lines = [
     "if __name__ == .__main__.",
     "if TYPE_CHECKING:",
 ]
-
-[tool.hatch.build.targets.wheel]
-packages = ["src/worktreeflow"]

scripts/bump_version.py

@@ -0,0 +1,45 @@
+#!/usr/bin/env python3
+"""Bump the version in pyproject.toml. Usage: python scripts/bump_version.py [patch|minor|major]"""
+
+import re
+import sys
+from pathlib import Path
+
+PYPROJECT = Path(__file__).resolve().parent.parent / "pyproject.toml"
+VERSION_RE = re.compile(r'(version\s*=\s*")(\d+)\.(\d+)\.(\d+)(")')
+
+
+def bump(part: str) -> None:
+    text = PYPROJECT.read_text()
+    m = VERSION_RE.search(text)
+    if not m:
+        print("ERROR: Could not find version in pyproject.toml", file=sys.stderr)
+        sys.exit(1)
+
+    major, minor, patch = int(m.group(2)), int(m.group(3)), int(m.group(4))
+    old = f"{major}.{minor}.{patch}"
+
+    if part == "patch":
+        patch += 1
+    elif part == "minor":
+        minor += 1
+        patch = 0
+    elif part == "major":
+        major += 1
+        minor = 0
+        patch = 0
+    else:
+        print(f"ERROR: Unknown bump part '{part}'. Use patch, minor, or major.", file=sys.stderr)
+        sys.exit(1)
+
+    new = f"{major}.{minor}.{patch}"
+    text = VERSION_RE.sub(rf"\g<1>{new}\5", text, count=1)
+    PYPROJECT.write_text(text)
+    print(f"{old} -> {new}")
+
+
+if __name__ == "__main__":
+    if len(sys.argv) != 2:
+        print("Usage: python scripts/bump_version.py [patch|minor|major]", file=sys.stderr)
+        sys.exit(1)
+    bump(sys.argv[1])

src/worktreeflow/__init__.py

@@ -2,7 +2,13 @@
 worktreeflow - Git workflow manager for feature branches using worktrees
 """
 
-__version__ = "0.3.0"
+try:
+    from importlib.metadata import version as _metadata_version
+
+    __version__ = _metadata_version("worktreeflow")
+except Exception:
+    __version__ = "0.0.0+unknown"
+
 __author__ = "Steve Morin"
 __license__ = "MIT"
 

tests/test_new_features.py

@@ -40,11 +40,19 @@ def _make_manager(dry_run=False, config=None, json_output=False):
 
 class TestVersionCommand:
     def test_version_output(self):
+        from importlib.metadata import version as _meta_version
+
         runner = CliRunner()
         result = runner.invoke(cli, ["version"])
         assert result.exit_code == 0
         assert "worktreeflow" in result.output
-        assert "0.3.0" in result.output
+        assert _meta_version("worktreeflow") in result.output
+
+    def test_version_is_not_unknown(self):
+        from worktreeflow import __version__
+
+        assert __version__ != "0.0.0+unknown"
+        assert "." in __version__
 
     def test_version_in_help(self):
         runner = CliRunner()