DeepLabCut · deruyter92 · Jan 29, 2026 · Jan 29, 2026 · Jan 30, 2026 · Jan 30, 2026
diff --git a/.circleci/config.yml b/.circleci/config.yml
@@ -1,24 +1,73 @@
 version: 2.1
 
 orbs:
-  python: circleci/python@0.2.1
+  python: circleci/python@4.0.0
 
 jobs:
   build-and-test:
-    working_directory: ~/circleci-demo-python-django
-    docker:
-      - image: circleci/python:3.10  # primary container for the build job
-        auth:
-          username: mydockerhub-user
-          password: $DOCKERHUB_PASSWORD  # context / project UI env-var reference
+    executor:
+      name: python/default
+      tag: '3.10' # or '3.12'
+    environment:
+      # HuggingFace: disable xet and use cache directory
+      # NOTE @deruyter92 2026-05-07: "xet" opens many simultaneous connections
+      # to different data chunks. Currently doesn't work well with CircleCI.
+      # See: https://github.com/huggingface/xet-core/issues/800
+      HF_HUB_DISABLE_XET: 1
+      HF_HOME: ~/.cache/huggingface
+
     steps:
       - checkout
-      - python/load-cache
-      - python/install-deps
-      - python/save-cache
+
+      # Restore uv cache
+      - restore_cache:
+          name: Restore uv cache
+          keys:
+            - v2-uv-pip-{{ checksum "pyproject.toml" }}
+            - v2-uv-pip-
+
+      # Restore HuggingFace weights cache
+      - restore_cache:
+          name: Restore Hugging Face cache
+          keys:
+            - hf-weights-v1-{{ checksum "pyproject.toml" }}
+            - hf-weights-v1-
+
+      # Install uv
+      - run:
+          name: Install uv
+          command: |
+            pip install uv
+
+      # Install DeepLabCut runtime deps only
+      - run:
+          name: Install DeepLabCut runtime deps only
+          command: |
+            uv pip install --system -e .
+
+      # (Optional) Trim the cache for CI so uploads stay small and fast
+      - run:
+          name: Prune uv cache for CI
+          command: uv cache prune --ci || true
+
+      # Save the uv cache for next runs
+      - save_cache:
+          name: Save uv cache
+          key: v2-uv-pip-{{ checksum "pyproject.toml" }}
+          paths:
+            - ~/.cache/uv
+
+      # Test DLC
       - run:
-          command: python testscript_cli.py
           name: TestDLC
+          command: python testscript_cli.py
+
+      # Save the HF weights cache for next runs
+      - save_cache:
+          name: Save huggingface cache
+          key: hf-weights-v1-{{ checksum "pyproject.toml" }}
+          paths:
+            - ~/.cache/huggingface
 
 workflows:
   main:

diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml
@@ -25,7 +25,7 @@ body:
     attributes:
       label: DeepLabCut version
       description: What version of DLC are you using? Please check with `import deeplabcut`, `deeplabcut.__version__`
-      placeholder: 3.0.0rc9
+      placeholder: 3.0.0
     validations:
       required: true
   - type: dropdown

diff --git a/.github/workflows/build-book.yml b/.github/workflows/build-book.yml
@@ -0,0 +1,51 @@
+name: Build (and optionally deploy) Jupyter Book
+
+on:
+  workflow_call:
+    inputs:
+      python-version:
+        description: "Python version used to build the docs."
+        required: false
+        default: "3.10"
+        type: string
+      build_dir:
+        required: false
+        default: "./_build/html"
+        type: string
+      upload_artifact:
+        description: "If true, upload the built site as an artifact."
+        required: false
+        default: false
+        type: boolean
+
+
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ inputs.python-version }}
+
+      - name: Install docs dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install .[docs]
+
+      - name: Build the book
+        run: jupyter-book build .
+
+      - name: Upload built site artifact
+        if: ${{ inputs.upload_artifact }}
+        uses: actions/upload-artifact@v6
+        with:
+          name: built-book
+          path: ${{ inputs.build_dir }}
+          if-no-files-found: error
+          retention-days: 1
diff --git a/.github/workflows/codespell.yml b/.github/workflows/codespell.yml
@@ -5,7 +5,8 @@ on:
   push:
     branches: [main]
   pull_request:
-    branches: [main]
+    types: [opened, synchronize, reopened]
+    branches: [ main ]
 
 jobs:
   codespell:
@@ -14,7 +15,7 @@ jobs:
 
     steps:
       - name: Checkout
-        uses: actions/checkout@v3
+        uses: actions/checkout@v6
       - name: Annotate locations with typos
         uses: codespell-project/codespell-problem-matcher@v1
       - name: Codespell

