Use version catalogs in generated projects

[melix]

Currently we use the "good old" dependency coordinates in generated templates. But instead, we could use the version catalog that we publish alongside the BOM.

For example, this is what the dependencies of a project with Micronaut Data and PostgreSQL would look like when using a catalog:

dependencies {
    annotationProcessor(mn.micronaut.data.processor)
    annotationProcessor(mn.micronaut.http.validation)
    implementation(mn.micronaut.http.client)
    implementation(mn.micronaut.jackson.databind)
    implementation(mn.micronaut.data.jdbc)
    implementation(mn.micronaut.jdbc.hikari)
    implementation(mn.jakarta.annotation.api)
    runtimeOnly(mn.logback)
    runtimeOnly(mn.postgresql)
    implementation(mn.micronaut.validation)
}

Note that this requires updating our generated settings.gradle file:

dependencyResolutionManagement {
   repositories {
       mavenCentral()
   }
   
   repositoriesMode = RepositoriesMode.PREFER_PROJECT
   
   versionCatalogs {
       create("mn") {
           from("io.micronaut:micronaut-bom:$micronautVersion")
       }
   }
}

Also for dependencies which are not in the published catalog, we'd have to add them in the libs catalog.

[sdelamo]

What is the advantage for users? How will we talk about this change?

I am not 100% sure if we should default to version catalogs. Users can use it nowadays. But I am not sure if it will be a confusing default. Is it worth it for them to learn this new syntax?

Moreover, our documentation snippets don't use version catalogue snippets but:

If we are migrating to this new syntax, we should consider to update the asciidoctor macro to generate version catalogue snippets.

On our side, it is going to be a little bit of work.

We will need to do replace every dependency. I guess we will need to replace this:

     generatorContext.addDependency(Dependency.builder()
                .groupId("io.micronaut.problem")
                .artifactId("micronaut-problem-json")
                .compile());

with:

     generatorContext.addDependency(Dependency.builder()
                .groupId("io.micronaut.problem")
                .artifactId("micronaut-problem-json")
                .versionCatalogue("mn.micronaut.problem.json")
                .compile());

We need to keep the maven coordinates for Maven.

Also for dependencies which are not in the published catalog, we'd have to add them in the libs catalog.

What do you mean exactly?

[sdelamo]

On our side, it is going to be a little bit of work.

We will need to do replace every dependency. I guess we will need to replace this:

     generatorContext.addDependency(Dependency.builder()
                .groupId("io.micronaut.problem")
                .artifactId("micronaut-problem-json")
                .compile());

with:

     generatorContext.addDependency(Dependency.builder()
                .groupId("io.micronaut.problem")
                .artifactId("micronaut-problem-json")
                .versionCatalogue("mn.micronaut.problem.json")
                .compile());

Never mind, I think we can implement this easily without having to change the code where we add dependencies.

https://github.com/micronaut-projects/micronaut-starter/pull/1387/files

[melix]

What is the advantage for users?

The same advantages as what we benefit from in our own builds, and, I would say, a more modern way to write build files. But, I would say for me the biggest benefit is that (at least with Kotlin DSL), you can get completion on dependencies, so it's easy to find more dependencies to add.

How will we talk about this change?

We could do something similar to what I wrote in my blog post a few months ago.

If we are migrating to this new syntax, we should consider to update the asciidoctor macro to generate version catalogue snippets

That would be useful indeed. It will probably require extra work to double check that the library is available in the catalog (note that I don't think today we prove that the dependency coordinates we add exist, do we?).

What do you mean exactly?

I mean that it is possible that guides, doco or starter, reference libraries which do not belong to the BOM, hence do not belong to the version catalog. If this is the case, then those libraries will have to be declared in the libs.versions.toml file of the generated project.

[alvarosanchez]

IMO, as a user, version catalogs only make sense with code completion, and currently that is only available for the Kotlin DSL. For a Groovy DSL-based build, it's simply non-existing variables, and I personally prefer a groupId:artifactId string to that.

On the other hand, being able to autocomplete over the hundreds of dependencies that are in the Micronaut BOM is really handy.

[melix]

I use version catalogs even in Groovy scripts, personally. It's hard to get back when you start using this. We could make it an option to use catalogs or not. Reasons I use them in Groovy too:

• allows aliasing libraries, which is much more concise than GAV coordinates
• no need to remember GAV coordinates, also corresponds to a constant
• can handle library versions in a consistent way (but, in the Micronaut case, we'd import a catalog, so it's not an advangage of importing the Micronaut catalog, just an advantage of using catalogs in general)
• smaller PRs when upgrading versions (similar to previous, not necessarily a Micronaut catalog advantage but a generic one)
• bundles!

[grossws]

JFYI, Jetbrains just released IDEA 2022.3 with version catalog autocompletion support for Groovy DSL