This is an automated email from the ASF dual-hosted git repository.
sandynz pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/shardingsphere.git
The following commit(s) were added to refs/heads/master by this push:
new fed8b48fb30 docs: refine Maven verification freshness rules (#38913)
fed8b48fb30 is described below
commit fed8b48fb30df7cd35c1b090a83a80feea51290f
Author: Hongsheng Zhong <[email protected]>
AuthorDate: Thu Jun 25 12:10:21 2026 +0800
docs: refine Maven verification freshness rules (#38913)
What: prefer IDE/MCP or explicit Maven module scopes before using reactor
expansion, and add a review-pr freshness strategy for mergeability evidence.
Why: reduce repeated mvn -am runs while preserving dependency freshness by
using at-most-once current-head reactor gates only when narrower evidence is
insufficient.
---
.codex/context/token-efficiency.md | 6 +++++-
.codex/skills/review-pr/SKILL.md | 23 ++++++++++++++++++++++-
AGENTS.md | 19 +++++++++++++++----
3 files changed, 42 insertions(+), 6 deletions(-)
diff --git a/.codex/context/token-efficiency.md
b/.codex/context/token-efficiency.md
index 6ff98bb924c..3fc172016ae 100644
--- a/.codex/context/token-efficiency.md
+++ b/.codex/context/token-efficiency.md
@@ -93,8 +93,12 @@ exit "$rc"
Maven build, test, package, install, verification, and plugin goals are
usually `Must Wrap`. Small and bounded version or help checks may run raw.
- Run scoped commands when possible instead of defaulting to whole-repository
builds.
+- Prefer an explicit `-pl <moduleA>,<moduleB>` set when changed modules,
affected test modules, and runtime entry modules are known.
- Add `-am` only when there is a clear reason, such as missing reactor
dependencies, stale dependent module artifacts, CI-equivalent builds, or
commands that require reactor participation.
-- When a Maven command uses `-am`, record why the smaller command was
insufficient.
+- For PR-readiness or mergeability checks, treat `-am` as a current-head
freshness gate that normally runs at most once per unchanged head.
+ Rerun it only after a relevant failure, a code change, or a widened
verification scope.
+- When a Maven command uses `-am`, record why the explicit module set or
smaller command was insufficient.
+- For multi-module checks, prefer bottom-up verification: run lower-level
changed modules first, then higher-level adapter or runtime modules that
consume them.
- On Maven success, extract one summary line such as `BUILD SUCCESS`, `Tests
run:`, or the runner summary from the log.
- On Maven failure, inspect `tail -n 30 "$log_file"` first, then use an
available filtering tool to find `ERROR`, `FAILURE`, `Caused by`, or the failed
test name.
diff --git a/.codex/skills/review-pr/SKILL.md b/.codex/skills/review-pr/SKILL.md
index 461a11c62ea..4f2034dd946 100644
--- a/.codex/skills/review-pr/SKILL.md
+++ b/.codex/skills/review-pr/SKILL.md
@@ -86,6 +86,9 @@ Do not turn speculative risks, personal style preferences, or
out-of-scope polis
9. Breaking change and migration: default behavior, config keys, API/SPI
contracts, protocols, metadata storage, SQL semantics, and released artifacts
have clear compatibility, migration, upgrade, and rollback evidence when
touched.
10. Diagnostics: changed errors, logs, or diagnostic output remain accurate,
actionable, and safe.
11. Dependency and distribution: manifests, lockfiles, packaging, native-image
metadata, LICENSE, NOTICE, and release artifacts are checked for security,
license, compatibility, packaging, and release impact when touched.
+12. Local verification freshness: reviewer-run verification, when used to
support mergeability, must exercise the latest PR head or a clearly identified
current-head artifact.
+ Do not require Maven `-am` when IDE/MCP current-source runs, current-head
installs, CI artifacts,
+ or an explicit `-pl` module set already prove freshness for the reviewed
path.
## Not Mergeable Feedback Mode
@@ -176,6 +179,23 @@ Forbidden sources:
- Unverifiable blogs, forum posts, or AI-reposted content.
+## Local Verification Freshness Strategy
+
+Before choosing a local verification command, decide which evidence is needed
for the latest PR head:
+
+1. Prefer IDE/MCP runs for focused module tests, inspections, Proxy startup,
or run configurations when available and appropriate,
+ because they compile and run current project sources without relying on
stale local Maven artifacts.
+2. Prefer precise Maven module scopes over reactor expansion: identify changed
modules, affected test modules, and runtime entry modules,
+ then use an explicit `-pl <moduleA>,<moduleB>` set when that covers the
reviewed path.
+3. When reactor participation is still needed, keep it to one current-head
freshness gate before final mergeability judgment,
+ except when the first run fails and the PR head changes after a fix.
+4. Use Maven `-am` only when explicit module selection cannot prove dependency
freshness, a required upstream module is missing from local artifacts,
+ or CI-equivalent reactor behavior is itself the evidence.
+5. For multi-module verification, prefer a bottom-up order: validate changed
lower-level modules first,
+ then higher-level adapter or runtime modules that consume them. Stop on the
first relevant failure and update the review evidence before widening scope.
+6. Record the freshness reason in `Verification`, such as `IDE/MCP current
project sources`, `explicit -pl module set covers changed and consuming
modules`,
+ `current-head install already performed`, or `Maven -am used because
dependency freshness was otherwise uncertain`.
+
## Inventory Script Usage
When local git refs are available, use `scripts/build_review_inventory.py` to
generate a bounded local review-inventory draft before deep review.
@@ -532,5 +552,6 @@ Optional `Not Mergeable` sections are `Positive Feedback`,
`Unrelated Changes`,
- Do not output patch-level `Required Change` requests after selecting
`Feedback Mode: Needs Discussion`.
- Do not output `Review Result: Mergeable` when a required hard gate remains
unresolved, including missing required test evidence, release notes, user docs,
migration guidance, or diagnostic quality evidence.
- Do not output `Review Result: Mergeable` for a shared-code change unless you
have checked at least one non-target dialect or feature that also uses the
changed path.
-- Do not output `Review Result: Mergeable` when local verification omitted
`-am` on a module-scoped Maven run and dependency freshness matters.
+- Do not output `Review Result: Mergeable` when local verification used stale
artifacts, freshness-unclear module-scoped Maven output,
+ or an incomplete explicit module set while dependency freshness matters.
- Do not output `Review Result: Mergeable` when Proxy/JDBC DML/DQL
high-frequency SQL paths directly call `ConcurrentHashMap#computeIfAbsent`
without a preceding `get` miss check.
diff --git a/AGENTS.md b/AGENTS.md
index 9881165cde8..c4ce9707339 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -349,8 +349,16 @@ Always state which topology, registry, and engine versions
(e.g., MySQL 5.7 vs 8
- **Success recipe:** explain why the change exists, cite the affected
data-flow step, keep public APIs backward compatible, and record defaults/knobs
alongside code changes.
## Verification & Commands
-- Core commands: `./mvnw clean install -B -T1C -Pcheck` (full build), `./mvnw
test -pl <module>[-am]` (scoped unit tests), `./mvnw -pl <module> -DskipITs
-Dspotless.skip=true -Dtest=<TestClassName> test` (fast verification), `./mvnw
-pl proxy -am -DskipTests package` (proxy packaging/perf smoke).
-- Coverage: when tests change or targets demand it, run `./mvnw test
jacoco:check@jacoco-check -Pcoverage-check` or scoped `-pl <module> -am
-Djacoco.skip=false test jacoco:report`; pair with the Coverage & Branch
Checklist.
+- Core commands: `./mvnw clean install -B -T1C -Pcheck` (full build), `./mvnw
test -pl <module>` (scoped unit tests),
+ `./mvnw -pl <module> -DskipITs -Dspotless.skip=true -Dtest=<TestClassName>
test` (fast verification),
+ `./mvnw -pl <explicit-module-set> -DskipTests package` (scoped packaging or
smoke preparation).
+- Reactor freshness strategy: prefer IDE/MCP current-source runs or precise
`-pl <moduleA>,<moduleB>` Maven scopes.
+ Use `-am` only when dependency freshness, missing local reactor artifacts,
or CI-equivalent behavior cannot be proven otherwise,
+ and normally run that freshness gate at most once per unchanged PR head
before final handoff or mergeability judgment.
+- Module selection: derive the explicit module set from changed modules,
affected tests, and runtime entry modules.
+ For multi-module checks, validate lower-level changed modules first and then
higher-level adapter or runtime modules that consume them.
+- Coverage: when tests change or targets demand it, run `./mvnw test
jacoco:check@jacoco-check -Pcoverage-check`
+ or scoped `-pl <explicit-module-set> -Djacoco.skip=false test
jacoco:report`; pair with the Coverage & Branch Checklist.
- Format: after code or documentation changes, run `./mvnw spotless:apply
-Pcheck -T1C`; do not use any other formatting method.
This must be repeated after the last file-changing action before handoff.
- Style: after formatting, run `./mvnw checkstyle:check -Pcheck -T1C` when
production, test, or project-rule files are touched.
@@ -359,8 +367,11 @@ Always state which topology, registry, and engine versions
(e.g., MySQL 5.7 vs 8
- API bans: if a user forbids a tool/assertion, add it to the plan, avoid it
during implementation, and cite verification searches (e.g., `rg assertEquals`)
in the final report.
## Run & Triage Quick Sheet
-- **Proxy quick start:** `./mvnw -pl proxy -am package` then
`shardingsphere-proxy/bin/start.sh -c conf/server.yaml`; report command, exit
code, config path, and protocol.
-- **JDBC smoke:** `./mvnw -pl jdbc -am test -Dtest=<TestClassName>` with
datasource configs from `examples`; note test name, datasource setup, and
failure logs.
+- **Proxy quick start:** prefer an IDE/MCP `Bootstrap` run configuration or
`./mvnw -pl proxy,<required-upstream-modules> package`
+ when the module set is known; use `./mvnw -pl proxy -am package` only when
dependency freshness cannot otherwise be proven.
+ Report command, exit code, config path, and protocol.
+- **JDBC smoke:** prefer IDE/MCP current-source test runs or `./mvnw -pl
jdbc,<required-upstream-modules> test -Dtest=<TestClassName>`
+ when the module set is known; use `-am` only as the freshness fallback. Note
test name, datasource setup, and failure logs.
- **Config validation:** update standalone `server.yaml` and cluster `mode/`
configs together; call out defaults and any edits that affect both.
- **Failure triage:** collect `proxy/logs/` plus `target/surefire-reports`,
quote the relevant log lines, map them to the data-flow step, and propose the
next diagnostic.
- **Routing mistakes:** check feature-rule configs, metadata freshness, and
parser dialect; include SQL + config snippet plus impacted module (`features`
or `kernel`), and add/plan targeted tests.