diff --git a/.github/workflows/docs_and_notebooks_checks.yml b/.github/workflows/docs_and_notebooks_checks.yml
@@ -0,0 +1,59 @@
+name: Docs & notebooks freshness and formatting checks
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  staleness:
+    name: Docs and notebooks scan (read-only)
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+
+    steps:
+      - name: Checkout repository (full history for git dates)
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Install staleness tool dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install "pydantic>=2,<3" pyyaml "nbformat>=5"
+
+      - name: Run staleness report (read-only)
+        run: |
+          python tools/docs_and_notebooks_check.py \
+          --config tools/docs_and_notebooks_report_config.yml \
+          --out-dir tmp/docs_nb_checks \
+          report
+
+
+      # Optional: run check mode (will fail only once you populate allowlists in config)
+      - name: Run staleness policy check (optional gate)
+        continue-on-error: true
+        run: |
+          python tools/docs_and_notebooks_check.py \
+          --config tools/docs_and_notebooks_report_config.yml \
+          --out-dir tmp/docs_nb_checks \
+          --no-step-summary \
+          check
+
+      - name: Upload staleness artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: staleness-report
+          path: |
+            tmp/docs_nb_checks/*.json
+            tmp/docs_nb_checks/*.md
+          if-no-files-found: error
diff --git a/.github/workflows/format.yml b/.github/workflows/format.yml
@@ -0,0 +1,119 @@
+name: pre-commit (PR only on changed files)
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+permissions:
+  contents: read
+
+jobs:
+  detect_changes:
+    runs-on: ubuntu-latest
+    outputs:
+      changed: ${{ steps.changed_files.outputs.changed }}
+      changed_python: ${{ steps.changed_python.outputs.changed_python }}
+
+    steps:
+      - name: Checkout full history
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Detect changed files
+        id: changed_files
+        run: |
+          git fetch origin ${{ github.base_ref }}
+          CHANGED_FILES=$(git diff --name-only origin/${{ github.base_ref }}...HEAD)
+
+          {
+            echo "changed<<EOF"
+            echo "$CHANGED_FILES"
+            echo "EOF"
+          } >> "$GITHUB_OUTPUT"
+
+      - name: Detect changed Python files
+        id: changed_python
+        run: |
+          git fetch origin ${{ github.base_ref }}
+          CHANGED_PYTHON=$(git diff --name-only origin/${{ github.base_ref }}...HEAD | grep -E '\.(py|pyi|ipynb)$' || true)
+
+          {
+            echo "changed_python<<EOF"
+            echo "$CHANGED_PYTHON"
+            echo "EOF"
+          } >> "$GITHUB_OUTPUT"
+
+      - name: Show changed files
+        run: |
+          echo "Changed files:"
+          echo "${{ steps.changed_files.outputs.changed }}"
+
+          echo
+          echo "Changed Python files:"
+          echo "${{ steps.changed_python.outputs.changed_python }}"
+
+  precommit:
+    needs: detect_changes
+    runs-on: ubuntu-latest
+    if: ${{ needs.detect_changes.outputs.changed != '' }}
+
+    steps:
+      - name: Checkout PR branch
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Install tooling
+        run: pip install pre-commit ruff
+
+      - name: Run pre-commit (CI check-only stage) on changed files
+        id: precommit_run
+        continue-on-error: true
+        env:
+          CHANGED_FILES: ${{ needs.detect_changes.outputs.changed }}
+        run: |
+          mapfile -t files <<< "$CHANGED_FILES"
+          pre-commit run --hook-stage manual --files "${files[@]}" --show-diff-on-failure
+
+      - name: Generate Ruff Markdown report
+        id: ruff_report
+        if: ${{ always() && needs.detect_changes.outputs.changed_python != '' }}
+        env:
+          CHANGED_PYTHON: ${{ needs.detect_changes.outputs.changed_python }}
+        run: |
+          mkdir -p tmp
+          mapfile -t pyfiles <<< "$CHANGED_PYTHON"
+          python tools/ruff_report.py "${pyfiles[@]}" --output tmp/ruff-report.md
+
+      - name: Add short Ruff report to GitHub Actions summary
+        if: ${{ always() && steps.precommit_run.outcome == 'failure' && needs.detect_changes.outputs.changed_python != '' }}
+        run: |
+          {
+            echo "# Lint summary"
+            echo
+            echo "## Ruff report (top section)"
+            echo
+            sed -n '1,80p' tmp/ruff-report.md
+            echo
+            echo "_Full report uploaded as workflow artifact: `ruff-report`_"
+          } >> "$GITHUB_STEP_SUMMARY"
+
+      - name: Upload Ruff report artifact
+        if: ${{ always() && needs.detect_changes.outputs.changed_python != '' }}
+        uses: actions/upload-artifact@v6
+        with:
+          name: ruff-report
+          path: tmp/ruff-report.md
+
+      - name: Fail job if pre-commit failed
+        if: ${{ steps.precommit_run.outcome == 'failure' }}
+        run: |
+          echo "pre-commit reported failures"
+          exit 1