AGENT SKILL

groovy-build

暂无简介

License 许可
Apache-2.0
所属仓库
apache/groovy
最近更新
2026-11-15
Stars
★ 5.5k
Forks
1.9k

02 资源文件 5

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.gradle or settings.gradle edits.
  • Subproject build.gradle edits where the change is build-shape, not source.
  • gradle.properties edits (versions, target bytecode, build flags).
  • Adding, removing, or upgrading a runtime or test dependency, including the matching gradle/verification-metadata.xml regeneration.
  • 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:

  1. 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-*.gradle are the source of truth — read the actual extension type before writing DSL. grep -r "groovyLibrary" build-logic/ finds the real shape.

  2. 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 help after any dependency change and inspect the diff before committing.

  3. Hard-coding versions. Versions live in gradle.properties and the Versions type under build-logic/src/main/groovy/org/apache/groovy/, not as 'group:artifact:1.2.3' literals in subproject build files. See Build infrastructure.

  4. Touching repackagedDependencies without 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:installGroovy and exercise groovy / groovyc against a non-trivial script. On a machine with SDKMAN, unset GROOVY_HOME first — else the launcher silently runs a different Groovy (or fails with ClassNotFoundException: org.codehaus.groovy.tools.GroovyStarter) and the smoke test proves nothing. See "Running your local build".

  5. Editing generated ANTLR sources to "fix" a parser problem. build/generated/sources/antlr4/... is regenerated on every build; the grammar lives in src/antlr/*.g4. See Generated code.

  6. Adding a new runtime dependency without flagging dev@ discussion. ASF rules apply: new runtime dependencies need discussion on dev@ and may require NOTICE / LICENSE updates. AI tooling drafts the dependency change; the contributor decides whether to send the dev@ message.

  7. 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. See COMPATIBILITY.md.

  8. Breaking the configuration cache. AI tooling reaches for eager Project access (project.foo at execution time) instead of the provider chains the build expects. See Build infrastructure.

  9. 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.

  10. 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.

  11. 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.

  12. 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 edits gradle.properties or a build.gradle toolchain block to force a JDK and forgets to revert it, committing a machine-specific path or a changed targetJavaVersion / 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

  1. Classify the scope. Convention plugin (cross-cutting), subproject (local), or root/settings.gradle (project-wide). State which and stay there.

  2. Read the relevant convention plugin first. Skim the org.apache.groovy-* plugin(s) the affected subproject applies, plus Services.groovy / SharedConfiguration / Versions. Don't guess the DSL.

  3. Make the smallest correct change. Per Build infrastructure.

  4. For dependency changes, regenerate verification metadata:

    ./gradlew --write-verification-metadata sha512,pgp help
    

    Inspect the diff; commit only the entries your change actually introduced.

  5. Run targeted → subproject → full — see Targeted runs:

    ./gradlew :<subproject>:<task>
    ./gradlew :<subproject>:check
    ./gradlew build
    
  6. For repackaging or distribution changes, install and exercise. Code-level tests don't catch a broken groovy / groovyc launcher:

    ./gradlew :groovy-binary:installGroovy
    

    unset GROOVY_HOME first on SDKMAN machines, or the launcher exercises a different Groovy / fails with the GroovyStarter ClassNotFoundException. See "Running your local build".

  7. For API-affecting changes, run binary compatibility explicitly — ./gradlew :binary-compatibility:check.

  8. 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 / groovyTargetBytecodeVersion override 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:installGroovy produced a working install, exercised against a non-trivial script with GROOVY_HOME unset so the local build actually ran.
  • [ ] ./gradlew :<subproject>:check passes locally.
  • [ ] ./gradlew build passes — 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 / LICENSE updates in the same change if needed.
  • [ ] Commit message references GROOVY-NNNNN where applicable; AI provenance trailer per AGENTS.md policy.

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.

04 同仓库更多 Skills