Document / prefer use of BOM for resolving SDK artifacts

[cloudshiftchris]

Describe the issue

Currently the documentation here does not show or mention the BOM. Using the BOM should be the default / recommended approach, as it encapsulates the version constraints.

For example, using the BOM will prevent users from specifying different versions - perhaps accidentally or incidentally - for different service client dependencies (and perhaps other runtime dependencies such as http clients). This can happen even with the version catalog, as those versions are merely an input into dependency resolution (not a constraint) - other components (perhaps transitive dependencies) could specify a higher version of a specific JAR, leading to misalignment and subsequent quirky runtime behaviour.

The AWS Java SDK documents using the BOM here (also in other pages for Maven etc).

Links

https://docs.aws.amazon.com/sdk-for-kotlin/latest/developer-guide/setup-create-project-file.html

[0marperez]

Hi, thanks for the report. I understand how this would be a good addition to our documentation. I've set this issue as standard priority (p2) and created an internal ticket for us to track this and implement into our sprints.

[bcmedeiros]

Raised #1508 yesterday which is related to this one. If that one doesn't go ahead, I think it's work mentioning that even with the BOM included, you might need to pay attention to some transitive dependencies being controlled by other BOMs (e.g OkHttp being managed by Spring in a Spring Boot app)

[lauzadis]

The "Create project build files" page now recommends the BOM approach by default.

[github-actions]

⚠️COMMENT VISIBILITY WARNING⚠️

Comments on closed issues are hard for our team to see.
If you need more assistance, please either tag a team member or open a new issue that references this one.
If you wish to keep having a conversation with other community members under this issue feel free to do so.

[cloudshiftchris]

The "Create project build files" page now recommends the BOM approach by default.

@lauzadis this is progress, but not fully there - for example, the "version catalog" section doesn't mention the BOM. Referencing multiple artifacts from a version catalog doesn't provide the same constraints that the BOM does - any of those artifacts could have its resolved version adjusted, leaving it out of sync with others with potential impacts.

It also states:

...keep version numbers synchronized across multiple artifacts.

...which is incorrect. Version catalogs are merely a suggestion, they don't enforce synchronization - that's what the BOM is for.

Gradle doc references:

While version catalogs define versions, they don’t influence the dependency resolution process. Gradle may still select different versions due to dependency graph conflicts or constraints applied through platforms or dependency management APIs.

Versions declared in a catalog are typically not enforced, meaning the actual version used in the build may differ based on dependency resolution.

Reference: https://docs.gradle.org/current/userguide/version_catalogs.html

[cloudshiftchris]

Combining version catalogs for discovery/naming and BOM for constraints would be:

    implementation(platform(awssdk.bom))
    implementation(awssdk.services.codeartifact)
    implementation(awssdk.services.ecr)
    implementation(awssdk.services.s3)

This would ensure that consumers always receive a single/synchronized SDK version, even in the face of dependency conflict resolution, for top level artifacts. Transitive dependencies appear to be missing from the BOM (that's #1508).

[lauzadis]

Thanks @cloudshiftchris for the feedback, I'll take a look at clarifying the docs, probably combining both sub-sections into one.