[AE-181] Add check-release-version.yml workflow

[aliphys]

This PR adds a new GitHub workflow to check the releases:

• 🔍 Fails if library.properties and the release have different version numbers
• 💥 Removes the affected release AND the tag, if the workflow fails
• 🧪 Uses https://github.com/dev-drprasad/delete-tag-and-release/ after testing various GitHub actions,

[github-actions]

Memory usage change @ 64d2ef0

Board	flash	%	RAM for global variables	%
arduino:mbed_opta:opta	0 - 0	0.0 - 0.0	0 - 0	0.0 - 0.0
arduino:mbed_portenta:envie_m7	N/A	N/A	N/A	N/A
arduino:renesas_portenta:portenta_c33	0 - 0	0.0 - 0.0	0 - 0	0.0 - 0.0

Click for full report table

Board	extras/tests/TestExisting flash	%	extras/tests/TestExisting RAM for global variables	%	extras/tests/TestFileOperations flash	%	extras/tests/TestFileOperations RAM for global variables	%	extras/tests/TestFolderOperations flash	%	extras/tests/TestFolderOperations RAM for global variables	%	extras/tests/TestRepeatedFormatMount flash	%	extras/tests/TestRepeatedFormatMount RAM for global variables	%	examples/SimpleStorageWriteRead flash	%	examples/SimpleStorageWriteRead RAM for global variables	%	examples/AdvancedUSBInternalOperations flash	%	examples/AdvancedUSBInternalOperations RAM for global variables	%	examples/BackupInternalPartitions flash	%	examples/BackupInternalPartitions RAM for global variables	%
arduino:mbed_opta:opta	0	0.0	0	0.0	0	0.0	0	0.0	0	0.0	0	0.0	0	0.0	0	0.0	0	0.0	0	0.0	0	0.0	0	0.0	0	0.0	0	0.0
arduino:mbed_portenta:envie_m7	N/A	N/A	N/A	N/A	N/A	N/A	N/A	N/A	N/A	N/A	N/A	N/A	N/A	N/A	N/A	N/A	N/A	N/A	N/A	N/A	N/A	N/A	N/A	N/A	N/A	N/A	N/A	N/A
arduino:renesas_portenta:portenta_c33	0	0.0	0	0.0	0	0.0	0	0.0	0	0.0	0	0.0	0	0.0	0	0.0	0	0.0	0	0.0	0	0.0	0	0.0	0	0.0	0	0.0

Click for full report CSV

Board,extras/tests/TestExisting<br>flash,%,extras/tests/TestExisting<br>RAM for global variables,%,extras/tests/TestFileOperations<br>flash,%,extras/tests/TestFileOperations<br>RAM for global variables,%,extras/tests/TestFolderOperations<br>flash,%,extras/tests/TestFolderOperations<br>RAM for global variables,%,extras/tests/TestRepeatedFormatMount<br>flash,%,extras/tests/TestRepeatedFormatMount<br>RAM for global variables,%,examples/SimpleStorageWriteRead<br>flash,%,examples/SimpleStorageWriteRead<br>RAM for global variables,%,examples/AdvancedUSBInternalOperations<br>flash,%,examples/AdvancedUSBInternalOperations<br>RAM for global variables,%,examples/BackupInternalPartitions<br>flash,%,examples/BackupInternalPartitions<br>RAM for global variables,%
arduino:mbed_opta:opta,0,0.0,0,0.0,0,0.0,0,0.0,0,0.0,0,0.0,0,0.0,0,0.0,0,0.0,0,0.0,0,0.0,0,0.0,0,0.0,0,0.0
arduino:mbed_portenta:envie_m7,N/A,N/A,N/A,N/A,N/A,N/A,N/A,N/A,N/A,N/A,N/A,N/A,N/A,N/A,N/A,N/A,N/A,N/A,N/A,N/A,N/A,N/A,N/A,N/A,N/A,N/A,N/A,N/A
arduino:renesas_portenta:portenta_c33,0,0.0,0,0.0,0,0.0,0,0.0,0,0.0,0,0.0,0,0.0,0,0.0,0,0.0,0,0.0,0,0.0,0,0.0,0,0.0,0,0.0

[per1234]

