anchor.diff:  ----
   =====
   ====
  -In the future, Gradle will consider these flaky-mutations as failures.
  -It also means the configuration needs to flow from the extensions to the tasks.
  -Thus, the task should be configured by the extension and not the other way around.
  +In the future, Gradle will consider this sort of anti-pattern an error and will produce an exception.
   
   3. [[task_configuration_avoidance_guideline_prefer_small_incremental_change]] **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.
   
   4. [[task_configuration_avoidance_guideline_validate_build_logic]] **Ensure a good plan is established for validating the build logic.**
  -Usually, a simple `build` task invocation should do the trick to validate all corner of your build logic.
  -However, if all automation aspect is centralized around Gradle, you may need to validate other task execution path.
  +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.
   
   5. [[task_configuration_avoidance_guideline_prefer_automatic_testing]] **Prefer automatic testing to manual testing.**
   It’s good practice to write integration test for your build logic using TestKit.
   
   6. [[task_configuration_avoidance_guideline_avoid_task_by_name]] **Avoid referencing a task by name.**
  -In the majority of the case, referencing a task by name is a fragile pattern and should be avoided.
  -Although task name is available on the `TaskProvider`, effort should be made to use references from a strongly typed model instead.
  +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.
   
   7. **Use the new task API as much as possible.**
  -The lazy task API is an opt-in feature. Eagerly realizing some tasks may cause a cascade of other tasks to be realized.
  -Using `TaskProvider` helps create an indirection that protects transitive realization.
  +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.
   
   8. Some APIs may be disallowed if you try to access them from the new API's configuration blocks. For example,
   link:{groovyDslPath}/org.gradle.api.Project.html#org.gradle.api.Project:afterEvaluate(org.gradle.api.Action)[`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 hard to track down configuration errors because tasks registered with the new API are not always configured, but an `afterEvaluate` block
  +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.
   
   [[sec:task_configuration_avoidance_migration_steps]]
   === Migration Steps
  -The first part of the migration process is to go through the code and manually migrate eager task creation and configuration to use lazy APIs.
  +The first part of the migration process is to go through the code and manually migrate eager task creation and configuration to use configuration avoidance APIs.
   The following explores the recommended steps for a successful migration.
  -While going through those steps, keep in mind <<#sec:task_configuration_avoidance_general, the guidelines>>.
  +While going through these steps, keep in mind <<#sec:task_configuration_avoidance_general, the guidelines>> above.
   
   [NOTE]
   ====
  -Using the new API in a plugin will require users to use Gradle 4.9 or newer. Plugin authors should refer to <<sec:task_configuration_avoidance_backward_compatibility_migration>> section.
  +Using the new API in a plugin will require users to use Gradle 4.9 or later. Plugin authors should refer to <<sec:task_configuration_avoidance_backward_compatibility_migration>> section.
   ====
   
   1. **Migrate task configuration that affects all tasks (`tasks.all {}`) or subsets by type (`tasks.withType(...) {}`).**
  -This will cause your build to create fewer built-in Gradle task types.
  -Note that despite some built-in Gradle task aren’t using the lazy APIs, the configuration affecting those task type should still be migrated.
  -We recommend using regex code search capability offered by modern IDE.
  -For example, the Intellij regex `\.all\s*((\(?\s*\{)|\(\s*new)` will identify every call to `.all` of a `DomainObjectCollection` and subtype.
  -We will need to go through those result and identify and migrate only the method calls affecting the `TaskContainer` or `TaskCollection`.
  -Be aware of the <<#sec:task_configuration_avoidance_pitfalls, common pitfall around deferred configuration>>.
  +This will cause your build to eagerly create fewer tasks that are registered by plugins.
   
   2. **Migrate tasks configured by name.**
  -Just like the previous point, it will cause your build to create fewer built-in Gradle tasks.
  -For example, logic that uses `TaskContainer#getByName(String, Closure/Action)` would be converted to `TaskContainer#named(String).configure(Closure/Action)`.
  -It also include <<#task_configuration_avoidance_pitfalls_hidden_eager_task_realization, task configuration as DSL blocks>>.
  -Be aware of the <<#sec:task_configuration_avoidance_pitfalls, common pitfall around deferred configuration>>.
  +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_avoidance_pitfalls_hidden_eager_task_realization, task configuration via DSL blocks>>.
   
   3. **Migrate tasks creation to `register(...)`.**
  -It will cause your build to create fewer tasks in general.
  -Be aware of the <<#sec:task_configuration_avoidance_pitfalls, common pitfall around deferred configuration>>.
  -
  -At this point, we should see a decent improvement regarding build configuration.
  -We recommend <<#sec:how_do_i_know_its_working, profiling your build and note the improvement>>.
  -Under some circumstance, you may <<task_configuration_avoidance_troubleshooting_no_improvement, notice no improvement>>.
  -It’s unfortunate, and we feel your frustration. Keep reading onto the next section.
  +At this point, you should change anywhere that you are creating tasks to instead register those tasks.
  +
  +
  +For all steps above, be aware of the <<#sec:task_configuration_avoidance_pitfalls, common pitfalls around deferred configuration>>.
  +
  +After making these changes, you should see improvement in the number of tasks that are eagerly created at configuration time.  Use <<#sec:task_configuration_avoidance_troubleshooting, build scans>> to understand what tasks are still being created eagerly and where this is happening.
   
   [[sec:task_configuration_avoidance_troubleshooting]]
   === Troubleshooting
  -* **The build became unstable after migrating to lazy task configuration.**
  -It’s a common issue that happens during the migration.
  -Follow these next steps to find out the issue:
  -  1. Is the build succeed when all tasks are eagerly realized on creation using the command line flag (`-Dorg.gradle.internal.tasks.eager=true`)?
  -  Verify that <<#task_configuration_avoidance_guideline_only_mutate_task_object, each task configuration only mutating the task>>.
  -
  -  2. Was there any build logic accidentally deleted?
  -  Verify <<#task_configuration_avoidance_guideline_prefer_small_incremental_change, your change log>> for disparity in the configuration that may have been deleted.
  -
  -  3. It may be a real issue.
  -  For example, https://github.com/gradle/gradle-native/issues/737[the issue of `FileCollection` using `TaskProvider` was a real discrepancy] found while migrating a build to lazy task API.
  -  As a rule of thumb, a `TaskProvider` should be accepted everywhere a `Task` instance is accepted.
  -
  -* **Where a task was realized?**
  +* **What tasks are being realized?**
   As we keep developing the feature, more reporting, and troubleshooting information will be made available to answer this question.
   In the meantime, https://gradle.com/enterprise/releases/2018.3#reduce-configuration-time-by-leveraging-task-creation-avoidance[build scan is the best way to answer this question].
   Follow these steps:
  
