includeBuild in PluginManagementSpec deincubated in Gradle 8, docs still say it's incubating

[3flex]

Expected Behavior

Docs align to code/behaviour.

Current Behavior

includeBuild in org.gradle.plugin.management.PluginManagementSpec was deincubated in #22391, however composite build docs say:

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.

The promotion to stable also wasn't mentioned in the Gradle 8 release notes (I expected to see it under "Promoted features in the Settings API" in https://docs.gradle.org/8.0/release-notes.html#promoted-features)

Context

• Docs aligning to code would have reduced my confusion when seeing this was deincubated in the IDE.
• It would be good to know if "this does not support all use cases" is still true. I would think if it's a superior but otherwise drop-in replacement for using includeBuild outside pluginManagement that this change would be promoted somewhere in the release notes along with some explanation of why the new method is better than the old.
• org.gradle.api.initialization#includeBuild also hasn't been deprecated now that the new mechanism is stable as the docs suggested would happen.

Steps to Reproduce

N/A

Your Environment

N/A

[eskatos]

Thank you for your interest in Gradle!

This is a valid documentation issue which we will address.

[ljacomet]

Documentation will be updated in upcoming Gradle 8.0.2 release.

However for:

• org.gradle.api.initialization#includeBuild also hasn't been deprecated now that the new mechanism is stable as the docs suggested would happen.

This is not deprecated at this stage, and the only thing that would be deprecated is including build that provide build logic. It remains the preferred way for including builds that do not provide build logic.