Provide a clearer link between the documented managed dependency coordinates and version properties

[FyiurAmron]

Going along the lines of #21723 etc. (i.e. switching from the Spring Dependency Management Plugin to platform declarations), one stumbles upon the following problem: not all Managed Dependency Coordinates have equivalent spring-boot-dependencies - which, basically, is because they do not all have equivalent Version Properties. This is somewhat visible even with SDMP, when it's impossible to use ext[] to bump the version of those, but at least you get the managed dependency coordinates defined versions handled by the plugin itself then. However, with just the platform BOM it's completely broken - no coordinates are defined at all, and the buildscripts fail, requiring manual BOM inclusion or explicit coord/version definitions. edit: was the case for OkHttp, but that's actually to be expected

While having this extend to version properties is not strictly required I guess, there is a strict 1:1 relationship between version properties and spring-boot-dependencies BOM as of now, so keeping it that way (version properties===spring-boot-dependencies) would be useful.

TBH, this is not even a strict case where "we don't define those as managed dependency coordinates because there are no BOMs" or "single-use version would unlikely be useful" etc. reasoning would apply. E.g., OkHttp has a well-defined BOM published @ https://mvnrepository.com/artifact/com.squareup.okhttp3/okhttp-bom , and there are a whopping 9 managed dependency coordinates defined for it - but no version properties, and no support via spring-boot-dependencies. The obvious workaround is to use platform BOM explicitly, but why have it as a managed dependency coordinate if one is expected to use the BOM/explicit version manually anyway? edit: see above

My proposal would be to strictly align managed dependency coordinates with version properties with n:1 relationship. FWIW, this would also allow the relevant doc pages and tables to be merged into one, to make it easier to figure which co-ord is applied where and when - knowing which particular version is applied to which particular artifact from the group requires a bit of research ATM, with the quickest way being just looking at https://github.com/spring-projects/spring-boot/blob/v3.4.1/spring-boot-project/spring-boot-dependencies/build.gradle , which somewhat defeats the purpose of version properties page. E.g. if I have a org.apache.kafka.kafka-clients dep, managed dependency coordinates page tells me that 3.8.1 will be used; looking at version properties I might suspect it will use kafka.version, but no real proof exists there (not even the default value of the version is provided in the doc). Only by looking at https://github.com/spring-projects/spring-boot/blob/v3.4.1/spring-boot-project/spring-boot-dependencies/build.gradle#L1098 the relationship gets clear.

Note 1: current docs are obviously right by saying (managed dependency coordinates) "The following table provides details of all of the dependency versions that are provided by Spring Boot in its CLI (Command Line Interface), Maven dependency management, and Gradle plugin." - however, this fails POLA test IMVHO, as one would expect all the Spring Boot Managed Dependency Coordinates to be handled by Spring Boot Dependencies BOM as well :)

Note 2: if a PR is needed here, I'd be happy to help (although this seems easy enough to handle directly by the dev team I guess? :)

[wilkinsona]

Thanks for the report. Unfortunately, I don't think I understand what you're proposing.

Note that the OkHttp (and Spock) entries in Managed Dependency Coordinates should not be there. #43584 has corrected this in the latest snapshots. There are also some other dependencies that should not be there, but currently are due to them being managed by boms that were imported. #42522 is tracking that.

Beyond these two issues, are there any other areas where you believe the managed dependency coordinates and version properties are not aligned?

[FyiurAmron]

@wilkinsona OK, so if I understand this correctly:

1. Managed dependency coordinates has some "legacy" deps that will disappear after 3.4.2 etc., as per Managed Dependency Coordinates lists Spock and OkHttp dependencies that are not managed #43584 etc.,
2. It has some other "legacy" deps that will be removed later on as per spring-boot-dependencies contains unwanted dependency management #42522 ,
3. After those two are handled, all managed dependency coordinates are expected to have a valid version properties and spring-boot-dependencies entries that would allow handling them?

I still think that 1. & 2. doesn't cover all the cases though. See e.g. this:

io.micrometer context-propagation 1.1.2
io.micrometer docs 1.4.1
io.micrometer micrometer-commons 1.14.2

- it's a direct excerpt from managed dependency coordinates page. However, how does one figure out how these match to version properties? I.e. yes, there are

Micrometer micrometer.version
Micrometer Tracing micrometer-tracing.version

- but which of those props are used to manage which co-ords? After manual inspection of https://github.com/spring-projects/spring-boot/blob/v3.4.1/spring-boot-project/spring-boot-dependencies/build.gradle#L1098 I can figure it's probably like this:

io.micrometer context-propagation 1.1.2 ???
io.micrometer docs 1.4.1 micrometer-tracing.version
io.micrometer micrometer-commons 1.14.2 micrometer.version

... because I can't find any version properties that would manage context-propagation even after inspecting the spring-boot-dependencies buildfiles. I thus think the lack of managed dependency coordinates to version properties mapping still happens in some cases even taking #43584 & #42522 into account.

Anyway, I'd still go aligning this and a merge of managed dependency coordinates and version properties doc pages so that each managed dependency coordinate would be provided with a matching version properties. Nobody needs a version properties for "just" Kafka e.g. - people need version properties for a particular co-ords like org.apache.kafka.kafka-clients or groups of them - even if we talk about Spring "packs" or Spring Boot Starters like org.springframework.kafka.spring-kafka , they are explicitly listed in managed dependency coordinates so one would also expect them to go this way, i.e. just tell directly which version properties is used for them.

An added value of refactoring the managed dependency coordinates & version properties page(s) like that is that it makes obvious for everyone if/when a matching version properties is missing.

[wilkinsona]

I think the lack of MDC-to-VP mapping still happens even taking #43584 & #42522 into account

While some of the mappings may be hard to determine, I don't think there's anywhere that there's no mapping. For example, io.micrometer:context-propagation is managed by io.micrometer:micrometer-bom.

We'll see if we can make the relationship between the version properties and the managed dependency coordinates more clear. Unfortunately, I don't think it will be easy, particularly where we've imported a bom. The version properties and the managed dependency coordinates are auto-generated from the spring-boot-dependencies build.gradle file. Producing the table of managed dependency coordinates involves some resolution and then asking Gradle for all the version constraints. As far as I know, the relationship between version properties and dependency constraints is lost as part of this process.

I'm still unclear on what you mean by this:

However, with just the platform BOM it's completely broken - no coordinates are defined at all, and the buildscripts fail, requiring manual BOM inclusion or explicit coord/version definitions.

Can you please provide an example of something being "completely broken"? It may be better to do so as a separate issue as it feels unrelated to the docs providing a clearer mapping between versions properties and managed dependency coordinates.

[FyiurAmron]

@wilkinsona

We'll see if we can make the relationship between the version properties and the managed dependency coordinates more clear.

Well, even just adding the VPs to MDCs on the doc page in the cases where it's relatively obvious (e.g. when the https://github.com/spring-projects/spring-boot/blob/v3.4.1/spring-boot-project/spring-boot-dependencies/build.gradle specifies the mapping explicitly) would make it much easier to use. I understand this is not trivial, but I guess the resolution data could be exported from the buildscript and included into the page, at least in most of the cases?

As to

However, with just the platform BOM it's completely broken - no coordinates are defined at all, and the buildscripts fail, requiring manual BOM inclusion or explicit coord/version definitions.

was the case for OkHttp etc., which you covered. I assume people who had OkHttp managed by Spring Boot will get the short end of the stick, but, as you pointed out, it's specified in the release notes explicitly, so I'd say no action is needed here... and I should read the release notes more often :D

BTW thanks for the quick reply in any case!