Module naming and versioning guidelines

      2 min read        guideline

As part of the upcoming 3.3.0 release preparation — module documentation was updated in several places. Among other things module naming and versioning pages were added. Below you can find a summary of our suggestions.

You can already browse the development version of the documentation. It will become the main documentation after the 3.3.0 release.

Note
 You are free to use your own module name and versioning scheme, but standardizing on the same format will make it easier to reuse modules prepared by someone else.

Module naming

See development version of documentation related to module naming.

We suggest using reverse domain convention. You can see an example below:

name: "org.jboss.container.openjdk"
version: "11"
description: "OpenJDK 11 module"

In the image descriptor’s module’s installation section we could see something similar to this:

modules:
    install:
        - name: "org.jboss.container.openjdk"
          version: "11"
        - name: "org.projecta.feature"
          version: "1.2"
        - name: "org.projectb.feature"
          version: "1.12.1"

Here are the main benefits of using such an approach:

  1. Simplicity.

  2. Module maintainer is known immediately by just looking at the name.

  3. Module name clashes are unlikely.

Module versioning

See development version of documentation related to module versioning.

We suggest to follow Python versioning scheme which in the simplest for can be summarized by this:

MAJOR.MINOR.MICRO

Its design is very similar to semantic versioning scheme. You can read about differences between these two here.

Although this versioning scheme does allow for suffixes, we suggest to avoid them.

It’s also worth to note that internally we parse module versions according to Python versioning scheme. This means that if your versioning scheme does not follow it and there will be need to compare it against a PEP 440 defined version — it will always be older. This is another reason to use suggested above versioning.