This is an automated email from the ASF dual-hosted git repository.
yaooqinn pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/gluten.git
The following commit(s) were added to refs/heads/main by this push:
new 5286b8cf1e [MINOR][DOC] Fix and expand build/test instructions in
AGENTS.md (#12121)
5286b8cf1e is described below
commit 5286b8cf1e015a300f9d15afc3bc1c5e8328134a
Author: Kent Yao <[email protected]>
AuthorDate: Thu May 21 21:37:30 2026 +0800
[MINOR][DOC] Fix and expand build/test instructions in AGENTS.md (#12121)
- Use `./build/mvn` wrapper consistently (not bare `mvn`)
- Fix ClickHouse build script path
- Add correct profile combinations for `gluten-ut` (`-Pspark-ut
-Pbackends-velox -Pspark-3.5 -Pscala-2.12`)
- Add Common Pitfalls section covering native bundle build, profile
mismatches, and format check
- Trim verbose tables; link to docs/get-started/{Velox,ClickHouse}.md for
details
Generated-by: Claude Opus 4.7
---
AGENTS.md | 96 +++++++++++++++++++++++++++++++++++++++++----------------------
1 file changed, 63 insertions(+), 33 deletions(-)
diff --git a/AGENTS.md b/AGENTS.md
index a6556c9410..8d71c4acad 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,5 +1,9 @@
# Agent Guidelines for Apache Gluten
+Entry point for AI coding agents and new contributors. Detailed build, test
+and contribution docs are linked below — this file only captures the rules
+that are easy to get wrong.
+
## Developer Documentation
- [New to Gluten](docs/developers/NewToGluten.md)
@@ -10,23 +14,33 @@
## Build Order (Important)
-The Java/Scala build depends on native shared libraries produced by the C++
build.
-Always build the native backend before running Maven. Modifying `gluten-core`
without
-rebuilding the native backend produces a build that compiles but fails at
runtime.
+The Java/Scala build depends on native shared libraries produced by the C++
+build. Always build the native backend before running Maven. Modifying
+`gluten-core` without rebuilding the native backend produces a build that
+compiles but fails at runtime.
-```bash
-# Velox backend — build native first, then Maven
-./dev/builddeps-veloxbe.sh
-mvn package -Pbackends-velox -DskipTests
+Always invoke Maven through the `./build/mvn` wrapper — it pins the Maven
+version and JVM flags Gluten expects.
-# ClickHouse backend — build native first, then Maven
-./dev/builddeps-clickhousebe.sh
-mvn package -Pbackends-clickhouse -DskipTests
+```bash
+# Velox backend — one-shot native + bundled jar build.
+# PROMPT_ALWAYS_RESPOND=y auto-confirms vcpkg / system-package prompts.
+export PROMPT_ALWAYS_RESPOND=y
+./dev/buildbundle-veloxbe.sh --enable_vcpkg=ON \
+ --enable_s3=OFF --enable_gcs=OFF --enable_hdfs=OFF --enable_abfs=OFF
+
+# ClickHouse backend — build native first, then Maven.
+bash ./ep/build-clickhouse/src/build-clickhouse.sh
+./build/mvn clean package -Pbackends-clickhouse -Pspark-3.3 -DskipTests
```
+For incremental builds, cloud-FS flags, the Spark/Scala/JDK matrix,
table-format
+and shuffle profiles, see
[docs/get-started/Velox.md](docs/get-started/Velox.md)
+and [docs/get-started/ClickHouse.md](docs/get-started/ClickHouse.md).
+
## Before Committing
-Before committing any changes, you MUST run the following checks and fix any
issues.
+You MUST run the following checks and fix any issues before committing.
### Java/Scala
@@ -37,7 +51,7 @@ Before committing any changes, you MUST run the following
checks and fix any iss
### C/C++ (Velox backend)
```bash
-# requires clang-format-15
+# Requires clang-format-15 specifically — other versions reformat differently
and CI rejects the diff.
./dev/format-cpp-code.sh
```
@@ -50,10 +64,27 @@ Before committing any changes, you MUST run the following
checks and fix any iss
Do not commit code that fails CI checks.
+## Testing
+
+Add at least one unit test (under `gluten-ut/`) for any fix or feature not
+covered by existing Spark UTs.
+
+```bash
+# gluten-ut — must select backend, Spark and Scala profiles
+./build/mvn test -pl gluten-ut -Pspark-ut -Pbackends-velox -Pspark-3.5
-Pscala-2.12
+
+# Velox backend (build with native tests enabled)
+./dev/builddeps-veloxbe.sh --build_tests=ON
+
+# ClickHouse backend CI — re-trigger by posting on the PR page:
+# Run Gluten Clickhouse CI
+```
+
## PR Title Convention
-Use `[GLUTEN-<issue ID>]` when a GitHub issue exists ("if necessary" per
CONTRIBUTING.md —
-omit the issue tag entirely for minor changes with no associated issue).
+Use `[GLUTEN-<issue ID>]` when a GitHub issue exists ("if necessary" per
+CONTRIBUTING.md — omit the issue tag entirely for minor changes with no
+associated issue).
| Scope | Title format |
|---|---|
@@ -66,28 +97,27 @@ Examples from CONTRIBUTING.md:
- `[GLUTEN-1234][VL] Fix null handling in velox aggregation`
- `[MINOR][DOC] Update configuration docs`
-## Testing
-
-Add at least one unit test (under `gluten-ut/`) for any fix or feature not
covered by
-existing Spark UTs.
-
-```bash
-# Java/Scala unit tests
-mvn test -pl gluten-ut
-
-# Velox backend (build with tests enabled)
-./dev/builddeps-veloxbe.sh --build_tests=ON
-
-# ClickHouse backend CI — re-trigger by posting on the PR page:
-# Run Gluten Clickhouse CI
-```
-
## AI Tooling Disclosure
-The PR template requires answering: "Was this patch authored or co-authored
using
-generative AI tooling?"
+The PR template requires answering: "Was this patch authored or co-authored
+using generative AI tooling?"
-- If yes: `Generated-by: <tool name and version>` (e.g. `Generated-by: Claude
claude-sonnet-4-6`)
+- If yes: `Generated-by: <tool name and version>` (e.g.
+ `Generated-by: Claude claude-sonnet-4-6`)
- If no: write `No`
See [ASF Generative Tooling
Guidance](https://www.apache.org/legal/generative-tooling.html).
+
+## Common Pitfalls
+
+- **Bare `mvn` instead of `./build/mvn`** — the wrapper pins versions and JVM
flags.
+- **Editing `gluten-core` / `gluten-substrait` and skipping the native
rebuild.**
+ Maven still succeeds, but JNI/Substrait mismatches blow up at runtime. Re-run
+ `./dev/builddeps-veloxbe.sh build_gluten_cpp` when in doubt.
+- **Wrong `clang-format` version.** Anything but 15.x reformats differently and
+ CI rejects the diff. Verify with `clang-format --version`.
+- **Spark 4.x with JDK 8.** Always pair `-Pspark-4.0`/`-Pspark-4.1` with
+ `-Pjava-17 -Pscala-2.13 -Dmaven.compiler.release=17`.
+- **Per-module tests before `./build/mvn install`.** `gluten-ut` and
+ `backends-velox` resolve sibling Gluten modules from the local Maven repo —
+ run `./build/mvn install ... -DskipTests` once after a clean checkout.
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
