From a8335e4bda8f10134dce69804f989bcc3c227d69 Mon Sep 17 00:00:00 2001 From: Julien Herr Date: Thu, 30 Jul 2026 09:52:03 +0200 Subject: [PATCH] docs: make the gate ./gradlew build, not clean build AGENTS.md told agents to run 'clean build' and then, to dodge the six minutes that costs, to judge by hand whether a diff could affect anything. Both halves were wrong. CI runs 'build'. Without 'clean', Gradle's up-to-date check already answers the question the paragraph asked a human to answer, and answers it from the real task inputs rather than a hand-written path list -- a docs-only build finishes in one to three seconds here. Dropping 'clean' removes the incentive to skip and the need to classify, so the paragraph goes with it. The list it carried was wrong in both directions anyway: '.github/workflows/' cannot fail a Gradle build, while LICENSE.txt -- which reads as documentation -- is copied into META-INF of every jar. Comments were listed as safe to skip, but autostyleCheck reflows javadoc and .java files ship in the published sources jar. Also corrects what CI runs: the branches: ['*'] filter in test.yml does not match '/', so pushing a slash-named branch triggers no build at all until a pull request exists, and pull requests get an OpenRewrite check and wrapper validation on top of the matrix. --- AGENTS.md | 11 +++++++++-- CLAUDE.md | 8 ++++---- 2 files changed, 13 insertions(+), 6 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 53e289c0b..8423559a8 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -13,12 +13,19 @@ Checks that only fail once tests are compiled, or after a `clean`, slip straight Prone rules that fire on test fixtures, formatter tasks that were up to date, dependency upgrades that break test code but not main. -The gate is a full build, which is also what CI runs on every push and pull request: +The gate is `./gradlew build`, the same task CI runs. Let Gradle decide how much of it to re-run: +a change that reaches nothing finishes in seconds, so there is no need to judge by hand what a diff +can affect. Add `clean` only to rule out stale output. ```bash -./gradlew clean build # several minutes, must be 0 failures +./gradlew build # minutes when it has work to do, seconds when it does not; 0 failures ``` +A green local build is not a green CI. Pull requests against `master` also run an OpenRewrite check +that `.github/CONTRIBUTING.md` documents, and a wrapper validation. Pushes are weaker than they +look: the `branches: ['*']` filter in `test.yml` does not match `/`, so pushing a branch named +`docs/foo` triggers no build until a pull request exists. + `verifyPublishedPomDependencies` (in `testng/testng-build.gradle.kts`, wired into `check`) pins the exact dependency set of the published pom, versions ignored. When it fails, either the change is wrong or the expected list needs updating — decide which, do not just update the list. diff --git a/CLAUDE.md b/CLAUDE.md index 480aec62a..7f09de85b 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -16,8 +16,8 @@ This needs the `java@` alias to point at an installed version; `mise where` f ## Long-running commands -`./gradlew clean build` takes several minutes — well over the default `Bash` timeout. Pass an -explicit one: +`./gradlew build` takes several minutes whenever it has real work to do — well over the default +`Bash` timeout. Pass an explicit one: ```text timeout: 900000 @@ -29,14 +29,14 @@ without it the pipeline reports grep's status, so a failed build still exits 0: ```bash set -o pipefail -./gradlew --console=plain clean build 2>&1 | grep -E "^BUILD (SUCCESSFUL|FAILED)|[1-9][0-9]* failed" +./gradlew --console=plain build 2>&1 | grep -E "^BUILD (SUCCESSFUL|FAILED)|[1-9][0-9]* failed" ``` For a failure, extract the useful part instead of scrolling: ```bash set -o pipefail -./gradlew --console=plain clean build 2>&1 | grep -A15 "What went wrong" +./gradlew --console=plain build 2>&1 | grep -A15 "What went wrong" ``` Gradle names the HTML report on failure, but locating the failing test is quicker from the result