// Copyright (C) 2025 Gradle, Inc.
//
// Licensed under the Creative Commons Attribution-Noncommercial-ShareAlike 4.0 International License.;
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      https://creativecommons.org/licenses/by-nc-sa/4.0/
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

[[best_practices_index]]
= Best Practices Index

The table below provides a complete list of documented Gradle Best Practices.

++++
<div style="border: 2px solid #ddd; padding: 1.25em; margin: 10px 0;">
  There are currently <strong><span id="best-practices-total">X</span> Best Practices</strong><span id="best-practices-filtered-text"></span>.
</div>
++++

Use this as a quick reference to track newly added recommendations, check adoption status, or explore areas for improving your build:

++++
<div style="margin: 10px 0;">
  <label for="section-filter" style="margin-right: 10px;">Filter by Section:</label>
  <select id="section-filter" style="margin-right: 20px; width: auto;">
    <option value="">All Sections</option>
  </select>
  <label for="version-filter" style="margin-right: 10px;">Filter by Version:</label>
  <select id="version-filter" style="width: auto;">
    <option value="">All Versions</option>
  </select>
</div>
++++

[.table]
[#best-practices-table]
|===
| Title | Section | Added in Gradle Version

| <<best_practices_general.adoc#use_kotlin_dsl,Use Kotlin DSL>> | General | 8.14
| <<best_practices_general.adoc#use_latest_minor_versions,Use the Latest Minor Version of Gradle>> | General | 8.14
| <<best_practices_general.adoc#use_the_plugins_block,Apply Plugins Using the plugins Block>> | General | 8.14
| <<best_practices_general.adoc#do_not_use_internal_apis,Do Not Use Internal APIs>> | General | 8.14
| <<best_practices_general.adoc#use_the_gradle_properties_file,Set build flags in gradle.properties>> | General | 9.0.0
| <<best_practices_general.adoc#name_your_root_project,Name Your Root Project>> | General | 9.2.0
| <<best_practices_general.adoc#do_not_use_gradle_properties_in_subprojects,Do not use gradle.properties in subprojects>> | General | 9.2.0
| <<best_practices_general.adoc#avoid_after_evaluate,Avoid afterEvaluate>> | General | 9.6.0
| <<best_practices_general.adoc#consider_use_of_incubating_apis_carefully,Consider use of `@Incubating` APIs carefully>> | General | 9.7.0

| <<best_practices_structuring_builds.adoc#modularize_builds,Modularize Your Builds>> | Structuring Builds | 9.0.0
| <<best_practices_structuring_builds.adoc#no_source_in_root,Do Not Put Source Files in the Root Project>> | Structuring Builds | 9.0.0
| <<best_practices_structuring_builds.adoc#favor_composite_builds,Favor build-logic Composite Builds for Build Logic>> | Structuring Builds | 9.0.0
| <<best_practices_structuring_builds.adoc#avoid_empty_projects,Avoid Unintentionally Creating Empty Projects>> | Structuring Builds | 9.1.0
| <<best_practices_structuring_builds.adoc#use_convention_plugins,Use Convention Plugins>> | Structuring Builds | 9.3.0

| <<best_practices_dependencies.adoc#single-gav-string,Single GAV String>> | Dependencies | 8.14
| <<best_practices_dependencies.adoc#use_version_catalogs,Use Version Catalogs to Centralize Dependency Versions>> | Dependencies | 9.0.0
| <<best_practices_dependencies.adoc#name_version_catalog_entries,Name Version Catalog Entries Appropriately>> | Dependencies | 9.0.0
| <<best_practices_dependencies.adoc#set_up_repositories_in_settings,Set up your Dependency Repositories in the Settings file>> | Dependencies | 9.0.0
| <<best_practices_dependencies.adoc#dont_depend_on_kotlin_stdlib,Don’t Explicitly Depend on the Kotlin Standard Library>> | Dependencies | 9.0.0
| <<best_practices_dependencies.adoc#avoid_duplicate_dependencies,Avoid Redundant Dependency Declarations>> | Dependencies | 9.0.0
| <<best_practices_dependencies.adoc#use_content_filtering,Use Content Filtering with multiple Repositories>> | Dependencies | 9.1.0
| <<best_practices_dependencies.adoc#apply_exclusions_narrowly,Apply Exclusions Narrowly>> | Dependencies | 9.2.0
| <<best_practices_dependencies.adoc#use_attributes_on_configurations,Always Declare Attributes on Consumable and Resolvable Configurations>> | Dependencies | 9.7.0

| <<best_practices_tasks.adoc#avoid_depends_on,Avoid DependsOn>> | Task | 8.14
| <<best_practices_tasks.adoc#use_cacheability_annotations, Favor @CacheableTask and @DisableCachingByDefault over cacheIf(Spec) and doNotCacheIf(String, Spec)>> | Task | 8.14
| <<best_practices_tasks.adoc#group_describe_tasks,Group and Describe custom Tasks>> | Task | 9.0.0
| <<best_practices_tasks.adoc#avoid_provider_get_outside_task_action,Do not call `get()` on a Provider outside a Task action>> | Task | 9.1.0
| <<best_practices_tasks.adoc#dont_resolve_configurations_before_task_execution,Don't resolve Configurations before Task Execution>> | Task | 9.1.0
| <<best_practices_tasks.adoc#avoid_eager_file_collection_apis,Avoid using eager APIs on File Collections>> | Task | 9.1.0
| <<best_practices_tasks.adoc#default_path_sensitivities,Prefer `@PathSensitivity.NONE` for file inputs and `@PathSensitivity.RELATIVE` for directories>> | Task | 9.2.0
| <<best_practices_tasks.adoc#use_unique_output_files_and_directories,Use unique output files and directories>> | Task | 9.3.0
| <<best_practices_tasks.adoc#dont_hardcode_task_names,Don't hardcode task names when referring to them>> | Task | 9.7.0
| <<best_practices_tasks.adoc#dont_access_project_instance_inside_task,Don't access a `Project` instance during Task Execution>> | Task | 9.7.0
| <<best_practices_tasks.adoc#map_versus_flatmap,Wiring Task Outputs with `map` and `flatMap`>> | Task | 9.7.0

| <<best_practices_performance.adoc#use_utf8_encoding,Enable UTF‑8>> | Performance | 9.0.0
| <<best_practices_performance.adoc#use_build_cache,Use the Build Cache>> | Performance | 9.1.0
| <<best_practices_performance.adoc#use_configuration_cache,Use the Configuration Cache>> | Performance | 9.1.0
| <<best_practices_performance.adoc#avoid_computations_in_configuration_phase,Avoid Expensive Computations in Configuration Phase>> | Performance | 9.0.0
| <<best_practices_performance.adoc#prefer_bin_distribution,Prefer the `-bin` Gradle Distribution>> | Performance | 9.4.0

| <<best_practices_security.adoc#best_practices_for_security,Validate the Gradle Distribution SHA-256 Checksum>> | Security | 9.1.0
| <<best_practices_security.adoc#validate_wrapper_checksum,Validate the Gradle Wrapper on every Upgrade>> | Security | 9.3.0
| <<best_practices_security.adoc#run_gradle_on_external_projects,Do not Run `./gradlew` on Untrusted Projects>> | Security | 9.7.0
| <<best_practices_security.adoc#builds_should_be_reproducible,Build Output Should Be Byte-for-Byte Reproducible>> | Security | 9.7.0

| <<best_practices_testing.adoc#test_custom_types_with_testkit,Test your custom Task and Plugins with TestKit>> | Testing | 9.4.0
|===

++++
<script src="js/best-practices-filter-sort.js"></script>
++++
