Multiple problems on mixed-versions documentation

[Vampire]

SDK

Other

Description

The docs on https://docs.sentry.io/platforms/java/troubleshooting/mixed-versions/ are ... sub-optimal.

• The example with io.sentry:sentry and io.sentry:sentry-logback is unlucky for Gradle.
  Gradle does not have the nearest-wins non-sense of Maven.
  sentry-logback depends on sentry.
  So you already have the same versions.

• Using a BOM is not really resolving the issue.
  The BOM just declares minimum versions.
  You can still bring in manually or through transitive dependency newer versions of some parts.

  A proper client-side work-around in Gradle for the missing metadata in your publication is to use

  plugins {
      id("org.gradlex.jvm-dependency-conflict-resolution") version "2.5"
  }
  
  jvmDependencyConflicts {
      patch {
          alignWithBom(
              "io.sentry:sentry-bom",
              "io.sentry:sentry",
              "io.sentry:sentry-logback"
              // add all other potential coordinates until https://github.com/gradlex-org/jvm-dependency-conflict-resolution/issues/190 is implemented
          )
      }
  }

  or

  plugins {
      id("org.gradlex.jvm-dependency-conflict-resolution") version "2.5"
  }
  
  // custom implementation until https://github.com/gradlex-org/jvm-dependency-conflict-resolution/issues/190 is implemented
  @CacheableRule
  abstract class AddBomDependencyByGroupMetadataRule @Inject constructor(
      bom: String,
      val group: String
  ) : AddBomDependencyMetadataRule(bom) {
      override fun execute(context: ComponentMetadataContext) {
          if (context.details.id.group == group) {
              super.execute(context)
          }
      }
  }
  
  dependencies {
      components {
          all<AddBomDependencyByGroupMetadataRule> {
              params("io.sentry:sentry-bom", "io.sentry")
          }
      }
  }

  Those will properly ensure that the modules have the same version unless forcefully reconfigured.

• Actually, for Gradle consumers, you should follow the documented procedure on https://blog.gradle.org/alignment-with-gradle-module-metadata. This will automatically align all the version of all the modules which is also done by the work-arounds just described, by providing the necessary metadata in your publication already.

Suggested Solution

• Fix the Gradle example to use two modules were the problem actually exists
• Fix the published metadata of your modules so that the versions are aligned automatically
• Until your publication metadata is fixed with the next release, maybe describe the proper Gradle work-around in the docs

[linear-code]

DOCS-2615