DX: define developer environment with uv (#42)

Co-authored-by: GitHub <[email protected]>

.cspell.json

@@ -22,14 +22,13 @@
   "ignorePaths": [
     "**/.cspell.json",
     ".editorconfig",
+    ".envrc",
     ".gitignore",
-    ".gitpod.*",
     ".pre-commit-config.yaml",
     ".prettierignore",
     ".vscode/*",
     "codecov.yml",
-    "pyproject.toml",
-    "tox.ini"
+    "pyproject.toml"
   ],
   "language": "en-US",
   "words": ["ComPWA", "conda", "doctests", "pdgref", "PyPA", "pytest"],

.editorconfig

@@ -16,5 +16,5 @@ indent_size = 4
 [LICENSE]
 indent_size = unset
 
-[setup.cfg]
+[uv.lock]
 indent_size = 4

.envrc

@@ -1 +1,2 @@
-layout anaconda
+uv sync --all-extras --quiet
+source .venv/bin/activate

.github/workflows/cd.yml

@@ -9,9 +9,9 @@ on:
 jobs:
   milestone:
     if: startsWith(github.ref, 'refs/tags')
-    uses: ComPWA/actions/.github/workflows/close-milestone.yml@v1
+    uses: ComPWA/actions/.github/workflows/close-milestone.yml@v2
   package-name:
-    uses: ComPWA/actions/.github/workflows/get-pypi-name.yml@v1
+    uses: ComPWA/actions/.github/workflows/get-pypi-name.yml@v2
   pypi:
     environment:
       name: PyPI
@@ -22,11 +22,11 @@ jobs:
       - package-name
     permissions:
       id-token: write
-    runs-on: ubuntu-22.04
+    runs-on: ubuntu-24.04
     steps:
-      - uses: ComPWA/actions/build-pypi-distribution@v1
+      - uses: ComPWA/actions/build-pypi-distribution@v2
       - uses: pypa/gh-action-pypi-publish@release/v1
   push:
     if: startsWith(github.ref, 'refs/tags') && !github.event.release.prerelease
     secrets: inherit
-    uses: ComPWA/actions/.github/workflows/push-to-version-branches.yml@v1
+    uses: ComPWA/actions/.github/workflows/push-to-version-branches.yml@v2

.github/workflows/ci.yml

@@ -28,7 +28,7 @@ on:
 
 jobs:
   pytest:
-    uses: ComPWA/actions/.github/workflows/pytest.yml@v1
+    uses: ComPWA/actions/.github/workflows/pytest.yml@v2
     with:
       coverage-target: sphinx_hep_pdgref
       macos-python-version: "3.9"
@@ -37,4 +37,4 @@ jobs:
     if: inputs.specific-pip-packages == ''
     secrets:
       token: ${{ secrets.PAT }}
-    uses: ComPWA/actions/.github/workflows/pre-commit.yml@v1
+    uses: ComPWA/actions/.github/workflows/pre-commit.yml@v2

.github/workflows/clean-caches.yml

@@ -14,9 +14,9 @@ on:
 jobs:
   cleanup:
     name: Remove caches
-    runs-on: ubuntu-22.04
+    runs-on: ubuntu-24.04
     steps:
-      - uses: ComPWA/actions/clean-caches@v1
+      - uses: ComPWA/actions/clean-caches@v2
         with:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           ref: ${{ inputs.ref }}

.github/workflows/lock.yml

@@ -0,0 +1,21 @@
+name: Update
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: |-
+    ${{ github.ref != format('refs/heads/{0}', github.event.repository.default_branch) }}
+
+on:
+  pull_request:
+    branches:
+      - main
+      - epic/*
+    paths:
+      - .pre-commit-config.yaml
+  workflow_dispatch:
+
+jobs:
+  lock:
+    uses: ComPWA/actions/.github/workflows/lock.yml@v2
+    secrets:
+      token: ${{ secrets.PAT }}

.github/workflows/pr-linting.yml

@@ -11,4 +11,4 @@ on:
 
 jobs:
   lint-pr:
-    uses: ComPWA/actions/.github/workflows/pr-linting.yml@v1
+    uses: ComPWA/actions/.github/workflows/pr-linting.yml@v2

.github/workflows/release-drafter.yml

@@ -9,7 +9,7 @@ on:
 
 jobs:
   update_release_draft:
-    runs-on: ubuntu-22.04
+    runs-on: ubuntu-24.04
     steps:
       - uses: release-drafter/release-drafter@v6
         env:

.gitignore

@@ -30,7 +30,6 @@ version.py
 
 # Temporary files
 *.pyc
-*condaenv.*
 .coverage
 .coverage.*
 .ipynb_checkpoints/
@@ -44,6 +43,7 @@ prof/
 *venv/
 .tox/
 pyvenv*/
+uv.lock
 
 # Settings
 .idea/
@@ -59,5 +59,4 @@ pyvenv*/
 !.readthedocs.yml
 !.vscode/*.json
 !codecov.yml
-!environment.yml
 !pyrightconfig.json

.pre-commit-config.yaml

@@ -1,27 +1,32 @@
 ci:
-  autoupdate_commit_msg: "MAINT: autoupdate pre-commit hooks"
-  autoupdate_schedule: quarterly # already done by requirements-cron.yml
+  autoupdate_commit_msg: "MAINT: update lock files"
+  autoupdate_schedule: quarterly
   skip:
     - mypy
-    - prettier
     - pyright
-    - taplo
 
 repos:
   - repo: meta
     hooks:
       - id: check-hooks-apply
       - id: check-useless-excludes
 
+  - repo: https://github.com/ComPWA/policy
+    rev: 0.5.0
+    hooks:
+      - id: check-dev-files
+        args:
+          - --repo-name=sphinx-hep-pdgref
+
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.5.6
+    rev: v0.7.0
     hooks:
       - id: ruff
         args: [--fix]
       - id: ruff-format
 
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.6.0
+    rev: v5.0.0
     hooks:
       - id: check-ast
       - id: check-case-conflict
@@ -48,15 +53,15 @@ repos:
           )$
       - id: trailing-whitespace
 
-  - repo: https://github.com/pre-commit/mirrors-prettier
-    rev: v4.0.0-alpha.8
+  - repo: https://github.com/ComPWA/prettier-pre-commit
+    rev: v3.3.3
     hooks:
       - id: prettier
 
-  - repo: https://github.com/ComPWA/mirrors-taplo
-    rev: v0.8.1
+  - repo: https://github.com/ComPWA/taplo-pre-commit
+    rev: v0.9.3
     hooks:
-      - id: taplo
+      - id: taplo-format
 
   - repo: https://github.com/pappasam/toml-sort
     rev: v0.23.1
@@ -65,23 +70,13 @@ repos:
         args:
           - --in-place
 
-  - repo: https://github.com/ComPWA/policy
-    rev: 0.3.18
-    hooks:
-      - id: check-dev-files
-        args:
-          - --no-notebooks
-          - --no-prettierrc
-          - --repo-name=sphinx-hep-pdgref
-          - --repo-title=sphinx-hep-pdgref
-
   - repo: https://github.com/streetsidesoftware/cspell-cli
-    rev: v8.13.1
+    rev: v8.15.1
     hooks:
       - id: cspell
 
   - repo: https://github.com/editorconfig-checker/editorconfig-checker.python
-    rev: 2.7.3
+    rev: 3.0.3
     hooks:
       - id: editorconfig-checker
         name: editorconfig
@@ -100,7 +95,7 @@ repos:
         types:
           - python
 
-  - repo: https://github.com/ComPWA/mirrors-pyright
-    rev: v1.1.374
+  - repo: https://github.com/ComPWA/pyright-pre-commit
+    rev: v1.1.385
     hooks:
       - id: pyright

.python-version

@@ -0,0 +1 @@
+3.12

.vscode/extensions.json

@@ -6,6 +6,8 @@
     "editorconfig.editorconfig",
     "esbenp.prettier-vscode",
     "github.vscode-github-actions",
+    "github.vscode-pull-request-github",
+    "mhutchie.git-graph",
     "ms-python.mypy-type-checker",
     "ms-python.python",
     "ms-python.vscode-pylance",

.vscode/settings.json

@@ -29,11 +29,11 @@
   "[yaml]": {
     "editor.defaultFormatter": "esbenp.prettier-vscode"
   },
+  "cSpell.enabled": true,
   "coverage-gutters.coverageFileNames": ["coverage.xml"],
   "coverage-gutters.coverageReportFileName": "**/htmlcov/index.html",
   "coverage-gutters.showGutterCoverage": false,
   "coverage-gutters.showLineCoverage": true,
-  "cSpell.enabled": true,
   "diffEditor.experimental.showMoves": true,
   "editor.formatOnSave": true,
   "files.watcherExclude": {
@@ -55,7 +55,6 @@
   "notebook.formatOnSave.enabled": true,
   "python.analysis.autoImportCompletions": false,
   "python.analysis.inlayHints.pytestParameters": true,
-  "python.analysis.typeCheckingMode": "strict",
   "python.terminal.activateEnvironment": false,
   "python.testing.pytestArgs": ["--color=no", "--no-cov"],
   "python.testing.pytestEnabled": true,
@@ -67,9 +66,7 @@
   "ruff.organizeImports": true,
   "search.exclude": {
     "**/tests/**/__init__.py": true,
-    "*/.pydocstyle": true,
-    "src/*/*/__init__.py": true,
-    "src/*/__init__.py": true
+    "**/uv.lock": true
   },
   "telemetry.telemetryLevel": "off"
 }

CONTRIBUTING.md

@@ -1,6 +1,26 @@
 # How to contribute?
 
-[![Open in Visual Studio Code](https://img.shields.io/badge/vscode-open-blue?logo=visualstudiocode)](https://open.vscode.dev/ComPWA/sphinx-hep-pdgref)
-[![GitPod](https://img.shields.io/badge/gitpod-open-blue?logo=gitpod)](https://gitpod.io/#https://github.com/ComPWA/sphinx-hep-pdgref)
+[![Open in Visual Studio Code](https://img.shields.io/badge/vscode-open-blue?logo=visualstudiocode)](https://github.dev/ComPWA/sphinx-hep-pdgref)
 
-This package is part of the [ComPWA Organization](https://github.com/ComPWA). For more information about how to contribute to the packages, go to [compwa.github.io/develop](https://compwa.github.io/develop)!
+> [!TIP]
+> This package is part of the [ComPWA Organization](https://github.com/ComPWA). For more information about how to contribute to the packages, go to **[compwa.github.io/develop](https://compwa.github.io/develop)**!
+
+To contribute to the project, you need to install the package in a virtual environment. This can be done best with [`uv`](https://docs.astral.sh/uv) (see installation instructions [here](https://docs.astral.sh/uv/getting-started/installation)). For this, you first need to get the source code with [Git](https://git-scm.com):
+
+```shell
+git clone https://github.com/ComPWA/sphinx-hep-pdgref
+cd sphinx-hep-pdgref
+```
+
+Now it's simply a matter of creating and activating the [virtual environment](https://docs.astral.sh/uv/pip/environments) with [`uv sync`](https://docs.astral.sh/uv/reference/cli/#uv-sync). The dependencies for the project are 'pinned' in each commit through the [`uv.lock` file](https://docs.astral.sh/uv/concepts/projects/#project-lockfile).
+
+```shell
+uv sync
+source .venv/bin/activate
+```
+
+Formatting and linting checks are automatically performed when committing changes. This is done with [pre-commit](https://pre-commit.com). To install the hooks in your local repository, run [`pre-commit install`](https://pre-commit.com/#3-install-the-git-hook-scripts) **once**:
+
+```shell
+pre-commit install --install-hooks
+```

README.md

@@ -4,7 +4,6 @@
 [![Supported Python versions](https://img.shields.io/pypi/pyversions/sphinx-hep-pdgref)](https://pypi.org/project/sphinx-hep-pdgref)
 [![BSD 3-Clause license](https://img.shields.io/badge/License-BSD_3--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)
 [![Open in Visual Studio Code](https://img.shields.io/badge/vscode-open-blue?logo=visualstudiocode)](https://open.vscode.dev/ComPWA/sphinx-hep-pdgref)
-[![GitPod](https://img.shields.io/badge/gitpod-open-blue?logo=gitpod)](https://gitpod.io/#https://github.com/ComPWA/sphinx-hep-pdgref)
 [![Test coverage](https://codecov.io/gh/ComPWA/sphinx-hep-pdgref/branch/main/graph/badge.svg?token=SS8ZB8J11N)](https://codecov.io/gh/ComPWA/sphinx-hep-pdgref)
 [![Codacy Badge](https://app.codacy.com/project/badge/Grade/dbe042deb2914f6098eb98586d3983fe)](https://www.codacy.com/gh/ComPWA/sphinx-hep-pdgref)
 [![CI status](https://github.com/ComPWA/sphinx-hep-pdgref/workflows/CI-tests/badge.svg)](https://github.com/ComPWA/sphinx-hep-pdgref/actions?query=branch%3Amain+workflow%3ACI-tests)
@@ -13,6 +12,7 @@
 [![Spelling checked](https://img.shields.io/badge/cspell-checked-brightgreen.svg)](https://github.com/streetsidesoftware/cspell/tree/master/packages/cspell)
 [![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg?style=flat-square)](https://github.com/prettier/prettier)
 [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/charliermarsh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
 
 This package is a
 [Sphinx extension](https://www.sphinx-doc.org/en/master/usage/extensions/index.html)