feat: Add GitHub releases and semantic versioning

- Set up dynamic version reading from package metadata
- Add python-semantic-release to dev dependencies
- Create release.yml workflow for automated GitHub releases
- Configure semantic versioning with conventional commits
- Update README with version-specific installation examples
- Build distribution packages (wheel and sdist)

Author: jreakin

.github/workflows/release.yml

@@ -0,0 +1,57 @@
+name: Release
+
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: write
+  packages: write
+
+jobs:
+  release:
+    name: Create Release
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+          enable-cache: true
+          cache-dependency-glob: "pyproject.toml"
+          ignore-nothing-to-cache: true
+
+      - name: Set up Python
+        run: uv python install 3.9
+
+      - name: Install dependencies
+        run: uv sync --group dev
+
+      - name: Run tests
+        run: uv run pytest tests/ -v --tb=short
+
+      - name: Run semantic-release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: uv run semantic-release publish --ci
+
+      - name: Build distribution packages
+        run: uv run pip install build && python -m build
+
+      - name: Upload artifacts to release
+        if: github.ref == 'refs/heads/main'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          # Get the latest tag
+          LATEST_TAG=$(git describe --tags --abbrev=0 || echo "")
+          
+          if [ -n "$LATEST_TAG" ]; then
+            # Upload wheel and sdist to the release
+            gh release upload "$LATEST_TAG" dist/*.whl dist/*.tar.gz --clobber
+          fi
+

README.md

@@ -10,16 +10,38 @@ A Python address parser built for Ryan Data that uses `usaddress` to parse US ad
 
 ## Installation
 
+Install the latest development version:
+
 ```bash
-pip install git+https://github.com/Abstract-Data/RyanData-Address-Utils.git
+uv add git+https://github.com/Abstract-Data/RyanData-Address-Utils.git
+```
+
+Install a specific version (recommended for production):
+
+```bash
+# Install a specific release version
+uv add git+https://github.com/Abstract-Data/RyanData-Address-Utils.git@v0.2.0
+
+# Install latest from main branch
+uv add git+https://github.com/Abstract-Data/RyanData-Address-Utils.git@main
 ```
 
 With pandas support:
 
 ```bash
-pip install "ryandata-address-utils[pandas] @ git+https://github.com/Abstract-Data/RyanData-Address-Utils.git"
+uv add "git+https://github.com/Abstract-Data/RyanData-Address-Utils.git[pandas]"
+```
+
+For specific version with pandas:
+
+```bash
+uv add "git+https://github.com/Abstract-Data/RyanData-Address-Utils.git@v0.2.0[pandas]"
 ```
 
+### Available Releases
+
+See [GitHub Releases](https://github.com/Abstract-Data/RyanData-Address-Utils/releases) for all available versions and changelog.
+
 ## Quick Start
 
 ```python
@@ -197,6 +219,28 @@ make test
 make lint
 ```
 
+## Versioning
+
+This project follows [Semantic Versioning](https://semver.org/). Version bumps are automated based on [Conventional Commits](https://www.conventionalcommits.org/):
+
+- `feat:` commits trigger a minor version bump
+- `fix:` commits trigger a patch version bump
+- `BREAKING CHANGE:` in commit footer triggers a major version bump
+- `chore:`, `docs:`, `refactor:` commits don't trigger version bumps
+
+### Release Process
+
+1. Commits following conventional commits are pushed to `main`
+2. GitHub Actions automatically:
+   - Detects version bump requirements
+   - Updates version in `pyproject.toml`
+   - Creates git tag (e.g., `v0.2.1`)
+   - Builds distribution packages (wheel + sdist)
+   - Creates GitHub release with changelog
+   - Uploads artifacts
+
+See [GitHub Actions Releases](https://github.com/Abstract-Data/RyanData-Address-Utils/actions/workflows/release.yml) to view release automation.
+
 ## License
 
 MIT

pyproject.toml

@@ -47,6 +47,7 @@ dev = [
     "mypy>=1.13.0",
     "pytest>=8.0.0",
     "hypothesis>=6.0.0",
+    "python-semantic-release>=9.0.0",
 ]
 
 [build-system]
@@ -83,3 +84,8 @@ warn_return_any = true
 warn_unused_ignores = true
 disallow_untyped_defs = true
 ignore_missing_imports = true
+
+[tool.semantic_release]
+version_source = "tag"
+tag_format = "v{version}"
+build_command = "pip install build && python -m build"

src/ryandata_address_utils/__init__.py

@@ -40,8 +40,23 @@
 
 from __future__ import annotations
 
+import sys
 from typing import Optional
 
+# Dynamic version from package metadata
+if sys.version_info >= (3, 8):
+    from importlib.metadata import version, PackageNotFoundError
+else:
+    from importlib_metadata import version, PackageNotFoundError
+
+try:
+    __version__ = version("ryandata-address-utils")
+except PackageNotFoundError:
+    # Package is not installed in editable mode or not installed at all
+    __version__ = "0.2.0"
+
+__package_name__ = "ryandata-address-utils"
+
 # Imports grouped by type and sorted
 from ryandata_address_utils.data import (
     BaseDataSource,
@@ -82,9 +97,6 @@
     ZipCodeValidator,
 )
 
-__version__ = "0.2.0"
-__package_name__ = "ryandata-address-utils"
-
 __all__ = [
     # Version
     "__version__",