groovy-build
暂无简介
- License 许可
- Apache-2.0
- 所属仓库
- apache/groovy
- 最近更新
- 2026-11-15
- Stars
- ★ 5.5k
- Forks
- 1.9k
02 资源文件 5
- 参考文档agents/openai.yaml488 B
- 资产文件assets/figma-small.svg818 B
- 资产文件assets/figma.png1.6 KB
- 资产文件assets/icon.svg964 B
- 许可证LICENSE.txt11.1 KB
03 SKILL.md 正文
<!-- Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. -->
name: groovy-build
description: AI-tooling guardrails for changes to the Apache Groovy Gradle build — points at the project's build conventions in ARCHITECTURE.md (convention plugins, version flow through gradle.properties and the Versions type, dependency verification, repackaging, configuration cache, binary compatibility), then adds the AI-specific constraints on top: no fabricated DSL, no hard-coded versions, regenerate verification-metadata.xml after dependency changes, exercise installed builds after repackaging changes, hand-back for review. Use when editing build.gradle, build-logic/, gradle.properties, or gradle/verification-metadata.xml.
license: Apache-2.0
compatibility: claude, codex, copilot, cursor, gemini, aider
metadata:
audience: contributors to apache/groovy
scope: ai-tooling-build-guardrails
Groovy build
This skill is the AI-tooling layer over the project's Gradle
build conventions. The conventions themselves — convention plugins
under build-logic/, version flow through gradle.properties and
the Versions type, dependency verification, repackaging rules,
configuration-cache discipline, binary compatibility — live in
ARCHITECTURE.md's "Build infrastructure" section.
This skill cites them and adds the AI-specific guardrails: no
fabricated DSL, no hard-coded versions, no skipped verification
regeneration, exercise installed builds after repackaging
changes.
groovy-internals— pair with when a build change correlates with a compiler/runtime change (parser grammar, repackaging that affects bytecode-time behaviour).groovy-tests— pair with when a build change affects test-task configuration.groovy-fix-workflow— pair with for the surrounding hand-back contract; build changes use the same artefact shape.ARCHITECTURE.md— the canonical source for build conventions this skill cites; load alongside.CONTRIBUTING.md— for the canonical command sequence and "Running your local build" instructions.
When to use this skill
Use it for:
- Convention plugin changes under
build-logic/src/main/groovy/org.apache.groovy-*.gradle. - Root
build.gradleorsettings.gradleedits. - Subproject
build.gradleedits where the change is build-shape, not source. gradle.propertiesedits (versions, target bytecode, build flags).- Adding, removing, or upgrading a runtime or test dependency,
including the matching
gradle/verification-metadata.xmlregeneration. - Repackaging rules in
groovyLibrary { repackagedDependencies = ... }. - OSGi manifest, JaCoCo aggregation, license-report, dep-updates, Develocity / build-scans, signing and publishing wiring.
subprojects/binary-compatibility/configuration and accepted-API-changes files.- Gradle wrapper version bumps
(
gradle/wrapper/gradle-wrapper.properties).
Don't use it for:
- Compiler, parser, type-checker, AST, or runtime source — that's
groovy-internals. - Adding a regression test or executable AsciiDoc example —
groovy-tests. - AsciiDoc prose under
src/spec/doc/that has no build implication.
Read first
ARCHITECTURE.md"Build infrastructure" — the canonical build conventions this skill cites.README.adoc"Building" — canonical build instructions.COMPATIBILITY.md— stability tiers, what counts as a breaking change, the binary-compatibility check.
Top failure modes
These are the recurring mistakes specific to AI tooling on build changes:
-
Fabricating Gradle DSL. Reaching for plausible-sounding extension names or task types that don't exist in this build. The convention plugins under
build-logic/src/main/groovy/org.apache.groovy-*.gradleare the source of truth — read the actual extension type before writing DSL.grep -r "groovyLibrary" build-logic/finds the real shape. -
Adding a dependency without regenerating
verification-metadata.xml. This breaks the build. AI tooling often forgets the regeneration step. Run./gradlew --write-verification-metadata sha512,pgp helpafter any dependency change and inspect the diff before committing. -
Hard-coding versions. Versions live in
gradle.propertiesand theVersionstype underbuild-logic/src/main/groovy/org/apache/groovy/, not as'group:artifact:1.2.3'literals in subproject build files. See Build infrastructure. -
Touching
repackagedDependencieswithout an installed-build smoke test. A wrong repackaging rule produces a jar that compiles fine but blows up at runtime. After any repackaging change, run./gradlew :groovy-binary:installGroovyand exercisegroovy/groovycagainst a non-trivial script. On a machine with SDKMAN,unset GROOVY_HOMEfirst — else the launcher silently runs a different Groovy (or fails withClassNotFoundException: org.codehaus.groovy.tools.GroovyStarter) and the smoke test proves nothing. See "Running your local build". -
Editing generated ANTLR sources to "fix" a parser problem.
build/generated/sources/antlr4/...is regenerated on every build; the grammar lives insrc/antlr/*.g4. See Generated code. -
Adding a new runtime dependency without flagging dev@ discussion. ASF rules apply: new runtime dependencies need discussion on dev@ and may require
NOTICE/LICENSEupdates. AI tooling drafts the dependency change; the contributor decides whether to send the dev@ message. -
Suppressing binary-compatibility failures. AI tooling can reach for
excludeClass/ suppression as the path of least resistance to green CI. Don't — either justify the change in the accepted-changes file or revert the API breakage. SeeCOMPATIBILITY.md. -
Breaking the configuration cache. AI tooling reaches for eager
Projectaccess (project.fooat execution time) instead of the provider chains the build expects. See Build infrastructure. -
Wrapper version bumps without Develocity compatibility check. A wrapper bump can disable build scans or break a plugin pinned in the root
plugins {}block. See Build infrastructure. -
Reformatting a build script outside the change. Same review-culture rule as code: drive-by reformatting hides intent and is rejected. See the "what not to do" list in
AGENTS.md. -
Downloading a JDK without asking.
sdk install java <ver>(or toolchain auto-provisioning) pulls a large artifact onto the user's machine. AI tooling reaches for it to make a version-specific build or test "just work." Try the JDK that launched Gradle first, then a locally-installed candidate (sdk list java,~/.sdkman/candidates/java/); only if none fits, surface that the JDK is missing and let the contributor decide. The download is a side effect with network, disk, and time cost — it is the contributor's call, like the dev@ discussion in Adding a new runtime dependency without flagging dev@ discussion above. -
Leaving a machine-specific JDK override in a tracked file. To build or test against a specific JDK the supported knob is the
-Ptarget.java.home=<java-home>Gradle property (command line, or~/.gradle/gradle.properties) — see "Building and testing against a specific JDK" and the three-knobs bullet in Build infrastructure. AI tooling instead editsgradle.propertiesor abuild.gradletoolchain block to force a JDK and forgets to revert it, committing a machine-specific path or a changedtargetJavaVersion/groovyTargetBytecodeVersion. Those properties are the single source of truth and move per Groovy version; don't pin them to investigate. If a tracked file must change to reproduce something, revert before hand-back.
Procedure
-
Classify the scope. Convention plugin (cross-cutting), subproject (local), or root/
settings.gradle(project-wide). State which and stay there. -
Read the relevant convention plugin first. Skim the
org.apache.groovy-*plugin(s) the affected subproject applies, plusServices.groovy/SharedConfiguration/Versions. Don't guess the DSL. -
Make the smallest correct change. Per Build infrastructure.
-
For dependency changes, regenerate verification metadata:
./gradlew --write-verification-metadata sha512,pgp helpInspect the diff; commit only the entries your change actually introduced.
-
Run targeted → subproject → full — see Targeted runs:
./gradlew :<subproject>:<task> ./gradlew :<subproject>:check ./gradlew build -
For repackaging or distribution changes, install and exercise. Code-level tests don't catch a broken
groovy/groovyclauncher:./gradlew :groovy-binary:installGroovyunset GROOVY_HOMEfirst on SDKMAN machines, or the launcher exercises a different Groovy / fails with theGroovyStarterClassNotFoundException. See "Running your local build". -
For API-affecting changes, run binary compatibility explicitly —
./gradlew :binary-compatibility:check. -
For config-cache or caching investigations, capture a build scan —
./gradlew --scan <task>.
Hand-back to a human
AI tooling produces build changes; humans review and land. The
hand-back artefact mirrors
groovy-fix-workflow: branch,
commit, gradle commands and outcomes, dependency-verification
regeneration diff (if applicable), installed-build smoke-test
outcome (if repackaging was touched), any cross-repo follow-up
(dev@ discussion for runtime deps, NOTICE / LICENSE updates),
open questions for the committer.
Validation checklist
Before declaring the change ready:
- [ ] Change is in the right scope (convention plugin for cross-cutting; subproject build for local; root for project-wide) — see Build infrastructure.
- [ ] No hard-coded versions in subproject build files.
- [ ] No machine-specific JDK path or
targetJavaVersion/groovyTargetBytecodeVersionoverride left in a tracked file; JDK targeting used-Ptarget.java.home, not a tracked-file edit. No JDK was downloaded without asking. - [ ] Dependency changes are reflected in
gradle/verification-metadata.xml; only the affected entries are touched. - [ ] No edits to files under
build/generated/. - [ ] No formatting changes outside the lines that needed to change.
- [ ] If repackaging or distribution changed:
:groovy-binary:installGroovyproduced a working install, exercised against a non-trivial script withGROOVY_HOMEunset so the local build actually ran. - [ ]
./gradlew :<subproject>:checkpasses locally. - [ ]
./gradlew buildpasses — including:binary-compatibility:check— or any API breakage is justified in the accepted-changes file. - [ ] New runtime dependencies have had dev@ discussion flagged
in the hand-back artefact;
NOTICE/LICENSEupdates in the same change if needed. - [ ] Commit message references
GROOVY-NNNNNwhere applicable; AI provenance trailer perAGENTS.mdpolicy.
References
ARCHITECTURE.md"Build infrastructure" — canonical build conventions.COMPATIBILITY.md— stability tiers, binary-compatibility check.CONTRIBUTING.md— build, test, submission process; "Running your local build".README.adoc— canonical "Building" instructions.AGENTS.md— AI-contributor guidance and ASF provenance rules.build-logic/src/main/groovy/org.apache.groovy-*.gradle— convention plugins (source of truth for subproject shape).gradle/verification-metadata.xml— dependency verification.subprojects/binary-compatibility/— accepted-changes files..agents/skills/groovy-internals/SKILL.md,.agents/skills/groovy-tests/SKILL.md,.agents/skills/groovy-fix-workflow/SKILL.md— pair with as applicable.