ci: simplify branching, harden release, update PyPI publishing flow

.github/workflows/ci.yml

@@ -0,0 +1,148 @@
+name: CI
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+concurrency:
+  group: pr-${{ github.head_ref || github.sha }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    name: Lint (ruff)
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+
+      - name: Install Poetry
+        run: pipx install poetry
+
+      - name: Configure Poetry
+        run: poetry config virtualenvs.in-project true
+
+      - name: Cache virtualenv
+        uses: actions/cache@v4
+        with:
+          path: .venv
+          key: venv-lint-${{ runner.os }}-3.10-${{ hashFiles('poetry.lock') }}
+
+      - name: Install dependencies
+        run: poetry install --with dev
+
+      - name: Run ruff check
+        run: poetry run ruff check .
+
+      - name: Run ruff format check
+        run: poetry run ruff format --check .
+
+  typecheck:
+    name: Type check (pyright)
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+
+      - name: Install Poetry
+        run: pipx install poetry
+
+      - name: Configure Poetry
+        run: poetry config virtualenvs.in-project true
+
+      - name: Cache virtualenv
+        uses: actions/cache@v4
+        with:
+          path: .venv
+          key: venv-typecheck-${{ runner.os }}-3.10-${{ hashFiles('poetry.lock') }}
+
+      - name: Install dependencies
+        run: poetry install --with dev
+
+      - name: Run pyright
+        run: poetry run pyright
+
+  build:
+    name: Build package
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+
+      - name: Install Poetry
+        run: pipx install poetry
+
+      - name: Configure Poetry
+        run: poetry config virtualenvs.in-project true
+
+      - name: Cache virtualenv
+        uses: actions/cache@v4
+        with:
+          path: .venv
+          key: venv-build-${{ runner.os }}-3.10-${{ hashFiles('poetry.lock') }}
+
+      - name: Install dependencies
+        run: poetry install --only main
+
+      - name: Build package
+        run: poetry build
+
+      - name: Check package
+        run: |
+          python -m pip install --upgrade twine
+          twine check dist/*
+
+  tests:
+    name: Tests (Python ${{ matrix.python-version }}, ${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install Poetry
+        run: pipx install poetry
+
+      - name: Configure Poetry
+        run: poetry config virtualenvs.in-project true
+
+      - name: Cache virtualenv
+        uses: actions/cache@v4
+        with:
+          path: .venv
+          key: venv-tests-${{ runner.os }}-${{ matrix.python-version }}-${{ hashFiles('poetry.lock') }}
+
+      - name: Install dependencies
+        run: poetry install
+
+      - name: Run unit tests
+        run: poetry run pytest tests/ -v

.github/workflows/docs.yml

@@ -0,0 +1,74 @@
+name: Docs
+
+on:
+  workflow_dispatch:
+  pull_request:
+    # Only run on PRs that touch docs-related files to keep checks fast.
+    paths:
+      - "docs/**"
+      - "README.md"
+      - "pyproject.toml"
+      - "deeptab/**"
+  push:
+    # No paths filter here: tag pushes must always build docs regardless of
+    # which files changed in the tagged commit. Paths filters in GitHub Actions
+    # apply to both branches and tags under the same push: block, so a tag
+    # like v1.7.0 would be silently skipped if docs files weren't in that commit.
+    branches:
+      - main
+    tags:
+      - "v*"
+
+concurrency:
+  group: docs-${{ github.head_ref || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build-docs:
+    name: Build docs (Sphinx)
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install system dependencies
+        run: sudo apt-get update && sudo apt-get install -y pandoc
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+
+      - name: Install Poetry
+        run: pipx install poetry
+
+      - name: Configure Poetry
+        run: poetry config virtualenvs.in-project true
+
+      - name: Cache virtualenv
+        uses: actions/cache@v4
+        with:
+          path: .venv
+          key: venv-docs-${{ runner.os }}-3.10-${{ hashFiles('poetry.lock') }}
+
+      - name: Install package and docs dependencies
+        run: poetry install --with docs
+
+      - name: Build Sphinx docs
+        run: poetry run sphinx-build -b html docs/ docs/_build/html -W --keep-going
+
+      # ── Triggered on push to main ──────────────────────────────────────────
+      # RTD listens to its own webhook and publishes "latest" automatically.
+      # The step below is informational; actual publishing is done by RTD.
+      - name: Notify latest/dev docs will be published
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        run: echo "Docs build succeeded. RTD will publish the 'latest' version."
+
+      # ── Triggered on a release tag ─────────────────────────────────────────
+      # RTD listens to tag pushes and publishes a versioned snapshot automatically
+      # when "Build tags" is enabled in the RTD project settings.
+      - name: Notify stable/versioned docs will be published
+        if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
+        run: |
+          TAG="${GITHUB_REF_NAME}"
+          echo "Docs build succeeded for tag ${TAG}. RTD will publish the '${TAG}' versioned docs."

.github/workflows/publish-pypi.yml

@@ -0,0 +1,83 @@
+name: Publish to PyPI
+
+# Triggered when a maintainer pushes a stable release tag (e.g. v1.7.0).
+# RC tags (v1.7.0rc1) are handled by publish-testpypi.yml instead.
+#
+# Requires the "pypi-publish" GitHub Environment with tag-based protection.
+# Uses OIDC trusted publishing — no PYPI_TOKEN secret required.
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi-publish
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+
+      - name: Install Poetry
+        run: pipx install poetry
+
+      - name: Configure Poetry
+        run: poetry config virtualenvs.in-project true
+
+      - name: Cache virtualenv
+        uses: actions/cache@v4
+        with:
+          path: .venv
+          key: venv-publish-${{ runner.os }}-3.10-${{ hashFiles('poetry.lock') }}
+
+      - name: Install dependencies
+        run: poetry install --only main
+
+      - name: Check tag matches pyproject version
+        run: |
+          VERSION=$(python3 -c "import tomllib; d=tomllib.load(open('pyproject.toml','rb')); print(d['tool']['poetry']['version'])")
+          TAG="${GITHUB_REF_NAME#v}"
+
+          echo "pyproject version: $VERSION"
+          echo "git tag version:   $TAG"
+
+          if [ "$VERSION" != "$TAG" ]; then
+            echo "❌ Tag version and pyproject.toml version do not match."
+            exit 1
+          fi
+
+      - name: Build package
+        run: poetry build
+
+      - name: Check package
+        run: |
+          python -m pip install --upgrade twine
+          twine check dist/*
+
+      - name: Test wheel install
+        run: |
+          python -m venv /tmp/deeptab-wheel-test
+          source /tmp/deeptab-wheel-test/bin/activate
+          pip install dist/*.whl
+          python -c "import deeptab; print(deeptab.__version__)"
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          prerelease: false
+          generate_release_notes: true
+          files: dist/*