Release nokee-version-management plugin

[lacasseio]

We are still unsure about the selected plugin id: dev.nokee.distributions-management

The main problem is the namespace. The plugin does not manage native distributions but manages Nokee distributions. Maybe we could use build.nokee.distributions-management (by using the nokee.build DNS) but it doesn't sound right. We could always use a very specialized DNS build.using-nokee.distributions-management.

As for the plugin name itself, distributions-management could be swapped for something better. We need something that makes the most sense for all users and is easy to remember. The goal of this plugin is to make Nokee feels like a core Gradle plugin by making the setup as easy as possible. Names like dev.nokee.setup is short and sweet but have little meaning.

[lacasseio]

Maybe @Ladalz has a great idea. Let me describe the particularity of the plugin as it should be documented and see if we can find a better name for the plugin.

Background

Normally, users would apply an external plugin like this:

plugins {
    id 'dev.nokee.jni-library' version '0.4.0'
    id 'dev.nokee.c-language' version '0.4.0'
}

The previous works great when the plugin is contained in a single library. The Nokee plugins are fragmented into multiple libraries. For this reason, all versions must align. Thus we must avoid things like the following (version misaligned):

plugins {
    id 'dev.nokee.jni-library' version '0.1.0'
    id 'dev.nokee.c-language' version '0.3.0'
}

In a single build script, it's easy to spot, but across multiple build script, it can be quite hard to figure out the issue. From the beginning, we propose using the following blob in settings.gradle:

pluginManagement {
  repositories {
    gradlePluginPortal()
    maven { url = uri("https://repo.nokee.dev/release") }
  }
  resolutionStrategy {
    eachPlugin {
      if (requested.id.id.startsWith("dev.nokee.")) {
        useModule("${requested.id.id}:${requested.id.id}.gradle.plugin:0.4.0")
      }
    }
  }
}

Although not technically correct, it works for most cases. The technically correct blob is much more complex than this. The blob is problematic as it requires the users to understand some advanced Gradle concepts as well as some Gradle oddities. The new plugin referred to, in this issue, will replace the previous blob with something like this:

plugins {
    id 'dev.nokee.distributions-management' version '<version>'
}

The plugin will always perform the technically correct configuration in different scenarios given all the work is abstracted by the plugin.

Plugin documentation

The plugin manages the configuration in relation to the Nokee distribution used. There are two main mandates: 1) the repositories configuration and 2) the version selection/alignment.

The plugin reads the Nokee version from .nokeerc file and performs the appropriate configuration. The plugin configures the correct repository (release or snapshot) based on the Nokee version. The plugin selects the same version for each Nokee plugin resolved during the build process.

The plugin performs additional works not present in the original blob above. The additional work strictly aligns with the two mandates listed and explained above.

@Ladalz We can take the discussion offline and summarize it here after.

[lacasseio]

Maybe we should consider the following changes:

• Use .nokee-version instead of .nokeerc because the rc part of the file doesn't make much sense.
• Rename the plugin to dev.nokee.nokee-version-management to better reflect the plugin strictly manage the version as well as its ownership over .nokee-version file.

[pedrolamarao]

Have you considered the word "platform"? It is used elsewhere to mean an artifact whose purpose is to align versions.

[lacasseio]

That is a good point. I was mostly focused on the "version manager"/"version management" tools often used by other languages/environments: pyenv, rbenv, nvm, etc. The plugin will do a little bit more than align versions. I wrote a very early and quick draft of the plugin reference chapter.

Finding the correct name for this plugin has been quite a challenge. It needs to be easy to remember. Given only the plugin id, users need to have a good enough idea of what the plugin does. I understand the last part is quite hard, but we can expand that if the user has some basic understanding that a plugin is used to manage the Nokee version, it should be obvious which plugin takes care of this capability. This plugin also needs to differentiate itself from the other plugins. All the other plugins produce artifacts in relation to their product. On the other hand, this plugin focus on the user builds itself. The previous name, e.g. distributions-management could be confused with a plugin that manages distributions of native software. The new name focus on two aspects: 1) dev.nokee is the namespace which should not be considered part of the plugin name and 2) nokee-version-management tries to clarify the direct relation to Nokee while indirectly referencing the .nokee-version files. The term management was chosen in contrast to dependencyManagement extension already present in settings.gradle. It's also a better name than manager as plugins should be a capability to the settings/project not act as a tool.

Internally, we may try to use a Gradle platform (BOM), if possible, but right now the version management is handwritten. As mentioned, I didn't consider the term "platform", but I will give it some more thought. I'm not 100% set on the name yet. The name nokee-version-management seems to tick a lot of the boxes I was most concerned with. I need to see how the users react to such a name. Maybe forget a bit about the plugin and see if I still understand what I wrote ;-)

Any suggestion is more than welcome.

[lacasseio]

When considering included build scenarios, version seeding and choosing the right version (from the environment variable, parent builds and remote location) we have a lot of test cases to consider. Although those features weren't part of the initial specs, they quickly fall into scope. We are counting 25 different environmental setups with 5 decision points when choosing the version. The complexity lies mostly with test authoring than the actual implementation. The development of the tests entered a bit of a rabbit hole exploration work which we don't really have the time at this instant. We will park this work and think a bit more about the test setup requiring multiple projects.

[lacasseio]

We should consider this scenario as a potential problem that we may want to try and reproduce.

[lacasseio]

The plugin is now released.