Transition application versioning from versioninfo to Zephyr's VERSION file

[MarkoSagadin]

Context

Currently, many of our projects use irnas-versioninfo-lib. This library has served us well, as it was automatically running git describe command whenever the build ran. The library then parsed the output of the git describe , extracted specific parts and converted them into the C macros.

The library was developed when Zephyr had no application-specific versioning system. In the past year that changed as Zephyr added support for the VERSION file.

Since it seems that all version-specific logic in the Zephyr and MCUboot will look at the macros that are derived from this VERSION file, it is in our interest to ditch the versioninfo and start using the VERSION file.

However, one drawback that the VERSION file has is the fact that there is no update mechanism. Application developers need to update the contents either manually or write a script that does it for them.

@TjazVracko already wrote such a short Python script that does that. This issue was created so we can think about all possible use-cases and how to integrate this file in the new/old projects in the most seamless way.

Required steps / Implementation details

• The update script can be a part of the Zephyr template, it should be located in the scripts/ folder.
• It should take a path argument to the version file that needs to be updated. As discussed in the IRL with @TjazVracko there is probably no need for an option to take the version as another argument. Parsing the git describe should be enough.
• We need to think about what is the expected use case within the CI.
• We need to think about what is the expected use-case when developing locally.
• We need a working demo setup in this repository and whatever instructions are needed for developers to use this script.
• Decide what the fields in the VERSION mean to the IRNAS team and document that.

I would be very happy if the CI workflow files do not need to change and that script only needs to be called by a specific make target. Then this is in my mind the easiest change to the existing infra that we have set up.

Definition of Done

A new working versioning workflow with the VERSION file and documentation describing relevant details.

[MarkoSagadin]

@KajbaM, @vid553, @eva-cerncic, @KristjanZigart @klancarLuka tagging you all here for the visibility, feel free to comment and suggest ideas.

[TjazVracko]

See the script and other changes in the PR here.

How the script/setup above works:

1. when CI runs a release, make pre-build is run. The script will generate a VERSION file based on the current git tag. Since the version file is ignored in .gitignore. This will thus not taint ˙east release` that is run right after.

---

I suggest a different process in the end:

1. Start with a VERSION file like so:

   VERSION_MAJOR = 0
   VERSION_MINOR = 0
   PATCHLEVEL = 0
   VERSION_TWEAK = 0

2. When making a release, the script above is run, setting the version from git. For example:

VERSION_MAJOR = 0
VERSION_MINOR = 1
PATCHLEVEL = 0
VERSION_TWEAK = 0

3. This would then be committed as part of the release process. (Note that the release process already makes a commit when updating the changelog).
4. Then, the release command is run, generating all the artefacts.

When testing version-related features, a developer can always run make pre-build to update the VERISON file. If he is 4 commits after a release, the file will be:

VERSION_MAJOR = 0
VERSION_MINOR = 1
PATCHLEVEL = 0
VERSION_TWEAK = 4

When a developer is not testing version-related things, the contents of the VERSION file do not matter.

---

Of course, it would be better if the VERSION file was updated for each commit made - this is after all the current behaviour of the version-info lib. But I am unsure how that could be done. There might be a way to still ignore the VERSION file, but commit it in the release process anyway. This way, the VERSION file on GitHub will always be of the last release, and a local VERSION file can be overwritten by the developer whenever.

Maybe we could have a pre-commit hook that updates the version file?

[TjazVracko]

All uses of the version_info.h module in code can be replaced by app_version.h, which is generated by Zephyr.

The build type is now also injected by east as #define EAST_BUILD_TYPE (if the build type is required somewhere).

[MarkoSagadin]

I suggest a different process in the end:

I agree with written, with one modification (as discussed IRL): for the purposes of the CI make the script to accept a "forced" version tag (it would be best if this is done over environment variable).

Then we can have a CI workflow where:

• CHANGELOG is updated.
• VERSION files are updated with the script
• Files are committed
• east release runs

If script receives no version tag, it has to use git describe, that way the scripts are still useful from the development point.

[TjazVracko]

@MarkoSagadin What should the env variable be called?

[MarkoSagadin]

So, after #31 PR and lengthy IRL discussion we have come to several points:

• If git ignored file is added then changes to that file are visible, and git update-index --assume-unchanged has to be used as pointed out above by Tjaz.
• The script throwing the error, if the output of the git describe is not valid tag is not always ok. For example, running git describe on repos without any git tag returns a hash, which is valid case, so we need to support it somehow.
• We are expected to support the *-rc tag in the future, both in the versioning and in CI. Zephyr's VERSION file supports that.
• The valid git tags are in the following format:v<MAJOR>.<MINOR>.<PATCH>[-<EXTRAVERSION>] . Extra version is used for *-rc .
• The valid allowed version format as a CLI input is v<MAJOR>.<MINOR>.<PATCH>[-<EXTRAVERSION>]-<TWEAK> , for example v1.2.3-4 or v1.2.3-rc1-5 .
• To avoid a lot of headaches the VERSION file must be git ignored, but not committed in the template. Developers are expected to run version generate command to create the file on the first clone of the project to avoid the missing app_version.h include error.
• The ./script/version.py should be a part of the east tool, as a east util version or east util gen-version command. This will make the versioning much more integrated with the current versioning of the east release command and it will make it much easier to maintain and update.
• The assumption that the VERSION file must be git ignored must be visibly documented in East, it would also probably be best if the East also checks for this, to prevent possible errors.

Since this will be implemented in east, the #31 won't be merged into main.