Remove unnecessary maven.compiler overrides from plugin pom.xml files and add CI check

wu-sheng · wu-sheng · commit 17f3da918dc6 · 2026-04-16T09:56:13.000+08:00
- Remove maven.compiler.release=17 from spring-ai-1.x-plugin (no JDK 17+ language features used)
- Remove redundant maven.compiler.source/target=8 from aerospike, jedis, nats, micronaut, tomcat plugins
- Add CI script (tools/plugin/check-compiler-overrides.sh) with allowlist to prevent future occurrences
- Update CLAUDE.md and new-plugin skill with compiler level guidance
diff --git a/.claude/skills/new-plugin/SKILL.md b/.claude/skills/new-plugin/SKILL.md
@@ -249,6 +249,11 @@ apm-sniffer/optional-plugins/{name}-plugin/
 - Never bundle target library classes into the plugin JAR
 - If the plugin needs a 3rd-party utility not already in agent-core, discuss with maintainers first
 
+**CRITICAL compiler level rule:**
+- Do NOT set `maven.compiler.release` or `maven.compiler.source/target` unless the plugin source code itself uses JDK 9+ language features (e.g., `var`, records, sealed classes, `java.net.http.HttpClient`).
+- A `provided`-scope dependency targeting a higher JDK (e.g., Spring AI requires JDK 17+) does NOT require raising the compiler level — the plugin only references the library's API at compile time.
+- Bootstrap plugins like `jdk-httpclient-plugin` (which uses JDK 11 `HttpClient` API directly in plugin source code) legitimately need a higher compiler target. SDK plugins and optional plugins generally should not.
+
 ### Register in Parent POM
 
 Add the new module to the parent `pom.xml`:
@@ -1052,6 +1057,7 @@ Before submitting:
 - [ ] Types in `PascalCase`, variables in `camelCase`
 - [ ] Imports only from `java.*`, `org.apache.skywalking.*`, `net.bytebuddy.*` (in instrumentation files)
 - [ ] Target library dependencies in `provided` scope
+- [ ] No unnecessary `maven.compiler.release` or `maven.compiler.source/target` (only set if plugin source uses JDK 9+ language features)
 - [ ] Using V2 API for new plugins
 - [ ] String literals (not `.class` references) in instrumentation definitions
 - [ ] `skywalking-plugin.def` registered
diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml
@@ -73,6 +73,8 @@ jobs:
           java-version: ${{ matrix.java-version }}
       - name: Check Javaagent Plugin List
         run: tools/plugin/check-javaagent-plugin-list.sh
+      - name: Check Plugin Compiler Overrides
+        run: tools/plugin/check-compiler-overrides.sh
       - name: Install and Test
         run: ./mvnw -q --batch-mode clean verify install javadoc:javadoc
 
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -292,5 +292,5 @@ GitHub Actions workflows:
 3. **Respect checkstyle**: No System.out, no @author, no Chinese characters
 4. **Use Lombok**: Prefer annotations over boilerplate code
 5. **Test both unit and E2E**: Different test patterns for different scopes
-6. **Java version compatibility**: Agent core must maintain Java 8 compatibility, but individual plugins may target higher JDK versions (e.g., jdk-httpclient-plugin for JDK 11+, virtual-thread plugins for JDK 21+)
+6. **Java version compatibility**: Agent core must maintain Java 8 compatibility, but individual plugins may target higher JDK versions (e.g., jdk-httpclient-plugin for JDK 11+, virtual-thread plugins for JDK 21+). **Do NOT set `maven.compiler.release` or `maven.compiler.source/target` in a plugin pom.xml unless the plugin source code itself uses JDK 9+ language features.** A `provided`-scope dependency targeting a higher JDK does not require raising the compiler level — the plugin code only references the library's API at compile time and does not need to match the library's runtime JDK requirement.
 7. **For plugin development**: See `apm-sniffer/apm-sdk-plugin/CLAUDE.md` and `apm-sniffer/bootstrap-plugins/CLAUDE.md`
diff --git a/apm-sniffer/apm-sdk-plugin/aerospike-plugin/pom.xml b/apm-sniffer/apm-sdk-plugin/aerospike-plugin/pom.xml
@@ -38,9 +38,5 @@
             <scope>provided</scope>
         </dependency>
     </dependencies>
-    <properties>
-        <maven.compiler.source>8</maven.compiler.source>
-        <maven.compiler.target>8</maven.compiler.target>
-    </properties>
 
 </project>
diff --git a/apm-sniffer/apm-sdk-plugin/jedis-plugins/pom.xml b/apm-sniffer/apm-sdk-plugin/jedis-plugins/pom.xml
@@ -24,8 +24,6 @@
     </parent>
 
     <properties>
-        <maven.compiler.source>8</maven.compiler.source>
-        <maven.compiler.target>8</maven.compiler.target>
         <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
     </properties>
 
diff --git a/apm-sniffer/apm-sdk-plugin/micronaut-plugins/micronaut-http-client-plugin/pom.xml b/apm-sniffer/apm-sdk-plugin/micronaut-plugins/micronaut-http-client-plugin/pom.xml
@@ -27,11 +27,6 @@
 
     <artifactId>micronaut-http-client-plugin</artifactId>
 
