build-tools-bump-gradle-in-tests

name	build-tools-bump-gradle-in-tests
description	Bump the maximum supported Gradle version in the `kotlin-gradle-plugin-integration-tests` project. Use this whenever the user asks to bump Gradle in integration tests, add a new Gradle X.Y.Z to the test matrix, update `MAX_SUPPORTED` Gradle, "run tests against the new Gradle release", or anything else that sounds like extending the integration test matrix to a newer Gradle. The procedure spans four touch points across three files that must stay in lock-step (`TestVersions.kt`, `build.gradle.kts`, `GradleCompatibilityIT.kt`); reach for this skill even when the user mentions only one of those files, because editing by hand routinely desyncs them.
disable-model-invocation	true

Bump the maximum supported Gradle version in integration tests

The kotlin-gradle-plugin-integration-tests module parameterises its tests across a fixed list of Gradle versions. Bumping the maximum requires synchronised edits to a versions table, a Gradle build list, an AGP compatibility matrix, and a compatibility test's when block — all of which must agree. This skill encodes the procedure.

When to use

Trigger on phrasings such as:

• "bump Gradle in tests" / "bump max Gradle"
• "add Gradle X.Y.Z to integration tests"
• "test against the new Gradle X.Y.Z release"
• "update MAX_SUPPORTED Gradle"
• "support Gradle X.Y in KGP integration tests"

Users frequently mention only one of the affected files; the procedure always touches all of them, so use this skill even if the request looks narrower.

Inputs

Ask the user for the new Gradle version string (e.g. 9.6.0, 9.6.1, 9.6.0-rc-1, 10.0.0). Gradle ships pre-releases with a -rc-N, -milestone-N, or -nightly qualifier; accept those too — the wrapper resolves them like any release. If the user has not provided a version, ask before editing anything.

From MAJOR.MINOR.PATCH[-qualifier] derive:

• constantName = G_<MAJOR>_<MINOR> (always major.minor only — drop the patch and any qualifier from the name)
• constantValue = "<full input string>" (keep patch and qualifier verbatim, since this is the literal string the Gradle wrapper consumes)

If a constant with that name already exists, update its value and the matching gradleVersions list entry in place — do not create a duplicate. Two common shapes for this:

• Patch-only bump (9.5.0 → 9.5.1 on the existing G_9_5)
• RC → stable promotion (9.6.0-rc-1 → 9.6.0 on the existing G_9_6 once the stable release ships)

Steps 4 and 7 still apply — MAX_SUPPORTED and the when branch may need refreshing if the surrounding entries shifted.

Files involved

All edits are inside libraries/tools/kotlin-gradle-plugin-integration-tests/:

File	Edits
src/test/kotlin/org/jetbrains/kotlin/gradle/testbase/TestVersions.kt	3 — new constant, MAX_SUPPORTED, last AgpCompatibilityMatrix entry
build.gradle.kts	1 — append to gradleVersions list
src/test/kotlin/org/jetbrains/kotlin/gradle/GradleCompatibilityIT.kt	1 — new branch in properPluginVariantIsUsed's when

Plus one read-only reference (open it but do not edit it):

• repo/gradle-build-conventions/gradle-plugins-common/src/main/kotlin/gradle/GradlePluginVariant.kt — drives the sourceSetName chosen for the new version.

Tooling

Per the project CLAUDE.md, use JetBrains IDE MCP tools for every read and write on these project files. Specifically:

• Read with mcp__idea__read_file or mcp__idea__get_symbol_info.
• Edit with mcp__idea__replace_text_in_file.
• After each edit, run mcp__idea__get_file_problems with errorsOnly: false and fix any warning attributable to the change.

Do not use Read, Edit, Write, Grep, or Glob on these project files — they bypass the IDE's view of open buffers and can desync.

Step-by-step

Carry these out in order. After each step, briefly state what changed so the user can follow along.

1. Collect inputs

Confirm the target version with the user. Accept MAJOR.MINOR.PATCH and MAJOR.MINOR.PATCH-<qualifier> (Gradle uses -rc-N, -milestone-N, -nightly). Reject obviously wrong input (no recognisable MAJOR.MINOR.PATCH core, or strictly less than the current MAX_SUPPORTED). Compute constantName and constantValue per the "Inputs" section.

2. Pick the Gradle plugin variant

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

