build-tools-bump-gradle-api

name

build-tools-bump-gradle-api

description

Bumps the Gradle API version that Kotlin Gradle plugins are compiled against in the Kotlin compiler repository. Use this skill whenever the user asks to upgrade, bump, or update the Gradle compile API version, Gradle plugin API version, or GRADLE_COMMON_COMPILE_API_VERSION. Also use it when the user says something like "update KGP to compile against Gradle X.Y.Z" or "bump Gradle API to X.Y" or "we need to support Gradle X.Y in the plugin".

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, replace_text_in_file, search_in_files_by_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__replace_text_in_file 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__replace_text_in_file 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