Require explicit user opt-in into Parallel Tooling Model Building #35996
Description
Context
Parallel Tooling Model Building or "Parallel Model Fetching" (PMF) is a feature that allows Tooling API clients executing work more efficiently on multi-core machines. The most common application of this is the IDE sync scenarios, where a user build information can be imported faster due to the parallelism, unlocking many IDE features developers are used to.
Historically, Gradle users didn't have direct control over PMF. Instead, it was enabled implicitly when org.gradle.parallel aka "Parallel Execution" (PE) was enabled in the gradle properties.
Gradle 9.4.0 introduces a new property org.gradle.tooling.parallel, which directly controls PMF and takes precendence over org.gradle.parallel. However, to preserve "performance backward-compatibility", the old behavior is still honored, meaning that Parallel Execution implies PMF.
To allow additional flexibility for IDE integrations, another option was introduced in the same release -- org.gradle.tooling.parallel.ignore-legacy-default. When set to true it disables the legacy default behavior, removing the connection between PE and PMF options, making them independent.
Problem
While the introduction of new properties is a required measure for improving the PMF story in IDEA, it leads to added complexity on both sides: for Gradle as well as for IDEs. The root of that complexity is the legacy default behavior, where PE implies PMF.
Removing the legacy default behavior in a minor Gradle version is not appropriate, because many Android Studio users rely on org.gradle.parallel today to enable PMF and deliver their current IDE Sync performance. Disabling PMF can lead to significant performance regressions, especially for larger builds.
Future considerations
In the future, both org.gradle.parallel and org.gradle.parallel.tooling can become absolute with the stabilization of Isolated Projects (IP). Due to additional constraints in place, IP can allow at least the same level of parallelism, while keeping compatible builds safe.
However, it will take time for IP to become stable, and even more time until the ecosystem and individual users can adopt it. So we should probably find a way to improve the situation until then.
Proposal
We can make org.gradle.parallel and org.gradle.parallel.tooling independent options in a major Gradle release.
However, before we do that, we should warn users about the change.
One strategy we can apply is to deprecate not being explicit about the PMF option if PE option is enabled.
In other words, starting from some Gradle version, we issue a deprecation, when we detect org.gradle.parallel=true in the build, while no explicit value for org.gradle.parallel.tooling is provided. To avoid the deprecation, all the users have to do is either enable or disable the PMF property explicitly.
Furthermore, in the same Gradle major, we should make it an error to have the PE property set without explicitly setting the PMF property. The properties will be independent in their effects; however, users won't accidentally lose performance if they upgrade from an older Gradle version that didn't have a deprecation to the Gradle major with the new behavior.
Relevant issues and PRs