Archetype engine

This is similar to Java's class file versioning.

As we evolve the archetype engine with new features, usage of these features will break compatibility with previous CLI releases.

#905 will introduce a new XML file in the cli data that will initially list all the archetype versions. However we will expand this file to include compatibility data.

We can use this file in helidon init to gracefully handle compatibility errors:

• Fail with an error message about compatibility and document which version of the cli is compatible
• Or automatically download a compatible cli version (e.g. under ~/.helidon/lib) and delegate the invocation to a forked process.

Note that incompatibility may not only come from the engine but also from the CLI, (E.g. ArchetypeInvoker, InitCommand etc.) ; thus the version of the archetype engine is simply the cli version.

Here is an example of the file:

<data>
    <archetypes>
        <version>2.0.0</version>
        <version>2.0.1</version>
        <version>2.0.2</version>
        <version>2.1.0</version>
        <version>2.2.0</version>
        <version>2.2.1</version>
        <version>2.2.2</version>
        <version>2.3.0</version>
        <version>2.3.1</version>
        <version>2.3.2</version>
        <version>2.3.3</version>
        <version>2.3.4</version>
        <version>2.4.0</version>
        <version>2.4.1</version>
        <version>2.4.2</version>
        <version>2.5.0</version>
        <version>2.5.1</version>
        <version>2.5.2</version>
        <version>2.5.3</version>
        <version>2.5.4</version>
        <version>2.5.5</version>
        <version>2.6.0</version>
        <version>3.0.0</version>
        <version>3.0.1</version>
        <version>3.0.2</version>
        <version>3.1.0</version>
        <version>3.1.1</version>
        <version default="true">3.1.2</version>
    </archetypes>
    <rules>
        <!-- Helidon version 2.x archetypes are supported by CLI 2.x, 3.x, 4.x -->
        <rule archetype="[2.0.0,3.0.0)" cli="[2.0.0,5.0.0)">
        <!-- Helidon version 3.x archetypes are supported by CLI 3.x, 4.x -->
        <rule archetype="[3.0.0,4.0.0)" cli="[3.0.0,5.0.0)">
        <!-- Helidon version 4.x archetypes are supported by CLI 4.x -->
        <rule archetype="[4.0.0,5.0.0)" cli="[4.0.0,5.0.0)">
    </rules>
</data>

A given version of the cli can filter the list of compatible archetypes as follow:

1. filter the rules that include this cli version
2. filter the archetype versions that match all the cli rules from step 1

Archetype schema

This is similar to Java's source level versioning.

We need a way to automatically detect that an archetype contains incompatible changes.

Any time a new feature is implemented a new archetype schema version should be created, even if there is no schema changes. This will force using a new schema explicitly is order to use features that are not available in previous CLI archetype engines / cli versions.

We will implement a check in the archetype engine and the archetype-maven-plugin that will fail if the schema version of a script is not supported. The check should always refuse to run anything newer than itself (i.e. never forward compatible).

The archetype-maven-plugin can store the information about the latest schema version used within an archetype to avoid having to load all files aggressively (E.g. in META-INF/MANIFEST.MF).