Automatically update version number by appending git hash

[arporter]

At the telco today, we agreed that the PSyclone version number (stored in src/psyclone/version.py and also in doc/reference_guide/doxygen.config) should have the git hash of the last commit (to master) appended to it. This will enable people to see when they are working with a version checked-out of GitHub, as opposed to a released version.

We could do this manually as part of the end-of-the-review process but it would be much better if we could automate it using a GitHub Action.

[hiker]

I've found https://stackoverflow.com/questions/3442874/in-git-how-can-i-write-the-current-commit-hash-to-a-file-in-the-same-commit. In short, we can't add the hash before writing the file (since adding the hash will change the hash). One solution mentioned was to use the previous hash. Or we could use the post-checkout hook? Not sure how this works with updates, merge, cherry-pick etc.
git attributes are mentioned, but they apparently need to be installed each time manually(?)

On https://softwareengineering.stackexchange.com/questions/333680/how-to-version-when-using-trunk-based-development it was mentioned:

To differentiate "trunk-builds" from official releases, it is common to add a suffix like snapshot-DATETIME to the version number.

Not sure if this can be automated (i.e. modified automatically on commit) - I did a brief search, and there seems to be odd cases where modifying file might have unexpected side effects. I hope one of you knows more of git hooks than I do :)

I am getting the feeling that just adding "-alpha" to the version number after a release might be the easiest option (and would work for me, all I need is to distinguish current master from the last release). It would also follow the semantic versioning standard (https://semver.org/).

One other idea: version.py tries to run and interpret git branch (we can't use git branch --show-current, it provides no output in case of a tag or hash based checkout). Possible outcomes (not sure if this list is really complete)

• (HEAD detached at 2.5.0) --> checked out tags/2.5.0 - identified by a regular expression of integers and dots
• (HEAD detached at 2f4162581) --> checked out a hash - identified by not a version number as above, and a valid hex number
• Any other non-error: we are on a branch - use the existing version number and append - with branch-name (2.5.0-257_verify_loop_fusion)
• Error - not a git checkout, just use the existing version number.

[arporter]

Thanks for thoroughly investigating Joerg. I like the idea of sticking to SemVer but I'm worried we're going to have e.g. 'alpha' versions of releases that will never actually exist. e.g. at the moment we should probably be at 3.0-alpha which is fine as we will definitely release 3.0. As soon as that is out of the door, we bump the 'working' version to 3.1-alpha. Say we then discover a bug in 3.0 that requires an immediate fix so we need to release 3.0.1. Do we backport the bug fix to 3.0 and then release that or does it go into 3.1? I guess the answer will depend on how urgently the bug fix is needed?

[hiker]

I would have said to use 3.0.0.1-alpha. But we could also just add ... hot or so - calling it 3.0-hot?

Maye not ideal, but KISS.

[arporter]

Incidentally, when we build the fparser documentation it gives us:

which at least makes it very clear you've not got '0.1.5'.

[hiker]

While not ideal (the reg-exp becomes a bit too general, but I guess a sequence of int and dots, and then letters, digits, + would be ok). It looks a bit like the output of git describe:

$ git describe
0.0.15-447-g2d8cef7

The 447 seems to be the number of commits since ... the last tag or release or so?

But (I think) again the problem: the doc is not part of a commit, it can use a hash. We can't add it to a commit, since this by itself changes the hash (unless we would be happy to add a previous tag, which would be good enough ... or we would manually add 'something' in every time we merge).

[hiker]

I just found:

>>> import pkg_resources
<stdin>:1: DeprecationWarning: pkg_resources is deprecated as an API. See https://setuptools.pypa.io/en/latest/pkg_resources.html
>>> pkg_resources.get_distribution("fparser").version
'0.1.5.dev42+g5f24ee2'
>>> pkg_resources.get_distribution("psyclone").version
'2.5.0'

So doesn't really help, since I am on current master ... but thought to mention this, just in case :)

I am getting more and more the feeling that just adding -dev to master after a release would be easiest?

[arporter]

I am getting more and more the feeling that just adding -dev to master after a release would be easiest?

I'm inclined to agree with you. KISS. No additional dependencies. Just requires the reviewer of the first PR after a release to update the version 'number' in the two locations. (One of which is the doxygen config file.) Would @sergisiso and @TeranIvy be happy with this proposal?