-    <properties>
-        <maven.compiler.source>8</maven.compiler.source>
-        <maven.compiler.target>8</maven.compiler.target>
-    </properties>
-
     <dependencies>
         <dependency>
             <groupId>io.projectreactor</groupId>
diff --git a/apm-sniffer/apm-sdk-plugin/micronaut-plugins/micronaut-http-server-plugin/pom.xml b/apm-sniffer/apm-sdk-plugin/micronaut-plugins/micronaut-http-server-plugin/pom.xml
@@ -28,11 +28,6 @@
     <artifactId>micronaut-http-server-plugin</artifactId>
     <packaging>jar</packaging>
 
-    <properties>
-        <maven.compiler.source>8</maven.compiler.source>
-        <maven.compiler.target>8</maven.compiler.target>
-    </properties>
-
     <dependencies>
         <dependency>
             <groupId>io.micronaut</groupId>
diff --git a/apm-sniffer/apm-sdk-plugin/nats-2.14.x-2.16.5-plugin/pom.xml b/apm-sniffer/apm-sdk-plugin/nats-2.14.x-2.16.5-plugin/pom.xml
@@ -29,11 +29,6 @@
     <artifactId>nats-2.14.x-2.16.5-plugin</artifactId>
     <packaging>jar</packaging>
 
-    <properties>
-        <maven.compiler.source>8</maven.compiler.source>
-        <maven.compiler.target>8</maven.compiler.target>
-    </properties>
-
     <dependencies>
         <dependency>
             <groupId>io.nats</groupId>
diff --git a/apm-sniffer/apm-sdk-plugin/spring-plugins/spring-ai-1.x-plugin/pom.xml b/apm-sniffer/apm-sdk-plugin/spring-plugins/spring-ai-1.x-plugin/pom.xml
@@ -31,10 +31,6 @@
     <name>spring-ai-1.x-plugin</name>
     <url>http://maven.apache.org</url>
 
-    <properties>
-        <maven.compiler.release>17</maven.compiler.release>
-    </properties>
-
     <dependencies>
         <dependency>
             <groupId>org.springframework.ai</groupId>
diff --git a/apm-sniffer/apm-sdk-plugin/tomcat-10x-plugin/pom.xml b/apm-sniffer/apm-sdk-plugin/tomcat-10x-plugin/pom.xml
@@ -28,8 +28,6 @@
     <artifactId>tomcat-10x-plugin</artifactId>
 
     <properties>
-        <maven.compiler.source>8</maven.compiler.source>
-        <maven.compiler.target>8</maven.compiler.target>
         <tomcat.version>10.0.22</tomcat.version>
     </properties>
     <dependencies>
diff --git a/tools/plugin/check-compiler-overrides.sh b/tools/plugin/check-compiler-overrides.sh
@@ -0,0 +1,69 @@
+#!/usr/bin/env bash
+
+#
+# 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.
+#
+
+# Check that plugin pom.xml files do not set maven.compiler.release,
+# maven.compiler.source, or maven.compiler.target unless they are on
+# the allowlist.  A provided-scope dependency targeting a higher JDK
+# does NOT justify raising the compiler level — only plugin source code
+# that uses JDK 9+ language features does.
+
+WORK_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && cd ../.. && pwd)"
+
+# Plugins whose source code genuinely uses higher-JDK language features or APIs,
+# or that set <maven.compiler.release /> to cancel a parent POM's value.
+ALLOWLIST=(
+    "bootstrap-plugins/jdk-httpclient-plugin"
+    "bootstrap-plugins/jdk-http-plugin"
+)
+
+EXIT_CODE=0
+
+while IFS= read -r pom; do
+    # Check if this pom is on the allowlist
+    allowed=false
+    for entry in "${ALLOWLIST[@]}"; do
+        if [[ "${pom}" == *"${entry}"* ]]; then
+            allowed=true
+            break
+        fi
+    done
+
+    if [ "${allowed}" = true ]; then
+        continue
+    fi
+
+    # Report the violation
+    echo "ERROR: ${pom} sets a compiler level override but is not on the allowlist."
+    echo "       If the plugin source code uses JDK 9+ language features, add it to the"
+    echo "       allowlist in tools/plugin/check-compiler-overrides.sh."
+    echo "       Otherwise, remove the compiler override from the pom.xml."
+    echo ""
+    EXIT_CODE=1
+done < <(grep -rl "maven\.compiler\.\(release\|source\|target\)" \
+    "${WORK_DIR}/apm-sniffer/apm-sdk-plugin" \
+    "${WORK_DIR}/apm-sniffer/bootstrap-plugins" \
+    "${WORK_DIR}/apm-sniffer/optional-plugins" \
+    "${WORK_DIR}/apm-sniffer/optional-reporter-plugins" \
+    --include="pom.xml")
+
+if [ ${EXIT_CODE} -eq 0 ]; then
+    echo "Compiler override check passed."
+fi
+
+exit ${EXIT_CODE}