positive.code: 
  In the event you still need to get access to a Task instance, you can use link:{javadocPath}/org/gradle/api/tasks/TaskCollection.html#named-java.lang.String-[TaskCollection.named(java.lang.String)] and call link:{javadocPath}/org/gradle/api/provider/Provider.html#get--[Provider.get()].  This will cause the task to be created/configured, but everything should work as it has with the eager APIs.
  
  Please https://github.com/gradle/gradle/issues/5664[contact us] if you find tricky build logic that requires you to get a Task instance.
  
  [[sec:task_configuration_avoidance_migration_guidelines]]
  == Migration Guide
  
  The following sections will go through some <<#sec:task_configuration_avoidance_general, general guidelines>> to adhere when migrating the build logic as well as <<#sec:task_configuration_avoidance_migration_steps, the steps>> we recommend following.
  We also cover some <<#sec:task_configuration_avoidance_troubleshooting, troubleshooting>> and <<#sec:task_configuration_avoidance_pitfalls, pitfalls>> to help you work around some issues you may encountered during the migration.
  
  [[sec:task_configuration_avoidance_general]]
  === General
  1. [[task_configuration_avoidance_guideline_use_help_task]] **Use `help` task as a benchmark during the migration.**
  The `help` task is the perfect candidate to benchmark your migration process.
  In a completely lazy build, https://scans.gradle.com/s/o7qmlmmrsfxz4/performance/configuration?openScriptsAndPlugins=WzFd[a build scan should show no task created immediately or created during configuration].
  Only a single task, the `help` task, should be created during task graph calculation.
  Be mindful of <<#task_configuration_avoidance_pitfall_build_scan_plugin, the pitfall around the lazy API usage in the build scan plugin>>.
  
  2. [[task_configuration_avoidance_guideline_only_mutate_task_object]] **Only mutate the current task inside configuration action.**
  Because the task configuration action can now run immediately, later or never, mutating anything other than the current task will expose flaky-like behavior in your build.
  Consider the following code:
  +
  ====
  
negative.code: .Configuration performance tab in build scan annotated
  image::taskConfigurationAvoidance-performance-annotated.png[]
  +
      1. Total tasks present when each task is created or not.
        - "Created immediately" represents tasks that were created using the eager task APIs.
        - "Created during configuration" represents tasks that were created using the configuration avoidance APIs, but were realized explicitly (via `TaskProvider#get()`) or implicitly using the eager task query APIs.
        - Both "Created immediately" and "Created during configuration" numbers are considered the "bad" numbers that should be minimized as much as possible.
        - "Created during task graph calculation" represents the tasks created when building the execution task graph.
        Ideally, this number would be equal to the number of tasks executed.
        - "Not created" represents the tasks that were avoided in this build session.
  
      2. The next section helps answer the question of where a task was realized. For each script, plugin or lifecycle callback, the last column represents the tasks that were created either immediately or during configuration.
      Ideally, this column should be empty.
  
      3. Focusing on a script, plugin, or lifecycle callback will show a break down of the tasks that were created.
  
  [[sec:task_configuration_avoidance_pitfalls]]
  === Pitfalls
  
  * [[task_configuration_avoidance_pitfalls_hidden_eager_task_realization]] **Beware of the hidden eager task realization.**
  There are many ways that a task can be configured eagerly.  For example, configuring a task using the task name and a DSL block will cause the task to immediately be created:
  +
  [source,groovy]
  ----
  // Given a task lazily created with
  tasks.register("someTask")
  
  // Some time later, the task is configured using a DSL block
  someTask {
      // This causes the task to be created and this configuration to be executed immediately
  }
  ----
  +
  Instead use the `named()` method to acquire a reference to the task and configure it:
  +
  [source,groovy]
  ----
  