This is an automated email from the ASF dual-hosted git repository.
philo-he 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 1e762d3a3a [MINOR][CI][DOC] Document the Delta Spark UT pipeline and
skip it for docs-only changes (#12745)
1e762d3a3a is described below
commit 1e762d3a3a4c3caee114e3db94bee84478b2b726
Author: Felipe Pessoto <[email protected]>
AuthorDate: Thu Aug 13 11:48:02 2026 -0700
[MINOR][CI][DOC] Document the Delta Spark UT pipeline and skip it for
docs-only changes (#12745)
---
.github/workflows/delta_spark_ut.yml | 3 +++
.github/workflows/util/delta-spark-ut/README.md | 28 ++++++++++++++++---------
docs/developers/velox-backend-CI.md | 28 ++++++++++++++++++++++++-
3 files changed, 48 insertions(+), 11 deletions(-)
diff --git a/.github/workflows/delta_spark_ut.yml
b/.github/workflows/delta_spark_ut.yml
index 2d9c4aa709..34f6baff0b 100644
--- a/.github/workflows/delta_spark_ut.yml
+++ b/.github/workflows/delta_spark_ut.yml
@@ -57,6 +57,9 @@ on:
- 'gluten-delta/**'
# Covers src-delta, src-delta33, src-delta40 and any future variant.
- 'backends-velox/src-delta*/**'
+ # Negated patterns are evaluated in order and override the positives
+ # above, so this must stay last.
+ - '!.github/workflows/util/delta-spark-ut/**/*.md'
workflow_dispatch:
inputs:
delta_ref:
diff --git a/.github/workflows/util/delta-spark-ut/README.md
b/.github/workflows/util/delta-spark-ut/README.md
index c473c4aa9b..b3119d7d39 100644
--- a/.github/workflows/util/delta-spark-ut/README.md
+++ b/.github/workflows/util/delta-spark-ut/README.md
@@ -18,10 +18,14 @@ limitations under the License.
# Delta Spark UT (Gluten) — managing expected failures
Running delta-io/delta's `spark` ScalaTest suite against the Gluten Velox
-bundle produces **many expected failures**: Gluten does not yet offload every
-Delta code path, and falls back or behaves differently in places. If CI simply
-went red on any failure, the signal would be useless and we could never tell a
-*new* breakage from the hundreds of already-known ones.
+bundle produces **many failures** today. Not because Gluten declines to offload
+a plan -- that should fall back to vanilla Spark and the test should still
pass.
+Some are real gaps: fallback not happening where it should, metrics that differ
+from vanilla, and native-side bugs. Others are expected rather than defects: a
+test that asserts on the query plan sees a different plan once the scan or
+operators are offloaded. If CI simply went red on any failure, the signal
+would be useless and we could never tell a *new* breakage from the hundreds of
+already-known ones.
To make this manageable we keep a **baseline of known failures** and gate each
run against it. The build is green when the only failing tests are ones already
@@ -88,8 +92,9 @@ longer shared between them, those PRs pay for the centos-7
native build twice
- **Per PR** — the workflow's own `paths:` filter runs the suite only when the
PR
touches a **high-signal Delta path**: the Delta integration code
(`backends-velox/src-delta*`), the `gluten-delta` module, or this pipeline's
- own files (`delta_spark_ut.yml`, `util/delta-spark-ut/**`). GitHub evaluates
- the filter before creating the run, so an unrelated PR costs nothing at all.
+ own files (`delta_spark_ut.yml`, `util/delta-spark-ut/**`, excluding Markdown
+ there — editing this README does not run the suite). GitHub evaluates the
+ filter before creating the run, so an unrelated PR costs nothing at all.
Changes to general Velox/core/native code can also affect Delta offload, but
they're touched on most PRs, so per-PR they skip the suite — the nightly run
is
the safety net.
@@ -120,9 +125,11 @@ From the next run onward the gate enforces the baseline.
- **You fixed Gluten and some Delta tests now pass.** CI will flag them as
*now-passing*. Delete those lines from `known-failures.txt` in your PR. That
is the whole point — the baseline only ever shrinks as coverage improves.
-- **You intentionally added a new expected failure** (e.g. a Delta path Gluten
- can't offload yet). Add the exact `Suite#test` line(s) the gate prints under
- *Regressions* to `known-failures.txt`, ideally with a comment explaining why.
+- **You intentionally added a new expected failure** (e.g. a test that asserts
+ on a query plan that legitimately differs once Gluten offloads, or one that
+ hits a tracked bug you are not fixing here). Add the exact `Suite#test`
+ line(s) the gate prints under *Regressions* to `known-failures.txt`, ideally
+ with a comment explaining why.
- **A genuine regression.** Fix it; do **not** add it to the baseline.
The error log prints copy-pasteable `Suite#test` lines for both regressions and
@@ -132,7 +139,8 @@ now-passing tests, and each run's job summary shows the
full breakdown.
After a Delta version bump or a large Gluten change, regenerate from scratch
the
same way as bootstrapping: run the workflow with `update_baseline=true`,
download
-the `delta-spark-ut-known-failures` artifact, and commit it. The aggregate job
+the `delta-spark-ut-known-failures` artifact, and replace `known-failures.txt`
+with the file it contains. The aggregate job
also lists **stale** entries you can prune.
The aggregate job passes `--expected-shards` (the shard count), so if a shard
diff --git a/docs/developers/velox-backend-CI.md
b/docs/developers/velox-backend-CI.md
index d35e5d9b31..c27791f647 100644
--- a/docs/developers/velox-backend-CI.md
+++ b/docs/developers/velox-backend-CI.md
@@ -38,4 +38,30 @@ Since the Docker image is rebuilt weekly, the ccache is
mostly outdated, so it i
## Updating the Docker Image
The GitHub secrets `DOCKERHUB_USER` and `DOCKERHUB_TOKEN` are used to push
Docker images to [Docker Hub](https://hub.docker.com/r/apache/gluten/tags).
-Note that GitHub secrets are not accessible in PRs from forked repos.
\ No newline at end of file
+Note that GitHub secrets are not accessible in PRs from forked repos.
+
+## Delta Spark UT
+`delta_spark_ut.yml` runs delta-io/delta's own `spark` test suite against a
Gluten Velox bundle, so Gluten is
+validated against a real Delta release.
+A number of those tests fail today.
+Not because Gluten declines to offload a plan -- that should fall back to
vanilla Spark and the test should
+still pass.
+Some are real gaps (fallback not happening where it should, metrics that
differ from vanilla, native-side
+bugs), and some are expected: a test that asserts on the query plan sees a
different plan once the scan or
+operators are offloaded, which is by design rather than a defect.
+So the job does not gate on "any failure": it compares each run against a
committed baseline of known failures
+in `.github/workflows/util/delta-spark-ut/known-failures.txt` and fails on a
**new** failure, or on a baseline
+test that starts **passing** (which means the baseline needs updating).
+It also fails outright if a run produced no usable results -- missing or
truncated JUnit reports, or fewer
+shards than expected -- rather than passing on partial data.
+
+It runs per PR only when Delta-relevant paths change (`gluten-delta/**`,
`backends-velox/src-delta*/**`, or
+the pipeline's own files), nightly at 05:00 UTC for full coverage, and on
demand via `workflow_dispatch` --
+use the manual run to check a Velox/core change against Delta before merging.
+
+To refresh the baseline after fixing something, run the workflow with
`update_baseline=true`, download the
+`delta-spark-ut-known-failures` artifact, and use the `known-failures.txt` it
contains to replace
+`.github/workflows/util/delta-spark-ut/known-failures.txt` in the repo.
+See
[.github/workflows/util/delta-spark-ut/README.md](https://github.com/apache/gluten/blob/main/.github/workflows/util/delta-spark-ut/README.md)
+for the gate, the flaky-test quarantine and baseline bootstrapping.
+Open follow-ups are tracked in
[#12743](https://github.com/apache/gluten/issues/12743).
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
