Task Configuration Avoidance

Use help task as a benchmark during the migration. The help task is the perfect candidate to benchmark your migration process. In a build that uses only the configuration avoidance API, a build scan would show no tasks created immediately or created during configuration, and only the tasks that were actually executed would be created. Be mindful of the version of the build scan plugin in use.

Only mutate the current task inside a configuration action. Because the task configuration action can now run immediately, later or never, mutating anything other than the current task can cause indeterminate behavior in your build. Consider the following code:

def check = tasks.register("check")
tasks.register("verificationTask") { verificationTask ->
    // Configure verificationTask

    // Run verificationTask when someone runs check
    check.get().dependsOn verificationTask
}

val check by tasks.registering
tasks.register("verificationTask") {
    // Configure verificationTask

    // Run verificationTask when someone runs check
    check.get().dependsOn(this)
}

def check = tasks.register("check")
def verificationTask = tasks.register("verificationTask") {
    // Configure verificationTask
}
check.configure {
    dependsOn verificationTask
}

val check by tasks.registering
val verificationTask by tasks.registering {
    // Configure verificationTask
}
check {
    dependsOn(verificationTask)
}

Prefer small incremental changes. Smaller changes are easier to sanity check. If you ever break your build logic, it will be easier to analyze the changelog since the last successful verification.

Ensure a good plan is established for validating the build logic. Usually, a simple build task invocation should do the trick to validate your build logic. However, some builds may need additional verification - understand the behavior of your build and make sure you have a good plan for verification.

Prefer automatic testing to manual testing. It’s good practice to write integration test for your build logic using TestKit.

Avoid referencing a task by name. In the majority of cases, referencing a task by name is a fragile pattern and should be avoided. Although the task name is available on the TaskProvider, effort should be made to use references from a strongly typed model instead.

Use the new task API as much as possible. Eagerly realizing some tasks may cause a cascade of other tasks to be realized. Using TaskProvider helps create an indirection that protects against transitive realization.

Some APIs may be disallowed if you try to access them from the new API’s configuration blocks. For example, Project.afterEvaluate() cannot be called when configuring a task registered with the new API. Since afterEvaluate is used to delay configuring a Project, mixing delayed configuration with the new API can cause errors that are hard to diagnose because tasks registered with the new API are not always configured, but an afterEvaluate block may be expected to always execute.

Migrate task configuration that affects all tasks (tasks.all {}) or subsets by type (tasks.withType(…​) {}). This will cause your build to eagerly create fewer tasks that are registered by plugins.

Migrate tasks configured by name. Similar to the previous point, this will cause your build to eagerly create fewer tasks that are registered by plugins. For example, logic that uses TaskContainer#getByName(String, Closure/Action) should be converted to TaskContainer#named(String).configure(Closure/Action). This also includes task configuration via DSL blocks.

Migrate tasks creation to register(…​). At this point, you should change anywhere that you are creating tasks to instead register those tasks.