You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@sedona.apache.org by "jbampton (via GitHub)" <gi...@apache.org> on 2026/06/23 01:47:24 UTC
[PR] [DOCS] Expand info on Makefile, uv, prek and code quality [sedona]
jbampton opened a new pull request, #3081:
URL: https://github.com/apache/sedona/pull/3081
## Did you read the Contributor Guide?
- Yes, I have read the [Contributor Rules](https://sedona.apache.org/latest/community/rule/) and [Contributor Development Guide](https://sedona.apache.org/latest/community/develop/)
## Is this PR related to a ticket?
- No:
- this is a documentation update. The PR name follows the format `[DOCS] my subject`
## What changes were proposed in this PR?
Add more info on how our systems work for docs and code quality.
Let us help people use the tools correctly on their local machines.
## How was this patch tested?
## Did this PR include necessary documentation updates?
- No, this PR does not affect any public API so no need to change the documentation.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@sedona.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [DOCS] Expand info on Makefile, uv, prek and code quality [sedona]
Posted by "jiayuasu (via GitHub)" <gi...@apache.org>.
jiayuasu commented on PR #3081:
URL: https://github.com/apache/sedona/pull/3081#issuecomment-4889639953
@jbampton can you double check the review above?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@sedona.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [DOCS] Expand info on Makefile, uv, prek and code quality [sedona]
Posted by "Copilot (via GitHub)" <gi...@apache.org>.
Copilot commented on code in PR #3081:
URL: https://github.com/apache/sedona/pull/3081#discussion_r3475901629
##########
docs/setup/compile.md:
##########
@@ -159,42 +159,86 @@ uv run mike deploy --update-aliases latest-snapshot -b website -p
uv run mike serve -b website
```
-## Code Quality Checks with `prek`, `uv`, and `make`
-
-This guide explains how Apache Sedona manages local code quality checks, formatting, and linting. 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, unified `Makefile`.
+### Compiling via Makefile (Recommended)
----
-
-### Prerequisites
+For a streamlined developer experience, a unified `Makefile` is provided to handle local documentation builds automatically.
-Before running any checks, ensure you have `uv` installed on your machine. If you don't have it yet, you can install it via the official installer:
+To build and serve the documentation locally using the automated environment pipeline, run:
```bash
-curl -LsSf https://astral.sh/uv/install.sh | sh
+make docsbuild
```
-> 💡 **Note:** 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`.
+**What this command does behind the scenes:**
+
+1. **Environment Verification:** Validates that `uv` is available on your local path.
+2. **Dependency Syncing:** Runs `uv sync --all-groups` to automatically set up or synchronize an isolated virtual environment (`.venv`) containing MkDocs and compilation dependencies.
+3. **Asset Generation:** Navigates into the `docs-overrides` directory to fetch, build, and bundle required JavaScript and CSS assets via Node/NPM and Gulp workflows.
+4. **MkDocs Compilation:** Compiles the Markdown files in the `docs` directory into a fully optimized, static HTML website based on the configuration inside `mkdocs.yml`.
---
-### The Core Workflow: `uv` + `prek`
+## Code Quality Checks with `prek`, `uv`, and `make`
-Our codebase uses `prek` to orchestrate linting and formatting workflows (such as *Black*, *markdownlint*, or *oxipng*).
+This guide explains how Apache Sedona manages local code quality checks, formatting, and linting. 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, unified `Makefile`.
-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.
+### Prerequisites
----
+Make sure your machine has `uv` and Python 3.8+ installed before running checks.
-### Available Make Commands
+### Core Workflow via Makefile
-For maximum convenience, you should interact with `prek` entirely through the following `make` shortcuts:
+The `Makefile` handles environment isolation and dependency resolution automatically using `uv`. For maximum convenience, you should interact with `prek` entirely through the following make shortcuts:
* **`make check-stage`** *Runs checks on staged changes only (Recommended before committing).* Evaluates `prek` only against the files you have explicitly staged using `git add`. It is incredibly fast.
* **`make check`** *Runs checks on the full codebase.* Forces `prek` to evaluate every single file in the repository, regardless of git status. **Use this before opening a Pull Request.**
-* **`make check-from-ref`** *Runs checks on your entire branch history.* Automatically identifies all files changed since you branched off of the `main` branch and runs linting rules against them.
+* **`make check-from-ref`** *Runs checks on your entire branch history.* Automatically identifies all files changed since you branched off of the `master` branch and runs linting rules against them.
* **`make check-last`** *Runs checks on your last commit.* If you just committed code and want to double-check that everything passes post-commit.
* **`make update-deps`** *Keeps linter hooks up to date.* Upgrades `prek` hooks to their latest respective upstream versions and updates your local locked dependencies.
+### Running prek Standalone (Without Makefile)
+
+For developers on execution environments where running a `Makefile` is unavailable, restrictive, or unoptimized (such as native Windows environments without an active bash/make emulation layer), you can execute code quality workflows by interacting with `prek` directly using `uv`.
+
+#### 1. Bootstrap the Environment
+
+Before invoking `prek` manually, force `uv` to resolve and install the mandatory development groups and local hook ecosystems:
+
+```bash
+uv sync --all-groups
+```
+
+#### 2. Executing Standalone Hooks
+
+Once dependencies are synced inside your virtual environment, execute `prek` tasks via `uv run`:
+
+* **Check Staged Files Only:**
+
+```bash
+uv run prek run
+```
+
+* **Check the Entire Codebase:**
+
+```bash
+uv run prek run --all-files
+```
+
+* **Run Specific Linters Standalone:**
+ If you only wish to validate explicit targets (such as Python formatting, markdown linter rules, or security auditing profiles), pass the specific hook ID directly:
+
+```bash
+uv run prek run <hook_id> --all-files
+```
+
+#### 3. Updating Hooks Manually
+
+To keep linter definitions synchronized with upstream styling configurations without a `Makefile` shortcut, trigger an explicit update through the core engine:
+
+```bash
+uv run prek autoupdate
Review Comment:
The command here uses `prek autoupdate`, but the repo’s Makefile (and existing workflow) use `prek auto-update`. Using the wrong subcommand will fail for contributors following these steps.
##########
docs/setup/compile.md:
##########
@@ -159,42 +159,86 @@ uv run mike deploy --update-aliases latest-snapshot -b website -p
uv run mike serve -b website
```
-## Code Quality Checks with `prek`, `uv`, and `make`
-
-This guide explains how Apache Sedona manages local code quality checks, formatting, and linting. 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, unified `Makefile`.
+### Compiling via Makefile (Recommended)
----
-
-### Prerequisites
+For a streamlined developer experience, a unified `Makefile` is provided to handle local documentation builds automatically.
-Before running any checks, ensure you have `uv` installed on your machine. If you don't have it yet, you can install it via the official installer:
+To build and serve the documentation locally using the automated environment pipeline, run:
```bash
-curl -LsSf https://astral.sh/uv/install.sh | sh
+make docsbuild
```
-> 💡 **Note:** 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`.
+**What this command does behind the scenes:**
+
+1. **Environment Verification:** Validates that `uv` is available on your local path.
+2. **Dependency Syncing:** Runs `uv sync --all-groups` to automatically set up or synchronize an isolated virtual environment (`.venv`) containing MkDocs and compilation dependencies.
Review Comment:
`make docsbuild` doesn’t run `uv sync --all-groups`; it runs `make docsinstall` which calls `uv sync --group docs` (see Makefile). The current text can mislead contributors into syncing unnecessary dev groups when they just want docs dependencies.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@sedona.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [DOCS] Expand info on Makefile, uv, prek and code quality [sedona]
Posted by "jiayuasu (via GitHub)" <gi...@apache.org>.
jiayuasu merged PR #3081:
URL: https://github.com/apache/sedona/pull/3081
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@sedona.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org