feat: automate releases and derive versions from tags

.github/workflows/publish.yaml

@@ -1,24 +1,37 @@
 name: Publish
+
 on:
-  release:
-    branches:
-      - master
-    types:
-      - published
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+
 jobs:
   publish:
-    name: Publish
+    name: Build and publish
     runs-on: ubuntu-latest
     steps:
-      - name: Checkout
+      - name: Checkout tag
         uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
       - name: Setup Python
         uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
       - name: Install uv
         uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+      - name: Install dependencies
+        run: uv sync --all-extras --group dev
       - name: Build
-        run: uv build
-      - name: Publish
+        run: uv run python -m build
+      - name: Check distributions
+        run: uvx twine check dist/*
+      - name: Publish to PyPI
         env:
-          UV_PUBLISH_TOKEN: ${{ secrets.pypi_token }}
+          UV_PUBLISH_TOKEN: ${{ secrets.PYPI_TOKEN || secrets.pypi_token }}
         run: uv publish

.github/workflows/release.yaml

@@ -0,0 +1,34 @@
+name: Release
+
+on:
+  push:
+    branches: [main, master]
+
+permissions:
+  contents: write
+  issues: write
+  pull-requests: write
+
+jobs:
+  release:
+    name: Create release tag
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "lts/*"
+      - name: Run semantic-release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          npx --yes \
+            -p semantic-release@25.0.3 \
+            -p @semantic-release/commit-analyzer@13.0.1 \
+            -p @semantic-release/release-notes-generator@14.1.1 \
+            -p @semantic-release/github@12.0.8 \
+            semantic-release

.github/workflows/tests.yaml

@@ -1,13 +1,41 @@
 name: Tests
+
 on:
   push:
-    branches:
-      - "master"
+    branches: [main, master]
   pull_request:
+
+permissions:
+  contents: read
+  pull-requests: read
+
 jobs:
+  conventional-pr-title:
+    name: Conventional PR title
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Validate title
+        uses: amannn/action-semantic-pull-request@v5
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          types: |
+            build
+            chore
+            ci
+            docs
+            feat
+            fix
+            perf
+            refactor
+            revert
+            style
+            test
+
   lint:
     name: Lint
-    runs-on: "ubuntu-latest"
+    runs-on: ubuntu-latest
     steps:
       - name: Checkout
         uses: actions/checkout@v4
@@ -17,11 +45,16 @@ jobs:
           python-version: "3.10"
       - name: Install uv
         uses: astral-sh/setup-uv@v6
-      - name: Run Lint
-        run: uv tool run ruff check
+        with:
+          enable-cache: true
+      - name: Install dependencies
+        run: uv sync --all-extras --group dev
+      - name: Run lint
+        run: uv run ruff check wbdata tests
+
   types:
     name: Types
-    runs-on: "ubuntu-latest"
+    runs-on: ubuntu-latest
     steps:
       - name: Checkout
         uses: actions/checkout@v4
@@ -31,30 +64,38 @@ jobs:
           python-version: "3.10"
       - name: Install uv
         uses: astral-sh/setup-uv@v6
-      - name: Install Dependencies
-        run: uv sync --all-extras
-      - name: Check Types
+        with:
+          enable-cache: true
+      - name: Install dependencies
+        run: uv sync --all-extras --group dev
+      - name: Check types
         run: uv tool run ty check
+
   test:
     name: Tests
     runs-on: ${{ matrix.os }}
     strategy:
+      fail-fast: false
       matrix:
         python-version: ["3.10", "3.11", "3.12", "3.13"]
-        os: ["ubuntu-latest", "macos-latest", "windows-latest"]
+        os: [ubuntu-latest, macos-latest, windows-latest]
     defaults:
       run:
         shell: bash
     steps:
       - name: Checkout
         uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
       - name: Setup Python
         uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
       - name: Install uv
         uses: astral-sh/setup-uv@v6
-      - name: Install Dependencies
-        run: uv sync --all-extras
-      - name: Run Tests
+        with:
+          enable-cache: true
+      - name: Install dependencies
+        run: uv sync --all-extras --group dev
+      - name: Run tests
         run: uv run pytest

.releaserc.json

@@ -0,0 +1,9 @@
+{
+  "branches": ["main", "master"],
+  "tagFormat": "v${version}",
+  "plugins": [
+    "@semantic-release/commit-analyzer",
+    "@semantic-release/release-notes-generator",
+    "@semantic-release/github"
+  ]
+}

AGENTS.md

@@ -1,10 +1,10 @@
 # Repository Guidelines
 
 ## Project Structure & Module Organization
-Source lives in `wbdata/` with clients, caching helpers, and API utilities; `wbdata/version.py` centralizes the library version and should be the single source when updating releases. Tests reside in `tests/` with `test_*.py` modules mirroring public APIs. Contributor-facing docs and MkDocs content sit in `docs/`, while packaging metadata and tooling configuration are in `pyproject.toml`.
+Source lives in `wbdata/` with clients, caching helpers, and API utilities; package versions are derived from Git tags by `setuptools-scm`. Tests reside in `tests/` with `test_*.py` modules mirroring public APIs. Contributor-facing docs and MkDocs content sit in `docs/`, while packaging metadata and tooling configuration are in `pyproject.toml`.
 
 ## Build, Test, and Development Commands
-Install dependencies with `uv sync --all-extras --group dev` so the docs, pandas extras, and developer tooling are available. Use `uv run pytest` for the default suite and coverage, matching the `--cov=wbdata` addopts in configuration. Run `uv run ruff check wbdata tests` to lint, and `uv run mypy wbdata` for type validation. During documentation work, serve the site locally via `uv run mkdocs serve`.
+Install dependencies with `uv sync --all-extras --group dev` so the docs, pandas extras, and developer tooling are available. Use `uv run pytest` for the default suite and coverage, matching the `--cov=wbdata` addopts in configuration. Run `uv run ruff check wbdata tests` to lint, and `uv tool run ty check` for type validation. During documentation work, serve the site locally via `uv run mkdocs serve`.
 
 ## Coding Style & Naming Conventions
 Follow standard Python formatting with four-space indentation and readable, snake_case symbols. Public APIs exposed in `wbdata/__init__.py` should maintain descriptive, lowercase names; classes stay in CapWords. Ruff enforces PEP 8, import sorting, and selected Bugbear/Simplify rules—run it before committing. Keep modules typed, updating `py.typed` coverage when adding packages, and prefer explicit re-exports in `__all__` blocks where applicable.
@@ -16,4 +16,4 @@ Write new tests under `tests/` using `pytest` conventions (`test_feature.py`, fu
 Aim for concise, imperative subjects, optionally prefixed with Conventional Commit types as seen in `git log` (e.g., `fix: improve caching`). Reference related issues or discussions with `(#123)` in the subject when merging via GitHub. Before opening a PR, ensure lint, typing, and tests pass, document user-facing changes, and provide a short summary plus reproduction or screenshots when behavior shifts.
 
 ## Documentation & Release Notes
-Update `docs/` pages when modifying user workflows, and verify the navigation using the MkDocs preview. Release metadata lives in `wbdata/version.py`; bump it in sync with changelog entries and confirm that packaging files (`pyproject.toml`, `MANIFEST.in`) need no extra updates.
+Update `docs/` pages when modifying user workflows, and verify the navigation using the MkDocs preview. Releases are created from Conventional Commits and Git tags; confirm that packaging files (`pyproject.toml`, `MANIFEST.in`) need no extra updates.

CONTRIBUTING.md

@@ -0,0 +1,40 @@
+# Contributing
+
+## Pull request titles
+
+Pull request titles must use Conventional Commits syntax, because squash merges use
+the PR title as the commit message that drives automated releases.
+
+Examples:
+
+- `feat: add a new data helper` -> minor release
+- `fix: correct cache expiry` -> patch release
+- `feat!: remove a deprecated API` -> major release
+- `fix: handle missing values` with a `BREAKING CHANGE:` footer -> major release
+
+Prefer squash merges so the merged commit on `main`/`master` keeps the validated
+PR title.
+
+## Releases and versions
+
+Versions come from git tags, not committed version files. Merged Conventional
+Commits are analyzed on pushes to `main`/`master`; when a release is needed,
+semantic-release creates a `vX.Y.Z` tag and GitHub release without committing a
+version bump back to the branch.
+
+Package builds use `setuptools-scm`, so a build from `vX.Y.Z` produces version
+`X.Y.Z`. Local development builds between tags receive setuptools-scm dev
+versions.
+
+Publishing to PyPI happens only from release tags. The tag workflow builds with
+uv and publishes with `uv publish`.
+
+## Local checks
+
+```bash
+uv sync --all-extras --group dev
+uv run pytest
+uv tool run ty check
+uv run python -m build
+uvx twine check dist/*
+```

MANIFEST.in

@@ -1,4 +1,3 @@
-include *.txt
-include *.rst
-recursive-include docs *.rst
+include LICENSE.txt README.md CONTRIBUTORS.md CONTRIBUTING.md mkdocs.yml
+recursive-include docs *.md
 recursive-include tests *.py

README.md

@@ -13,3 +13,5 @@ API](http://data.worldbank.org/developers/api-overview), and also adds some
 convenience functionality for searching and retrieving information.
 
 Documentation is available at <http://wbdata.readthedocs.org/> .
+
+Contributing and release conventions are described in [CONTRIBUTING.md](CONTRIBUTING.md).

mkdocs.yml

@@ -8,7 +8,7 @@ plugins:
           options:
             show_source: false
             members_order: source
-            docstrings_options:
+            docstring_options:
               returns_named_value: false
               returns_multiple_items: false
 watch:

pyproject.toml

@@ -1,10 +1,10 @@
 
 [project]
 name = "wbdata"
-version = "1.1.0"
+dynamic = ["version"]
 description = "A library to access World Bank data"
 readme = "README.md"
-license = {text = "GPL-2.0+"}
+license = "GPL-2.0-or-later"
 requires-python = ">=3.10,<4"
 authors = [
     {name = "Oliver Sherouse", email = "oliver@oliversherouse.com"},
@@ -41,7 +41,9 @@ Documentation = "https://wbdata.readthedocs.io/"
 
 [dependency-groups]
 dev = [
+    "build>=1.2.2,<2",
     "pytest>=7.4.4,<8",
+    "ruff>=0.8.0",
     "pytest-cov>=4.1.0,<5",
     "types-cachetools>=5.3.0.7,<6",
     "types-tabulate>=0.9.0.20240106,<0.10",
@@ -52,8 +54,18 @@ dev = [
 ]
 
 [build-system]
-requires = ["hatchling"]
-build-backend = "hatchling.build"
+requires = ["setuptools>=64", "setuptools-scm>=8"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+include = ["wbdata*"]
+
+[tool.setuptools.package-data]
+wbdata = ["py.typed"]
+
+[tool.setuptools_scm]
+fallback_version = "0+unknown"
+local_scheme = "no-local-version"
 
 [tool.ruff.lint]
 select = [

tests/test_version.py

@@ -0,0 +1,7 @@
+from importlib.metadata import version
+
+import wbdata
+
+
+def test_package_version_matches_distribution_metadata() -> None:
+    assert wbdata.__version__ == version("wbdata")