Note that this will make following a specific tag format mandatory (the tag name must match the version value exactly. I think standardizing the tag format is a good thing, but it is only reasonable to expect the project maintainers to comply if the required format is documented.

This could be included in a formal release procedure, which would include instructions to bump the version value in library.properties before tagging. You can see an example of such a document here:

https://github.com/arduino/arduino-ide/blob/main/docs/internal/release-procedure.md

A library release procedure would not be as complex as is required for Arduino IDE, but you get the idea. I find it very useful to have a document like this that I can follow to ensure a 100% successful release even in less complex projects.

Note that the last tag pushed to this repository was named v.1.1.0, which would have been detected as a mismatch even if the version value in library.properties had been correct at the time of the release.

[per1234]

The repository should be checked out at the tagged version. Even though it is common to tag at the revision at the current tip of the default branch, there is no requirement for doing so.

It can be useful to tag a prior revision in the case where a release is needed, but some of the recent work is not yet ready for release. The workflow should accommodate that possibility.

This can be done by moving the checkout step to after the step that gets the tag, then passing the tag to the ref input of the actions/checkout action.

[aliphys]

So you propose that tagging is performed manually by the maintainers?

[per1234]

No, not propose. That is simply the current practice in Arduino's library repositories and no change to that practice had been proposed at the time I wrote this.

It was only later that an alternative procedure, by which the tags and GitHub Releases would be created automatically was proposed (#28 (comment)).

[per1234]

I guess the idea is that you will correct library.properties and then push the deleted tag again?

Moving a tag after it was pushed to a public repository is considered a bad practice that can cause problems:

https://git-scm.com/docs/git-tag#_on_re_tagging

I know that Arduino developers already sometimes re-tag, but formalizing the bad practice in a workflow that is bound to propagate to many projects is another story.

The correct approach is to push a new tag with a correct library.properties (e.g., if the 1.1.0 tag was bad, then bump the version field to 1.1.1 and then push a 1.1.1 tag).

[aliphys]

I know that for the core, tagged versions (but not released) are avaliable via the IDE. Hence the reason the tag must be deleted, although I agree this is not an ideal approach.

[aliphys]

This tag dependant behaviour is mentioned here:

https://github.com/arduino/library-registry/blob/0fe11ac0074785431be01f2bf6362b4b2ccc8224/FAQ.md?plain=1#L56

[per1234]

tagged versions (but not released) are avaliable via the IDE. Hence the reason the tag must be deleted, although I agree this is not an ideal approach.

Note the second step described at the link you shared:

2. checks whether those tags meet the requirements for addition to the index

The Arduino Library Manager engine will reject any tag where the value of the version field of library.properties at the tag is the same as a previously indexed release of the library.

So this means there is no need to delete tags for the sake of Library Manager. The tags where the library maintainer forgot to update the library.properties file before tagging will simply be ignored by the engine.

[sebromero]

Really good feedback @per1234 ! About the documentation part, we're working on a guideline on library development that comes with a chapter about release. @aliphys Can you take a look at Per's suggestions? I agree with his comments.
Also, what if we create 3 manual GH actions that bump the version number in the properties file and creates a tag based on that version. One action for a major release, one for minor, one for patch. @per1234 Do you agree that this could be useful?

[sebromero]

I was thinking a bit and maybe it might be better to check the tags and not the releases because eventually the releases are based on the tags. So on each push we could retrieve the "latest" tag (need to figure out how) and then check the version in the library.properties file for the commit which was tagged with said version. If there is a mismatch, fail the build.
This would be independent of releases and would fail, whenever someone tags a commit without bumping the number in the properties file.

[per1234]

what if we create 3 manual GH actions that bump the version number in the properties file and creates a tag based on that version. One action for a major release, one for minor, one for patch. @per1234 Do you agree that this could be useful?

I think the idea of a GitHub Actions workflow that is manually triggered to take all actions required to produce a perfect release is a good idea.

I would recommend starting from a single workflow and then only split it into multiple workflows if you find that there is a significant amount of completely divergent code for each release type and overhead for switching between them.

You can use the inputs feature of the workflow_dispatch trigger event to allow the maintainer to provide inputs when triggering a run of the workflow:

https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#providing-inputs

So you could add a radio button for which release type to make and an optional text field for specifying a commit hash for the tag (in case some of the staged work is not yet ready for release). That would allow a single workflow to be used for any type of release.

it might be better to check the tags and not the releases because eventually the releases are based on the tags

Definitely. It is common for maintainers to push a tag without ever creating a GitHub release to go with it. The Library Manager engine works exclusively from tags, so it will attempt to index a new tag even if the maintainer didn't create a GitHub release for the tag.

we could retrieve the "latest" tag (need to figure out how)

GitHub Actions provides it via github.ref_name (meaning it isn't even necessary to do an API request):

https://docs.github.com/en/actions/learn-github-actions/contexts#github-context:~:text=The%20short%20ref%20name%20of%20the%20branch%20or%20tag%20that%20triggered%20the%20workflow%20run

[github-actions]

Memory usage change @ 748693f

Board	flash	%	RAM for global variables	%
arduino:mbed_opta:opta	0 - 0	0.0 - 0.0	0 - 0	0.0 - 0.0
arduino:mbed_portenta:envie_m7	N/A	N/A	N/A	N/A
arduino:renesas_portenta:portenta_c33	0 - 0	0.0 - 0.0	0 - 0	0.0 - 0.0

Click for full report table

Board	extras/tests/TestExisting flash	%	extras/tests/TestExisting RAM for global variables	%	extras/tests/TestFileOperations flash	%	extras/tests/TestFileOperations RAM for global variables	%	extras/tests/TestFolderOperations flash	%	extras/tests/TestFolderOperations RAM for global variables	%	extras/tests/TestRepeatedFormatMount flash	%	extras/tests/TestRepeatedFormatMount RAM for global variables	%	examples/SimpleStorageWriteRead flash	%	examples/SimpleStorageWriteRead RAM for global variables	%	examples/AdvancedUSBInternalOperations flash	%	examples/AdvancedUSBInternalOperations RAM for global variables	%	examples/BackupInternalPartitions flash	%	examples/BackupInternalPartitions RAM for global variables	%
arduino:mbed_opta:opta	0	0.0	0	0.0	0	0.0	0	0.0	0	0.0	0	0.0	0	0.0	0	0.0	0	0.0	0	0.0	0	0.0	0	0.0	0	0.0	0	0.0
arduino:mbed_portenta:envie_m7	N/A	N/A	N/A	N/A	N/A	N/A	N/A	N/A	N/A	N/A	N/A	N/A	N/A	N/A	N/A	N/A	N/A	N/A	N/A	N/A	N/A	N/A	N/A	N/A	N/A	N/A	N/A	N/A
arduino:renesas_portenta:portenta_c33	0	0.0	0	0.0	0	0.0	0	0.0	0	0.0	0	0.0	0	0.0	0	0.0	0	0.0	0	0.0	0	0.0	0	0.0	0	0.0	0	0.0

Click for full report CSV

Board,extras/tests/TestExisting<br>flash,%,extras/tests/TestExisting<br>RAM for global variables,%,extras/tests/TestFileOperations<br>flash,%,extras/tests/TestFileOperations<br>RAM for global variables,%,extras/tests/TestFolderOperations<br>flash,%,extras/tests/TestFolderOperations<br>RAM for global variables,%,extras/tests/TestRepeatedFormatMount<br>flash,%,extras/tests/TestRepeatedFormatMount<br>RAM for global variables,%,examples/SimpleStorageWriteRead<br>flash,%,examples/SimpleStorageWriteRead<br>RAM for global variables,%,examples/AdvancedUSBInternalOperations<br>flash,%,examples/AdvancedUSBInternalOperations<br>RAM for global variables,%,examples/BackupInternalPartitions<br>flash,%,examples/BackupInternalPartitions<br>RAM for global variables,%
arduino:mbed_opta:opta,0,0.0,0,0.0,0,0.0,0,0.0,0,0.0,0,0.0,0,0.0,0,0.0,0,0.0,0,0.0,0,0.0,0,0.0,0,0.0,0,0.0
arduino:mbed_portenta:envie_m7,N/A,N/A,N/A,N/A,N/A,N/A,N/A,N/A,N/A,N/A,N/A,N/A,N/A,N/A,N/A,N/A,N/A,N/A,N/A,N/A,N/A,N/A,N/A,N/A,N/A,N/A,N/A,N/A
arduino:renesas_portenta:portenta_c33,0,0.0,0,0.0,0,0.0,0,0.0,0,0.0,0,0.0,0,0.0,0,0.0,0,0.0,0,0.0,0,0.0,0,0.0,0,0.0,0,0.0

[aliphys]

I will close this PR for the following reasons:

• Libraries are considered released, not when a GitHub release is made, but when they are tagged
• GitHub Releases are not taking into account by the Library manager. So deleting releases will not eliminate a mis-versioned release. And eliminating a tag is not enough, a further manual step is needed.
• It is bad practice to delete tags (re-tagging).

An alternative solution is to check to see if the version key corresponds to the latest tagged release or later. This would cause subsequent builds to fail until a re-release(/re-tag) is made.