Version numbering

[jaakkojulin]

EDIT development merged to master:
This is more of an meta-issue, but the current development branch is the de facto master branch. If there are no good reasons and nobody opposes, I propose we merge development into master. That branch is more visible and easier to work with in GitHub. Creating new branches for larger refactoring or addressing issues is still strongly encouraged, but the master branch should reflect the latest possibly working version.

I also suggest we start version numbering roughly following semantic versioning by making the current version e.g. 2.1.0 indicating that there have been significant changes since the "2.0". This version number should appear in the UI and in binary packages.

I recommend bumping the patch level version at least whenever a new and curated binary package is made available and tagging the corresponding version in git. I suggest we tag versions with "v2.1.0" -style tags.

The use of tags also brings us extra functionality through releases.

Keeping a separate changelog might not be a bad idea either.

Any comments, ideas or suggestions?

[jussiks]

Sounds good. It is definitely an issue that the first branch that people see does not even have a decent ReadMe. 2.1.0 would be a logical current version number, I'm fairly confident that I have not yet broken backwards compatibility...

I believe all Python modules have a version field with value "2.0". Any preferences on how to update those? Edit every file en masse or gradually update them as changes are commited?

[jaakkojulin]

There is a deferred PEP about module version numbers, which brings up some of the issues with version numbering. Do the modules need to have a version number separate from the main version number?

Generic "2.0" is certainly bad and should be updated. My recommendation: no separate version numbers for modules, unless actually necessary or useful.

[samivout]

I've looked into implementing Potku's version numbering automatically with GitHub Actions and more specifically this action from GitHubs marketplace. Basically when a pull request is closed and merged into master, the action checks the merge commit message for tags #major, #minor, #patch or #none. The action then uses this message tag to determine the next semantic version number based on the repo's latest GitHub tag (if any exist). Finally the action adds a new lightweight GitHub tag using the newly incremented semantic version number. These can then be used as a basis for a release when desired.

The action has various environmental variables that can be used to adjust its behavior. Some examples:

• The message tags for incrementing the version number can be customized.
• Version numbering can either be done with or without a v prefix.
• The initial version number can be set to be other than 0.0.0.
• A default incrementing action can be determined if no message tags are in the merge commit message.

All in all this automatic version numbering method requires:

• All changes to master are done via pull requests (though can also be implemented to work on pushing to master).
• Allow all actions and reuseable workflows in the repo's settings under Actions -> General -> Actions permissions.
• Read and write permissions on the same page under Workflow permissions.
• Copy and possibly slightly modify the .yml script from the previously linked Github Tag Bump action and add it under .github/workflows/ as a .yml file.

In addition I'm thinking that it might be possible to make the script write the new version number into a file in the repo, so that Potku could then automatically use the new version number without having to manually change a harcoded number.

Could @jaakkojulin comment on this version numbering idea.

[jaakkojulin]

That does not sound too bad, but there might be some issues with this automatic numbering. Certainly it should not automatically increment anything (this can be configured, good).

I would prefer a solution that stores the version number in a file in the repository, like you were also thinking. For JIBAL and JaBS I decided to go with this solution:

I have a release script which, when run:

• checks that git working tree is clean
• suggests an automatic version number, allows user to override the suggestion
• generates version number file and CITATION.cff, these could probably also be done with git hooks when necessary
• adds the modified files to a commit, tags the commit but does not push (it would be super nice to have it generate a pull request, but I'm too lazy to implement that)

This solution also works well with archiving releases using Zenodo. The files in the repository guarantee a version number (and other metadata) if the source code is used outside git and GitHub.

Considering Potku is in Python, making a Python script that does that and having the developers run it would be quite straightforward? But I don't have anything against well working solutions, whatever they might be 😄.