build-tools-bump-gradle-api

Bump Gradle API Version

This skill walks through bumping GradlePluginVariant.GRADLE_COMMON_COMPILE_API_VERSION — the Gradle API version that the Kotlin Gradle plugins' common source set is compiled against.

IMPORTANT: This project uses JetBrains MCP tools for all file operations. Use mcp__idea__* tools (read_file, apply_patch, search_text, etc.) instead of standard Read/Edit/Grep/Glob tools.

---

Step 1 — Confirm the target version

If the user hasn't specified the target Gradle API version, ask them for it before proceeding.

Read the current value from:

repo/gradle-build-conventions/gradle-plugins-common/src/main/kotlin/gradle/GradlePluginVariant.kt

Look for the companion object and confirm the current GRADLE_COMMON_COMPILE_API_VERSION value, then let the user know what you're about to change it to.

---

Step 2 — Update GRADLE_COMMON_COMPILE_API_VERSION

In repo/gradle-build-conventions/gradle-plugins-common/src/main/kotlin/gradle/GradlePluginVariant.kt, change the constant inside the companion object:

const val GRADLE_COMMON_COMPILE_API_VERSION = "<NEW_VERSION>"

Use mcp__idea__apply_patch to make this change.

---

Step 3 — Regenerate verification-metadata.xml

The new Gradle API version introduces new artifacts whose checksums must be recorded.

3a. Handle local.properties

Check if local.properties contains kotlin.native.enabled=false:

grep -n "kotlin.native.enabled" local.properties 2>/dev/null || echo "not found"

If found, temporarily comment it out (prefix the line with #). Remember to restore it after step 3c.

3b. Run the regeneration script

./scripts/update-verification-metadata.sh

This script:

1. Strips the <components> section from gradle/verification-metadata.xml
2. Runs ./gradlew --write-verification-metadata sha256 -Pkotlin.native.enabled=true resolveDependencies

This can take several minutes. If the script itself doesn't exist or fails, fall back to the manual steps from ReadMe.md:

# Linux
sed -i -e '/<components>/,/<\/components>/d' gradle/verification-metadata.xml
./gradlew --write-verification-metadata sha256 -Pkotlin.native.enabled=true resolveDependencies

3c. Restore local.properties

If you commented out kotlin.native.enabled=false in step 3a, restore it now.

---

Step 4 — Compile kotlin-gradle-plugin and fix errors

Run compilation to surface any API incompatibilities:

./gradlew :kotlin-gradle-plugin:compileKotlin --quiet --console=plain --warning-mode=none 2>&1 | head -100

If that passes cleanly, also verify the common source set compilation (which uses the bumped API):

./gradlew :kotlin-gradle-plugin:classes --quiet --console=plain --warning-mode=none 2>&1 | head -100

Fixing compilation errors

If errors appear, approach them methodically:

1. Identify the source set: Errors in src/common/ affect all Gradle versions. Errors in src/gradleXXX/ affect only that specific variant.

2. Understand the API change: Use mcp__idea__get_symbol_info to look up what replaced a removed or changed API. Check the Gradle release notes for the target version.

3. Apply fixes: Use mcp__idea__apply_patch to update code.

4. Re-run compilation after each round of fixes until it's clean.

5. Check for warnings: After compilation succeeds, run mcp__idea__get_file_problems on any files you changed (with errorsOnly=false). Fix warnings related to your changes.

Common categories of errors when bumping Gradle API:

• Removed internal Gradle classes/methods → find the public replacement
• Changed method signatures → update call sites
• Newly deprecated APIs used in common code → migrate to the replacement

---

Step 5 — Run functionalTest and fix failures

Run the functional tests (these use Gradle's ProjectBuilder API, not full integration tests):

./gradlew :kotlin-gradle-plugin:functionalTest --quiet --console=plain --warning-mode=none 2>&1 | tail -80

Fixing test failures

If failures occur:

1. Read the failure output carefully — determine whether it's a compilation error, an assertion failure, or an exception at runtime.

2. Run just the failing test class to iterate faster:

   ./gradlew :kotlin-gradle-plugin:functionalTest --tests "org.jetbrains.kotlin.gradle.SomeTestClass" --quiet --console=plain --warning-mode=none
   

3. Fix the root cause:

   • If the test setup uses a Gradle API that changed → update the test or test utility
   • If production behavior changed due to the API bump → update the expectation and/or production code
   • Test sources live in libraries/tools/kotlin-gradle-plugin/src/functionalTest/

4. Re-run after each fix until all tests pass.

---

Key files

Path	Purpose
repo/gradle-build-conventions/gradle-plugins-common/src/main/kotlin/gradle/GradlePluginVariant.kt	Contains GRADLE_COMMON_COMPILE_API_VERSION — edit this
repo/gradle-build-conventions/gradle-plugins-common/src/main/kotlin/gradle/GradleCommon.kt	Consumes the constant (3 usages) — read-only reference
scripts/update-verification-metadata.sh	Script to regenerate gradle/verification-metadata.xml
gradle/verification-metadata.xml	Dependency checksum registry — regenerated in step 3
libraries/tools/kotlin-gradle-plugin/src/functionalTest/	Functional test sources
libraries/tools/kotlin-gradle-plugin/AGENTS.md	Area-specific build/test commands
local.properties	May override kotlin.native.enabled — handle carefully in step 3