Add "idiomatic builds" documentation page with the current best practices

[vlsi]

Expected Behavior

There should be a documentation page that could be used as an entry point for the current UP-TO-DATE practices.
For instance,

• the idiomatic way is to apply plugins via plugins {..} even though apply(file=...) might work.
• the idiomatic way is to use Action<...> instead of T.() ->.. and Closure configuration blocks.
• the idiomatic way is to prefer "each project configures itself" approach and avoid allprojects, especially for configuring subprojects
• the idiomatic way is to avoid explicit dependsOn and prefer task input-output properties
• the idiomatic way is to make sure each task writes outputs into its own folder (==avoid writing into the same directory by multiple tasks)
• the idiomatic way is to avoid buildscript { classpath {...} }
• the idiomatic way is to avoid from(configurations.runtimeClasspath.toList()) (avoid configuration resolution at configuration time)
• the idiomatic way is to avoid relying on artifact file names and use dependencies instead. For instance, avoid artifact.name != "mssql-jdbc-9.4.0.jre8.jar" and use configuration with excludes.
• the idiomatic way is to avoid relying on classifiers and use variants and attributes instead
• the idiomatic way to share files between projects is ... (see "Sharing outputs between projects" > doesn't work, documentation incomplete? #18846)

Here's the list "things to avoid", however, I'm not sure how to phrase them in "prefer ..."

• Avoid using tasks.named("...") { enabled = false } if you want exclude an artifact from publication. Configure the outgoing artifacts instead (e.g. configurations[...].outgoing { artifacts.removeIf { ... } }). If you use Task.enabled = false, the generated Gradle Metadata file still includes traces of the "skipped" file, so the publication would be inconsistent.

That would help to share the best practices.

See the thread in Gradle Slack: https://gradle-community.slack.com/archives/CA7UM03V3/p1637307179136800

Well, there's idiomatic Kotlin: https://www.youtube.com/watch?v=o4emra1xm88
There's idiomatic Python, and so on

There should be an "idiomatic Gradle build" page as well.

There should be a canonical GitHub repository with samples as well

• Share Gradle samples as GitHub repositories (or a single GitHub repository for all samples) #19179

Current Behavior

https://docs.gradle.org/7.3/userguide/structuring_software_products.html#defining_custom_project_types_as_convention_plugins

Context

See https://kotlinlang.org/docs/idioms.html

apache/calcite#2566

[vlsi]

Here's a case where users can't find "idiomatic way of report aggregation": Kotlin/dokka#1752 (comment)

[ov7a]

Sorry for the late reply.

Thank you for your interest in Gradle!

This is a valid documentation issue that we will address.