Merge pull request #24135 Document de-incubated Settings API

* settings.pluginManagement.includeBuild is no longer incubating
* Clarify limits of using settings.includeBuild for build logic

Fixes #24129

Co-authored-by: Louis Jacomet <louis@gradle.com>

subprojects/docs/src/docs/release/notes.md

@@ -9,6 +9,7 @@ It fixes the following issues:
 * [#24031](https://github.com/gradle/gradle/issues/24031) InstrumentingTransformer generates different class files in Gradle 8 and 7.6 which leads to Remote Build-Cache misses
 * [#24109](https://github.com/gradle/gradle/issues/24109) Extending an already resolved configuration no longer works correctly
 * [#24122](https://github.com/gradle/gradle/issues/24122) Update configuration cache state for some plugins
+* [#24129](https://github.com/gradle/gradle/issues/24129) includeBuild in PluginManagementSpec deincubated in Gradle 8, docs still say it's incubating
 
 Issues fixed in the first patch release: 
 * [#21551](https://github.com/gradle/gradle/issues/21551) Document integration of Scala plugin with toolchains and problems with `target` flag
@@ -364,6 +365,9 @@ The `War.getWebAppDirectory()` method is now considered stable.
 
 ### Promoted features in the `Settings` API
 
+The `includeBuild` methods in `Settings.pluginManagement` are now stable.
+They are the recommended way of including builds that contribute build logic.
+
 The methods `Settings.dependencyResolutionManagement(Action)` and `Settings.getDependencyResolutionManagement()` are now considered stable.
 
 All the methods in `DependencyResolutionManagement` are now stable, except the ones for central repository declaration.

subprojects/docs/src/docs/userguide/authoring-builds/software-product/composite_builds.adoc

@@ -91,9 +91,11 @@ include::sample[dir="snippets/developingPlugins/testingPlugins/kotlin/include-pl
 include::sample[dir="snippets/developingPlugins/testingPlugins/groovy/include-plugin-build",files="settings.gradle[tags=include-build]"]
 ====
 
-NOTE: Including plugin builds via the plugin management block is an incubating feature.
-You may also use the stable `includeBuild` mechanism outside `pluginManagement` to include plugin builds.
-However, this does not support all use cases and including plugin builds like that will be deprecated once the new mechanism is stable.
+[NOTE]
+====
+You may also use the `includeBuild` mechanism outside `pluginManagement` to include plugin builds.
+However, this does not support all use cases and including plugin builds like that might be deprecated in a future Gradle version.
+====
 
 [[included_builds]]
 === Restrictions on included builds