Add consideration when consuming Gradle API via Maven coordinate

[lacasseio]

As a user using Gradle API via Maven coordinate (e.g. dev.gradleplugins:gradle-api:<version>), I want to understand the implication behind the mapping of Gradle version and the published API so that I can take any necessary steps to future proof my consumption of the APIs.

The current version scheme seems like the artifact version matches the Gradle version. Although this is mostly true, we are bound by the fact that Maven Central doesn't allow republishing an artifact. If we need to patch the metadata (Gradle module or POM) or the binaries, we must publish them under a new version. There was already a change to the POM metadata starting version 7.0 (if I remember correctly) that wasn't rolled down into previous versions. The strategy we established early on was to publish patched artifacts using the following scheme: <gradle-version>-1, <gradle-version>-2, etc. In theory, this scheme is an implementation detail to how we publish the redistribution artifacts. It would be preferable to use the provided gradleApi(<version>) API offered by dev.gradleplugin.gradle-plugin-development plugin. The same goes for where the plugins are published. At the moment, we use Maven Central. Because of the disrupting event of Bintray shutting down, we took some additional steps to obfuscate where we publish the artifacts, and it's preferable to use gradlePluginDevelopment() repository helper.