chore: merge upstream branch gradle/master into main

This commit synchronizes the latest 10 changes from the https://github.com/gradle/gradle/tree/master. The changes include:

c622dee: gradle/gradle#25346 fix gradle/gradle#25235 Improve documentation of configuration-cache.problems option
025e42f: gradle/gradle#27197 Publish 8.5-20231129110721+0000
e6aac35: fix gradle/gradle#25235 Improve documentation of configuration-cache.problems option
9d7ba57: Merge branch 'release'
b2b7523: Publish 8.5-20231129110721+0000
28aca86: gradle/gradle#27186 Mention 'BuildLayout' in section on available services
14cd301: Mention 'BuildLayout' in section on available services
1548184: gradle/gradle#27179 Documentation cleanup for Gradle 8.5
877fd19: update build lifecycle image
987a039: changes based on @ljacomet feedback

platforms/documentation/docs/src/docs/userguide/authoring-builds/basics/build_lifecycle.adoc

@@ -18,8 +18,6 @@
 As a build author, you define tasks and dependencies between tasks.
 Gradle guarantees that these tasks will execute in order of their dependencies.
 
-image::author-gradle-1.png[]
-
 Your build scripts and plugins configure this dependency graph.
 
 For example, if your project tasks include `build`, `assemble`, `createDocs`, your build script(s) can ensure that they are executed in the order `build` -> `assemble` -> `createDoc`.
@@ -42,6 +40,8 @@ Both plugins and build scripts contribute to the task graph via the <<tutorial_u
 
 A Gradle build has three distinct phases.
 
+image::author-gradle-1.png[]
+
 Gradle runs these phases in order:
 
 Phase 1. Initialization::

platforms/documentation/docs/src/docs/userguide/authoring-builds/basics/gradle_directories.adoc

@@ -64,6 +64,8 @@ It is roughly structured as follows:
 <7> Distributions downloaded by the <<gradle_wrapper.adoc#gradle_wrapper,Gradle Wrapper>>.
 <8> Global <<build_environment.adoc#sec:gradle_configuration_properties,Gradle configuration properties>>.
 
+Consult the <<directory_layout.adoc#dir:gradle_user_home,Gradle Directories reference>> to learn more.
+
 [[dir:project_root]]
 == Project Root directory
 
@@ -104,7 +106,7 @@ The anatomy of a typical project root directory looks as follows:
 <8> Usually, a project is organized into one or multiple subprojects.
 <9> Each subproject has its own Gradle build script.
 
-Consult the <<directory_layout.adoc#directory_layout,Gradle Directories reference>> to learn more.
+Consult the <<directory_layout.adoc#dir:project_root,Gradle Directories reference>> to learn more.
 
 [.text-right]
 **Next Step:** <<intro_multi_project_builds.adoc#intro_multi_project_builds,Learn how to structure Multi-Project Builds>> >>

platforms/documentation/docs/src/docs/userguide/authoring-builds/basics/intro_multi_project_builds.adoc

@@ -45,9 +45,9 @@ The directory structure should look as follows:
 ├── gradlew
 ├── gradlew.bat
 ├── settings.gradle.kts  // <1>
-├── subproject-one
+├── sub-project-1
 │   └── build.gradle.kts // <2>
-└── subproject-two
+└── sub-project-2
     └── build.gradle.kts // <2>
 ----
 <1> The `settings.gradle.kts` file should include all subprojects.
@@ -76,7 +76,7 @@ The rest of a project path is a colon-separated sequence of project names, where
 
 [source]
 ----
-:subproject-one
+:sub-project-1
 ----
 
 You can see the project paths when running `gradle projects`:
@@ -88,8 +88,8 @@ Root project 'project'
 ------------------------------------------------------------
 
 Root project 'project'
-+--- Project ':subproject-one'
-\--- Project ':subproject-two'
++--- Project ':sub-project-1'
+\--- Project ':sub-project-2'
 ----
 
 Project paths usually reflect the filesystem layout, but there are exceptions.

platforms/documentation/docs/src/docs/userguide/extending-gradle/custom_gradle_types.adoc

@@ -181,6 +181,7 @@ The following services are available for injection:
 
 - link:{javadocPath}/org/gradle/api/model/ObjectFactory.html[ObjectFactory] - Allows model objects to be created. See <<#nested_objects>> for more details.
 - link:{groovyDslPath}/org.gradle.api.file.ProjectLayout.html[ProjectLayout] - Provides access to key project locations. See <<lazy_configuration.adoc#working_with_files_in_lazy_properties,lazy configuration>> for more details. This service is unavailable in Worker API actions.
+- link:{groovyDslPath}/org.gradle.api.file.BuildLayout.html[BuildLayout] - Provides access to important locations for a Gradle build. This service is only available for injection in settings plugins.
 - link:{groovyDslPath}/org.gradle.api.provider.ProviderFactory.html[ProviderFactory] - Creates `Provider` instances. See <<lazy_configuration.adoc#lazy_configuration,lazy configuration>> for more details.
 - link:{javadocPath}/org/gradle/workers/WorkerExecutor.html[WorkerExecutor] - Allows a task to run work in parallel. See <<custom_tasks.adoc#worker_api,the worker API>> for more details.
 - link:{javadocPath}/org/gradle/api/file/FileSystemOperations.html[FileSystemOperations] - Allows a task to run operations on the filesystem such as deleting files, copying files or syncing directories.

platforms/documentation/docs/src/docs/userguide/optimizing-performance/configuration_cache.adoc

@@ -164,7 +164,7 @@ If enabled in a `gradle.properties` file, you can override that setting and disa
 === Ignoring problems
 
 By default, Gradle will fail the build if any configuration cache problems are encountered.
-When gradually improving your plugin or build logic to support the configuration cache it can be useful to temporarily turn problems into warnings.
+When gradually improving your plugin or build logic to support the configuration cache it can be useful to temporarily turn problems into warnings, with no guarantee that the build will work.
 
 This can be done from the command line:
 

released-versions.json

@@ -1,7 +1,7 @@
 {
   "latestReleaseSnapshot": {
-    "version": "8.5-20231125012006+0000",
-    "buildTime": "20231125012006+0000"
+    "version": "8.5-20231129110721+0000",
+    "buildTime": "20231129110721+0000"
   },
   "latestRc": {
     "version": "8.5-rc-4",