the gradle documentation says in sharing build logic between subprojects:
We recommend putting source code and tests for the convention plugins in the special buildSrc directory in the root directory of the project. For more information about buildSrc , consult Using buildSrc to organize build logic.
then it refers to the gradle build itself, which does it different. what is the reasoning behind? why there is build-logic, and build-logic-commons?
For most builds buildSrc is fine, especially since Gradle 8 which made them more like included builds in some regards where it was different.
I personally prefer included builds for the build logic unless there is some reason like the need to monkey-patch a plugin class.
A real difference you should only see in really big builds with many projects and especially if you do not need every plugin in every project.
buildSrc is always built first and prepended to the build script class paths by being in a highter class loader in the hierarchy. This means that every change in buildSrc will change all class paths and thus might require redoing work that is not necessary. It also means that there is no conflict resolution between things defined in build scripts and things defined in buildSrc, the latter simply wins, which might then cause trouble too, or sometimes might be the solution, depending on the concrete case.
If you have one or multiple included builds for the build logic and within these included builds maybe even multiple projects for different plugins, then only the things actually used and needed are built and only the things that actually use something get invalidated by a change of it and so on.
In simple builds with only few projects, and where all projects apply all build logic convention plugins anyway, the difference in performance should not make much difference since Gradle 8 and it is mainly a matter of preference. I for example prefer to have the build logic in gradle/build-logic or similar.