You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@sedona.apache.org by ji...@apache.org on 2026/05/20 04:50:31 UTC
(sedona) branch master updated: [GH-2503] Switch to `prek` using `uv` (#2542)
This is an automated email from the ASF dual-hosted git repository.
jiayuasu pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/sedona.git
The following commit(s) were added to refs/heads/master by this push:
new 29184f89fc [GH-2503] Switch to `prek` using `uv` (#2542)
29184f89fc is described below
commit 29184f89fc440c9bc1bc95c3c6fced330c9fe52c
Author: John Bampton <jb...@users.noreply.github.com>
AuthorDate: Wed May 20 14:50:25 2026 +1000
[GH-2503] Switch to `prek` using `uv` (#2542)
---
.github/workflows/pre-commit-manual.yml | 22 ++++--
.github/workflows/pre-commit-reusable.yml | 57 --------------
.github/workflows/pre-commit.yml | 15 +++-
Makefile | 62 ++++++++-------
checkmake.ini | 2 +-
docs/setup/compile.md | 126 +++++++++++++++++++++++-------
pyproject.toml | 3 +
7 files changed, 162 insertions(+), 125 deletions(-)
diff --git a/.github/workflows/pre-commit-manual.yml b/.github/workflows/pre-commit-manual.yml
index a7b63ab54d..bc09f08734 100644
--- a/.github/workflows/pre-commit-manual.yml
+++ b/.github/workflows/pre-commit-manual.yml
@@ -15,7 +15,8 @@
# specific language governing permissions and limitations
# under the License.
-name: pre-commit-manual
+# https://github.com/j178/prek
+name: Manual hooks
on:
push:
@@ -33,9 +34,16 @@ concurrency:
cancel-in-progress: ${{ github.ref != 'refs/heads/master' }}
jobs:
- run:
- name: Run manual hooks
- uses: ./.github/workflows/pre-commit-reusable.yml
- with:
- job_id: 'manual'
- extra_args: '--hook-stage manual'
+ pre-commit:
+ name: Run pre-commit
+ runs-on: ubuntu-latest
+ steps:
+ - name: 'Checkout ${{ github.ref }} ( ${{ github.sha }} )'
+ uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+ with:
+ persist-credentials: false
+ - uses: j178/prek-action@6ad80277337ad479fe43bd70701c3f7f8aa74db3 # v2.0.3
+ with:
+ install-only: true
+ - name: Run manual pre-commit hooks
+ run: prek run --color=always --all-files --hook-stage manual
diff --git a/.github/workflows/pre-commit-reusable.yml b/.github/workflows/pre-commit-reusable.yml
deleted file mode 100644
index c66f40ee04..0000000000
--- a/.github/workflows/pre-commit-reusable.yml
+++ /dev/null
@@ -1,57 +0,0 @@
-# Licensed to the Apache Software Foundation (ASF) under one
-# or more contributor license agreements. See the NOTICE file
-# distributed with this work for additional information
-# regarding copyright ownership. The ASF licenses this file
-# to you under the Apache License, Version 2.0 (the
-# "License"); you may not use this file except in compliance
-# with the License. You may obtain a copy of the License at
-#
-# http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing,
-# software distributed under the License is distributed on an
-# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-# KIND, either express or implied. See the License for the
-# specific language governing permissions and limitations
-# under the License.
-
-name: _pre-commit-base
-
-on:
- workflow_call:
- inputs:
- extra_args:
- required: false
- type: string
- default: ''
- job_id:
- required: true
- type: string
-
-permissions:
- contents: read
-
-jobs:
- run-hooks:
- runs-on: ubuntu-latest
- steps:
- - name: 'Checkout ${{ github.ref }} ( ${{ github.sha }} )'
- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
- with:
- persist-credentials: false
- - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
- with:
- python-version: '3.11'
- architecture: 'x64'
- - name: Install dependencies
- run: |
- python -m pip install --upgrade pip
- pip install pre-commit
- - name: set PY
- run: echo "PY=$(python -VV | sha256sum | cut -d' ' -f1)" >> "$GITHUB_ENV"
- - uses: actions/cache@cdf6c1fa76f9f475f3d7449005a359c84ca0f306 # v5.0.3
- with:
- path: ~/.cache/pre-commit
- key: pre-commit|${{ inputs.job_id }}|${{ env.PY }}|${{ hashFiles('.pre-commit-config.yaml') }}
- - name: Run pre-commit
- run: pre-commit run --color=always --all-files --show-diff-on-failure ${{ inputs.extra_args }} # zizmor: ignore[template-injection]
diff --git a/.github/workflows/pre-commit.yml b/.github/workflows/pre-commit.yml
index 2bf524f421..1223d9a6f3 100644
--- a/.github/workflows/pre-commit.yml
+++ b/.github/workflows/pre-commit.yml
@@ -15,6 +15,7 @@
# specific language governing permissions and limitations
# under the License.
+# https://github.com/j178/prek
name: pre-commit
on:
@@ -34,7 +35,13 @@ concurrency:
jobs:
pre-commit:
- name: Run pre-commit standard
- uses: ./.github/workflows/pre-commit-reusable.yml
- with:
- job_id: 'standard'
+ name: Run pre-commit
+ runs-on: ubuntu-latest
+ steps:
+ - name: 'Checkout ${{ github.ref }} ( ${{ github.sha }} )'
+ uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+ with:
+ persist-credentials: false
+ - uses: j178/prek-action@6ad80277337ad479fe43bd70701c3f7f8aa74db3 # v2.0.3
+ with:
+ extra-args: --all-files
diff --git a/Makefile b/Makefile
index 216c0af42c..d29200b8c4 100644
--- a/Makefile
+++ b/Makefile
@@ -15,36 +15,28 @@
# specific language governing permissions and limitations
# under the License.
-PYTHON := $(shell command -v python || command -v python3 || echo python)
-PIP := $(PYTHON) -m pip
+.PHONY: check check-from-ref check-install check-last check-stage clean docsbuild docsinstall install run-docs sync-no-dev update update-deps
-.PHONY: check checkinstall checkupdate install docsinstall docsbuild clean run-docs
+check: install ## run all pre-commit checks
+ prek run --all-files
-check:
- @echo "Running pre-commit checks..."
- @if ! command -v pre-commit >/dev/null 2>&1; then \
- echo "Error: pre-commit is not installed. Run 'make checkinstall' first."; \
- exit 1; \
- fi
- pre-commit run --all-files
+check-from-ref: install ## will run prek checks for all changes since you branched off
+ prek run --from-ref main
-checkinstall:
- @echo "Installing pre-commit..."
- @if ! command -v pre-commit >/dev/null 2>&1; then \
- $(PIP) install pre-commit; \
- fi
- pre-commit install
+check-install: ## checks for a uv installation
+ @command -v uv >/dev/null 2>&1 || (echo 'uv not found, install via: curl -LsSf https://astral.sh/uv/install.sh | sh' && exit 1)
-checkupdate: checkinstall
- @echo "Updating pre-commit hooks..."
- pre-commit autoupdate
+check-last: install ## will run pre-commit checks on last commit only
+ prek --last-commit
-install: checkinstall
+check-stage: install ## runs check on currently staged changes
+ prek
-docsinstall:
- @echo "Installing documentation dependencies..."
- @command -v uv >/dev/null 2>&1 || (echo 'uv not found, install via: curl -LsSf https://astral.sh/uv/install.sh | sh' && exit 1)
- uv sync --group docs
+clean:
+ @echo "Cleaning up generated files... (TODO)"
+ rm -rf __pycache__
+ rm -rf .mypy_cache
+ rm -rf .pytest_cache
docsbuild: docsinstall
@echo "Building documentation..."
@@ -52,12 +44,24 @@ docsbuild: docsinstall
uv run mike deploy --update-aliases latest-snapshot -b website -p
uv run mike serve
-clean:
- @echo "Cleaning up generated files... (TODO)"
- rm -rf __pycache__
- rm -rf .mypy_cache
- rm -rf .pytest_cache
+docsinstall: check-install
+ @echo "Installing documentation dependencies..."
+ uv sync --group docs
+
+install: check-install ## Sync all dependencies (including development) using uv
+ uv sync --all-groups
run-docs:
docker build -f docker/docs/Dockerfile -t mkdocs-sedona .
docker run --rm -it -p 8000:8000 -v ${PWD}:/docs mkdocs-sedona
+
+sync-no-dev: check-install ## Sync non-development dependencies using uv
+ uv sync --no-dev
+
+update: install
+ prek auto-update
+
+update-deps: check-install ## Update pre-commit hooks and dependency locks
+ prek auto-update || :
+ uv lock --upgrade
+ uv sync --all-groups
diff --git a/checkmake.ini b/checkmake.ini
index 69fb487d50..ae342f75a0 100644
--- a/checkmake.ini
+++ b/checkmake.ini
@@ -19,4 +19,4 @@
maxBodyLength = 10
[minphony]
-required = check,checkinstall,checkupdate,install,docsinstall,docsbuild,clean,run-docs
+required = check,check-from-ref,check-install,check-last,check-stage,clean,docsbuild,docsinstall,install,run-docs,sync-no-dev,update,update-deps
diff --git a/docs/setup/compile.md b/docs/setup/compile.md
index 955b6100bd..5fd8dfc6d4 100644
--- a/docs/setup/compile.md
+++ b/docs/setup/compile.md
@@ -158,45 +158,117 @@ uv run mike deploy --update-aliases latest-snapshot -b website -p
uv run mike serve
```
-## pre-commit
+## Code Quality Checks with `prek`, `uv`, and `make`
-We run [pre-commit](https://pre-commit.com/) with GitHub Actions so installation on
-your local machine is currently optional.
+This guide explains how Apache Sedona manages code quality checks, formatting, and linting locally. To ensure a fast and consistent developer experience, we combine `uv` (a lightning-fast Python package and environment manager) with `prek` (our internal pre-commit wrapper framework) and expose everything via a simple `Makefile`.
-The pre-commit [configuration file](https://github.com/apache/sedona/blob/master/.pre-commit-config.yaml)
-is in the repository root. Before you can run the hooks, you need to have pre-commit installed.
+---
-The hooks run when running `git commit` and also from the command line with `pre-commit`. Some of the hooks will auto
-fix the code after the hooks fail whilst most will print error messages from the linters. If a hook fails the overall
-commit will fail, and you will need to fix the issues or problems and `git add` and git commit again. On git commit
-the hooks will run mostly only against modified files so if you want to test all hooks against all files and when you
-are adding a new hook you should always run:
+### Prerequisites
-`pre-commit run --all-files`
+Before running any checks, ensure you have `uv` installed on your machine. If you don't have it yet, you can install it via:
-Sometimes you might need to skip a hook to commit because the hook is stopping you from committing or your computer
-might not have all the installation requirements for all the hooks. The `SKIP` variable is comma separated for two or
-more hooks:
+`curl -LsSf https://astral.sh/uv/install.sh | sh`
-`SKIP=codespell git commit -m "foo"`
+You do not need to manually install Python virtual environments, `pre-commit`, or `prek`. The `Makefile` handles environment isolation and dependency resolution automatically using `uv`.
-The same applies when running pre-commit:
+---
-`SKIP=codespell pre-commit run --all-files`
+### The Core Workflow: `uv` + `prek`
-Occasionally you can have more serious problems when using `pre-commit` with `git commit`. You can use `--no-verify` to
-commit and stop `pre-commit` from checking the hooks. For example:
+Our codebase uses `prek` to orchestrate linting and formatting workflows (such as Black, markdownlint, or oxipng).
-`git commit --no-verify -m "foo"`
+Instead of forcing you to activate a virtual environment manually, the `Makefile` uses `uv sync` to build a perfectly isolated environment behind the scenes. When you run any `make check-*` command, it guarantees that `prek` is executed using the exact dependency versions locked in the project.
-If you just want to run one hook for example just run the `markdownlint` hook:
+---
-`pre-commit run markdownlint --all-files`
+### Available Make Commands
-We have a [Makefile](https://github.com/apache/sedona/blob/master/Makefile) in the repository root which has three pre-commit convenience commands.
+For maximum convenience, you should interact with `prek` entirely through the following `make` shortcuts.
-For example, you can run the following to setup pre-commit to run before each commit
+#### 1. Run Checks on Staged Changes (Recommended before committing)
-```
-make checkinstall
-```
+This runs `prek` only against the files you have explicitly staged using `git add`. It is incredibly fast.
+
+`make check-stage`
+
+#### 2. Run Checks on the Full Codebase
+
+This forces `prek` to evaluate every single file in the repository, regardless of git status. Use this before opening a Pull Request.
+
+`make check`
+
+#### 3. Run Checks on Your Entire Branch History
+
+This automatically identifies all files changed since you branched off of the `main` branch and runs linting rules against them.
+
+`make check-from-ref`
+
+#### 4. Run Checks on Your Last Commit
+
+If you just committed code and want to double-check that everything passes post-commit:
+
+`make check-last`
+
+#### 5. Keeping Linter Hooks Up to Date
+
+To upgrade `prek` hooks to their latest respective upstream versions and update your local locked dependencies:
+
+`make update-deps`
+
+---
+
+### Advanced Usage & Examples
+
+#### Skipping Specific Hooks Locally
+
+Sometimes a specific linter rule or hook blocks your workflow, or you want to isolate your testing to a single hook. You can bypass specific hooks by passing the `SKIP` environment variable directly to `prek`.
+
+* Example: Run all checks except the linter named codespell
+`SKIP=codespell make check-stage`
+* Example: Skip multiple hooks simultaneously (comma-separated)
+`SKIP=codespell,gitleaks make check`
+
+#### Bypassing Automated Git Hooks (`--no-verify`)
+
+If you have configured `prek` to run automatically as a native Git `pre-commit` hook on your system, it will block `git commit` if any files fail the quality gates.
+
+If you need to commit a work-in-progress (WIP) branch quickly without fixing style errors, you can bypass the `prek` gate entirely using Git's built-in `--no-verify` (or `-n`) flag.
+
+* Example: Force a commit despite failing linter checks
+`git add .`
+`git commit -m "WIP: basic structure for new feature" --no-verify`
+
+Warning: Continuous Integration (CI) runners will still execute all `prek` gates on your Pull Request. Bypassing hooks with `--no-verify` should only be used for temporary local savepoints.
+
+---
+
+### Housekeeping & Resetting Cache (`make clean`)
+
+If your Python environment behaves unexpectedly, or if the linters fail to pick up recent changes due to aggressive local caching, you should reset your workspace back to a pristine state.
+
+Run the following command:
+
+`make clean`
+
+#### What happens under the hood?
+
+This command triggers a multi-directory sweep to remove compiled local artifacts and temporary caches:
+
+* `__pycache__`: Clears out compiled Python bytecode files (`.pyc`).
+* `.mypy_cache`: Empties the type-checking state cache to ensure a fresh, accurate type analysis next run.
+* `.pytest_cache`: Cleans up previous test failure tracking states.
+
+Following a `make clean`, running any subsequent `make check` command will completely rebuild the `uv` virtual environment mapping and rerun all `prek` checks completely fresh.
+
+---
+
+### Architecture Pipeline
+
+When you execute a command like `make check`, the automation engine follows these exact steps:
+
+1. `check-install`: Verifies `uv` is installed on your local path.
+2. `install`: Triggers `uv sync --all-groups`, which automatically creates/syncs a `.venv` folder containing `prek` and all development dependencies.
+3. `Execution`: Runs the target `prek` command within that guaranteed environment context.
+
+`[ Your CLI ] ---> [ make check ] ---> [ uv syncs environment ] ---> [ prek executes hooks ]`
diff --git a/pyproject.toml b/pyproject.toml
index 26cb5ce4f2..2cf714686d 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -61,3 +61,6 @@ docs = [
"sphinx_rtd_theme==3.0.2",
"sphinx-autobuild",
]
+dev = [
+ "prek>=0.4.0"
+]