Auto change artifact version in action.yml

[gcw-it]

Fixes #315

• The jbang run command uses automatically the correct artifact version for the action
• The jbang shortcut for Maven Central was changed to simply central
• Updated the approval tests

[gcw-it]

@gsmet Is there a way to create a QuickStart from the locally changed version of the extension?

[gsmet]

I understand your pain and that's why I mostly use main and 999-SNAPSHOT and be done with it.
I know it's not ideal but IIUC I arrived at the conclusion that having versions wasn't so easy (see below).

While your approach is interesting as I didn't think of it at all, I think it has some flaws as you end up having to checkout a git repo, which is something that adds to the action initialization cost and then have a Maven execution (and potentially download missing artifacts) which adds even more.

I wonder if we should instead try to experiment with the Maven release plugin and see if we could adjust the file automatically during the release process.
Something with: https://stackoverflow.com/questions/37963689/maven-release-plugin-automatically-run-a-script-before-commit .
We could provide scripts if not entirely straightforward or even workflows (maybe one to create a branch - the Maven release plugin can also handle that and one to create a version from a branch with automated version increment (apparently --batch-mode will do that)).

What bothers me a bit though is that we need to be completely sure that when you push to a new tag/branch, the jar has to be already available in the repository.

Meaning you cannot be in the following situation:

• the action.yml is in a branch and has been updated
• the jar is not there so the action will fail

As for using the codestart of a deployed extension, if you add the extension with the full GAV (so with :999-SNAPSHOT in it) when you create the project, it will use the updated codestart.

[gsmet]

I don't think this will work as you're going to be in the context of the repo in which you execute the action. It won't download the action code itself.

[gsmet]

If we end up doing that, probably a good idea to rely on ./mvnw as you're not guaranteed there is a Maven environment around (Maven will come with setup-java but you could use this action in a workflow that doesn't use Java at all).

[gcw-it]

@gsmet Thank you for your thoughts.

I completely understand, if you don't want to go down this route, this was simply the first solution that came to mind, mitigating the problem. Please understand it as food for thought for how to get a handle on the issue.

You're probably right, not wanting to add to the initialisation cost generally, and keeping the QuickStart as simple as possible.

For me it was just a bit surprising to deploy a new version of an action, and not having it stick.

To prevent a similar experience for others, we could keep the QuickStart as is, but add a paragraph to the developer reference detailing versioning. Here we could offer a yet to be agreed upon example, on how to adjust the QuickStart to handle versioning. I'll definitely have a look at your idea with the release plugin.

Regarding the versioning, I would proceed as follows:

• Using a detailed version (e.g. v1.0.2) for each release
• Using a major version (eg. v1) pointing to the latest 1.x.x release

As far as I understand it, we should be able to avoid the above mentioned problem

Meaning you cannot be in the following situation:

• the action.yml is in a branch and has been updated
• the jar is not there so the action will fail

by first releasing the minor version, and updating the tag for the major version only, when the release of the new artifact is completed. This results in the following scenario:

• If the client references the minor version directly, then there is no conflict
• If the client references the major version, it will keep referencing the previous version, until the tag is changed

This is how I understand it, but please keep in mind, I'm in no way an expert for GitHub generally, nor GitHub-Actions in particular. Any insights, on how to best get a grip on this problem are highly welcome.

[gsmet]

So there are some thoughts about how to handle things here: https://docs.quarkiverse.io/quarkus-github-action/dev/push-to-production.html but as you have experienced it, the situation is far from being ideal...

I really think we should try the maven-release-plugin + workflow route.

What is going to be a bit annoying are the branches as you basically have two sorts of branches:

• the branches for your code - i.e. at the code level, you want to create and maintain a branch
• the branches for your action

What I'm wondering is if the following would work:

• when creating a branch, we could update the action.yml to point to the current snapshot of this branch
• when releasing a version, we update the action.yml to the released version (I think the Maven release plugin will only push the tag/branch to the origin repo on completion so that might work) - see the completionGoals idea and SO link above
• we don't update action.yml when updating to the new snapshot version so that the branch actually points to the currently released bits: so as soon as you have released something for a given branch, you switched to release mode and you only point to properly tagged artifacts

Because all in all, the action.yml is the only thing that needs to point to the released version in the branch.

If you're interested in pursuing this, I think it would have a lot of value. This thing has been bothering me for quite a while, I totally agree it's in the way of having an experience that is in line with what people expect from GitHub Actions.

Not sure if my plan is clear?

[gcw-it]

I see, where you're aiming at.

I'll definitively look further into this.

Please understand, I can't tell you exactly, when I can make time, to follow this through. I'll write any advances I make or questions I have here.

[gsmet]

Yeah sure, and don't feel obliged to anything. If you play with it and find interesting things about it, please post back and if you want to discuss this further, ping me, I'll be around.

[gcw-it]

This PR version offers support for automatic release versioning via the maven release-plugin.

The versioning scheme for the action should follow the smantic versioning specification (major.minor.incremental):

• new major versions for breaking changes
• new minor versions for new features
• new incremental versions for patches

You should create a new branch for each release, that isn't a patch release.

Before creating a new release, the main branch should be pushed to GitHub.

To release a new version create a new branch named releases/<version_identifier> and push it to GitHub:

• git switch -c releases/v1.0
• git push -u origin releases/v1.0

To release a patch for an existing version, simply add the changes to the respective releases/* branch and push them to GitHub. If appropriate, merge them back to main.

When releasing a new version, a new incremental SNAPSHOT version is created in the releases/* branch and project.next.version in the main branch is set to the next minor version.

After the release workflow has finished you can fetch the new updates with git fetch --tags --force. --force is necessary to update the major version tag, that references the latest action for this major version.

The full version tags have the format v<major>.<minor>.<incremental>, e.g. v1.2.3. The major version tag has the format v<major>, e.g. v1.

The major version tag is changed after the artifact is deployed, therefore the client alwas references a valid version of the action.

Some additional observations:

• The maven release plugin sets the tag in release:prepare before deploying the artifact in release:perform.
• Using the release:branch goal to create a new branch is not possible, because it's missing the necessary extension points (completionGoals, preparationGoals) release:prepare has, to modify action.yml before commiting.
• In the long run it could be beneficial, to write a dedicated maven plugin for the release process.

[gcw-it]

@gsmet If time permits, could you have a look, if that‘s the direction you‘d want to take this issue?