feat(abg): support different binding versions via version prefix

[Vampire]

No description provided.

[Vampire]

• feat(abg): add binding version v2 #1647: 2 dependent PRs (#1624, #1644)
• feat(abg): support different binding versions via version prefix #1639 👈 (View in Graphite)
• refactor(server): put version and comment parsing into one function #2309
• fix(server): prefetch the correct binding artifacts #2298: 2 other dependent PRs (#1602, #2308)
• test(server): add tests showing what artifacts are prefetched #2334
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[Vampire]

Here a sketch how versioned routes could work, or if you like it maybe even the ready implementation. :-)

If a version is marked as deprecated, the binding classes are deprecated with a deprecation message that the binding version is deprecated. It also prints out a warning if you run it manually and additionally when run on GitHub Actions emits a GitHub Actions warning, as most often you will not see this locally due to Maven Local cached binding jar.

I would as far as possible not remove deprecated binding versions, just hint users with it to upgrade to a newer binding version.

New binding versions are by default marked experimental and issue similar warnings, with the last stable binding version in the message.

The BindingVersion can then be propagated down to the generation code where needed to generate things depending on the requested binding version.

The BindingVersion also has a property which library version should be used as dependency version that is compatible with the generated binding version, so that for example a v1 binding does not depend on a library version having a modified Step signature, or that a v2 binding does not depend on a library version that does not yet have the Expression class available.

Theoretically, we could also in the generated classes init block add a version check for compatibility, but I guess most often you will hit a compilation error before already so it will not be reached.

Then when a new binding version is added, we can add a page to the docs that documents which library version is compatible with which binding version, and which breaking changes happened from one binding version to the next, besides requiring a new library version eventually.

[Vampire]

@krzema12 I recently came to the conclusion that version server routes will be a major problem.
Just like with ___minor, ___major, you cannot use a different server route easily.
If I today request actions/checkoutv4 from the v1 route and tomorrow change the repository URL in the workflow script to use the v2 route, then I will still have the v1 checkout jar in MavenLocal and that will be used, as Maven does not store from where a jar was resolved and thus does not redownload it afair.

If I am the one doing the change, I could of course delete the jar from MavenLocal.
But any other person executing those workflow scripts before will have the same problem.

And even worse, if you have one project using v1 route and one project already using v2 route.
You always need to manually nuke the jars from MavenLocal when you switch from one project to the other.

So I guess the plan to use the server route was not a good one, and also this version needs to be stored somewhere in the coordinates, for example

actions:setup-python___commit_lenient:v6.0.0__e797f83bcb11b83ae66e0230d6156d7c80228e7c___binding_version_v2
actions:checkout:v1___binding_version_v3

[Vampire]

Yes, I confirmed now that the problem is exactly like I feared.
To test, I made a condition that only with v1 you get typed bindings and with v2 only untyped bindings.
Then I executed a workflow script with v1 and with typed bindings used.
Change the route to v2, reexecuted the workflow script even with compilation cache disabled and it still compiled and ran successfully.
Then removed the binding from MavenLocal and again rerun the script and now it failed due to not finding the typed bindings.

So as assumed, the binding version must also be part of the coordinates and not of the route.

[Vampire]

Having it in the version is maybe also better for people that use Renovate,
as Renovate could then also suggest updating the the binding version.

The question is what is, whether it will behave better as prefix or suffix, or whether it does not matter.

@file:DependsOn("actions:checkout___major:[v6___binding_version_v2,v7___binding_version_v2-alpha)")
@file:DependsOn("actions:checkout___major:[binding_version_v2___v6,binding_version_v2___v7-alpha)")
@file:DependsOn("actions:checkout:v6___binding_version_v2")
@file:DependsOn("actions:checkout:binding_version_v2___v6")

[Vampire]

Ah, remembering the Renovate algorithm for ranges that I recently majorly improved, I think it needs to be prefix, so

@file:DependsOn("actions:checkout___major:[binding_version_v2___v6,binding_version_v2___v7-alpha)")
@file:DependsOn("actions:checkout:binding_version_v2___v6")

otherwise the range is not properly recognized as one-version closed range.