Each enum entry has a sourceSetName and a gradleVersion. Pick the variant whose gradleVersion is the highest value ≤ the new Gradle MAJOR.MINOR.

Worked example (today's enum): the last entry is GRADLE_813(sourceSetName = "gradle813", gradleVersion = "8.13", …), so anything in the 8.13+ range — including a bump to 9.6.0 — maps to "gradle813". If a future enum gains a newer entry (e.g. GRADLE_900 covering 9.0+), pick that instead. Always reread the enum at the start of the run; do not rely on a memorised value.

Remember the chosen sourceSetName — step 7 uses it.

3. Add the new constant to TestVersions.Gradle

File: libraries/tools/kotlin-gradle-plugin-integration-tests/src/test/kotlin/org/jetbrains/kotlin/gradle/testbase/TestVersions.kt

Inside object Gradle, after the last const val G_… line and before MIN_UNSUPPORTED_VERSION_TO_CHECK / MIN_SUPPORTED / MAX_SUPPORTED, insert:

const val G_X_Y = "X.Y.Z"

Preserve numerical order with the existing constants.

4. Update MAX_SUPPORTED

In the same file, change:

const val MAX_SUPPORTED = G_<previous>

to:

const val MAX_SUPPORTED = G_X_Y

5. Update the last AgpCompatibilityMatrix entry

In the same file, find the last entry of enum class AgpCompatibilityMatrix. Its third constructor argument is maxSupportedGradleVersion: GradleVersion. Replace its existing constant reference with G_X_Y. Do not change the preceding entries or the minSupportedGradleVersion argument.

Worked example — before, for a 9.6.0 bump:

AGP_91(AGP.AGP_91,   G_9_3,  G_9_5, JavaVersion.VERSION_17),

After:

AGP_91(AGP.AGP_91,   G_9_3,  G_9_6, JavaVersion.VERSION_17),

6. Add the version to gradleVersions in build.gradle.kts

File: libraries/tools/kotlin-gradle-plugin-integration-tests/build.gradle.kts

Find val gradleVersions = listOf(...) (the comment // Must be in sync with TestVersions.kt KTI-1612 sits immediately above it). Append the new version at the end, preserving the trailing-comma style:

val gradleVersions = listOf(
    …
    "9.5.0",
    "X.Y.Z",
)

The list order must mirror TestVersions.Gradle.

7. Add the new branch in gradlePluginVariantIsUsed

File: libraries/tools/kotlin-gradle-plugin-integration-tests/src/test/kotlin/org/jetbrains/kotlin/gradle/GradleCompatibilityIT.kt

Inside fun properPluginVariantIsUsed(...)'s when (gradleVersion) block, insert a new branch as the topmost case (most recent Gradle version first):

GradleVersion.version(TestVersions.Gradle.G_X_Y) -> "<sourceSetName>"

Use the sourceSetName selected in step 2.

Verification

1. Run mcp__idea__get_file_problems (with errorsOnly: false) on each edited file and confirm no new problems attributable to the change.

2. Optionally exercise the compatibility test against the new Gradle:

   ./gradlew :kotlin-gradle-plugin-integration-tests:<prefix>TestsForGradle_X_Y_Z \
       --tests "*GradleCompatibilityIT.properPluginVariantIsUsed*" -q
   

   The task name is generated by the loop in build.gradle.kts (tasks.register<Test>("${taskPrefix}TestsForGradle_${gradleVersion.replace(".", "_")}")); convert dots in the version to underscores. The <prefix> varies by configuration — discover it with ./gradlew :kotlin-gradle-plugin-integration-tests:tasks --all | grep TestsForGradle_X_Y_Z.

Commit conventions

Read docs/code_authoring_and_core_review.md before committing.

A single commit covers all three files. Use the subject style established by prior bumps (see e6f6dba6e8d1 for 9.5.0 and 9cf530c41d41 for 9.4.1):

[Gradle] Run tests against Gradle X.Y.Z release

If a YouTrack issue is associated, add ^KT-XXXXX Fixed on a body line so YouTrack auto-closes it.

Out of scope

• AGP.MAX_SUPPORTED (note its "Update once the Gradle MAX_SUPPORTED version is bumped" comment) — governed by AGP releases, not Gradle, and handled by a separate task.
• Any files outside the three listed in "Files involved" — other modules consume Gradle versions transitively through TestVersions, so the bump propagates without further edits.