Use Semantic Versioning in your releases and downloadables

[jasongodev]

Good day authors, I'm one of the volunteers in a project called Scoop, a Windows package manager that allows downloading apps using the command line. We are like Chocolatey or APT.

There's a contributor who wanted to submit Tomboy in our package ecosystem. However we are having problems with your versioning system as it has an inconsistent pattern.

Take for example release version 0.36c. We normally expect that this version will have a file that has a 0.36c in its filename. But yours have 0.36b and 0.36e pattern in the exe file. And your other older releases also have weird letter versioning choices.

I can imagine in Semantic Versioning this could have been 0.0.36-rc3, denoting that your "c" version is a release 3. Then for each environment make it will have something like 0.0.36-rc3.exe for the regular exe file, and maybe 0.0.36-rc3+experimental.exe for exe files with more experimental features/flags turned on.

If we have a consistent versioning pattern, we will be able to index and update our JSON manifest for packaging. We will not guess which of the 0.36b.exe and 0.36e.exe is the real exe file of the 0.36c release.

I reference here my comments about this in the Scoop submission: ScoopInstaller/Extras#12208 (comment)

[davidbannon]

Hi Jason, thanks for your interest. Its not quite as simple as it may appear. All the betas I have in the 0.36 directory should, in reality, be in a 0.37 directory. But some package managers refuse to install what it thinks are earlier versions than currently installed. See -

dbannon@dell:~$ cat test3.txt 
tomboy-ng-setup-0.38+a-2.exeeeeee 
tomboy-ng-setup-0.38-a-2.exe

dbannon@dell:~$ cat test3.txt | sort --version-sort
tomboy-ng-setup-0.38+a-2.exeeeeee 
tomboy-ng-setup-0.38-a-2.exe

dbannon@dell:~$ cat test3.txt | sort
tomboy-ng-setup-0.38-a-2.exe
tomboy-ng-setup-0.38+a-2.exeeeeee

I think, based on https://www.man7.org/linux/man-pages/man7/deb-version.7.html that debian does a --version-sort. But only with extensive testing can I be sure. RPMs are not well documented, Packman and Apple I have not looked at yet. So, sorry, a blanket commitment to one definition of 'Semantic" is impracticable. Sigh...

Anyway, the situation right now ? The main release page does contain 0.36c releases but just for Linux. With Windows, the bug fixed by 'c' was not applicable. So, the one pointed to by https://github.com/tomboy-notes/tomboy-ng/wiki/Download_Release ('b') is correct. The directory also contains possibly d..g suffix beta releases as noted in the text.

My normal policy is to have just a numeric version on the actual release, however, some late found bugs and a upstream problem caused by Gnome made that difficult with 0.36. The text in the Release Page (not the Download_Release wiki page) defines d..g as being beta releases. The problem is that I release so many different packages now, the list is totally unmanageable. Thats why I have that wiki Download_Release page, its very human readable, generated by a script so easy for me too. But the result is not script able.

As that release directory only ever has one release (for each platform) and every numeric change is reflected in a new release directory, maybe a better approach (for me and you) is needed. How would this affect you (before I start that extensive testing) ?

• I always release only a numeric version number ? So, if I have a small bug fix I need to urgently add to eg 0.37, instead of calling it 0.37a, I will call it 0.38. The down side of this approach might be that sometimes, some platforms may have different release versions available from others.
• Beta (rc, alpha etc) will always be a lower case letter added to the numeric part. So, as at present, a beta release of 0.38 will be called 0.37a.
• Given the above, that 0.37a beta will appear in a release directory called 0.38 but will be marked as containing only betas until Release and then, all betas will be removed. You, as a packager, probably DO NOT want to take those beta 0.37a files even though they may appear more attractive than the 0.37 ones.

Now, to further complicate, the reason there is many betas appearing in 0.36c right now is I am warming up for a release, 0.37, I have an upstream (I think) problem with Debian Bookworm 32bit. If I can solve that, its otherwise ready to go. So, maybe its worth your while waiting a bit ?

If you want to run now, then grab the file https://github.com/tomboy-notes/tomboy-ng/releases/download/v0.36c/tomboy-ng-setup-0.36b.exe - its functionally, on Windows, identical to the 0.36c version on Linux and MacOS.

In terms of Scoop, new to me. I package (for windows) using quite an old version of the packaging tool. Another user has asked me about Windows WinGet and I am aware of the need to upgrade the Windows packaging. For the record, a tomboy-ng install does not write to the registary but does read it to try and determine if user prefers dark mode.

Phew ! Possibly a record length response.

David

[jasongodev]

In SemVer I can imagine the following versioning numbers that fits your case:

You start with 0.36.0 as your most stable release.

Any bug fix related to the core features and functionality will increment the version to 0.36.1, 0.36.2, and on wards.

All your operating system environment is denoted by the +build marker at the end of the version, so that you have something like 0.36.0+win.1, 0.36.0+deb.1, etc.

If you have bug fixes specific to an operating system but does not affect the core features, then 0.36.0+win.1 will become .36.0+win.2. Only the build numbers will change in this case. Note that any bug fixes that will also reflect in any other OS builds should instead increment that patch version altogether, making 0.36.1+win.1 and 0.36.1+deb.1, etc.

If you are experimenting on some beta features slated to be 0.37.0, then version it as 0.37.0-beta.1. If you discover something that worth backporting to 0.36 as a bug fix then increment the 0.36.0 patch to 0.36.1 and so on.

Having many betas will just create 0.37.0-beta.2, 0.37.0-beta.3, and so on. I also saw some packages using timestamps or dates to denote their build and beta releases. Something like 0.37.0-beta.20231120 then 0.37.0-beta.20231201, and so on.

Any how, for our use case in Scoop I will just elect them to use the most recent exe release that can be found in the GitHub endpoint, regardless of whatever version that is.

[davidbannon]

Jason, a few points -

1. You did not answer my (long winded) question, would my proposed solution better meet your needs ?
2. I clearly failed to get the important message across to you. I name my packages in such a way so I can work with four very different Linux Package Managers, with MacOS and (the easy one) Windows. Certain characters, eg '-', '_', '+' have specific meaning dependent on where in the filename they appear.
3. Please do not take the most recent exe file in the 0.36c release directory, its a risky beta.

If my proposed policy of not mixing betas and releases works for you, I will move to that model and you then could take the only exe file in a Release Dir but not until I restructure. For me, thats already necessary and is a manageble solution.

Your particular proposed SemVer would be fine in one specific environment but tomboy-ng is distributed to, at last count, over 10 platforms with many variations in each. It runs on everything between ppc64el to the Raspberry Pi. Its built by other people, without my input, and lives in source form on Debian and PPA. If I make a change to the basic naming scheme, I would need to test, or get tested on all those platforms, it would take months.

Importantly, a mistake in a naming scheme would cause a great deal of trouble. Someone may be unable to update with out deleting the original, people hate that because they worry about losing data.

Thats why I proposed a change to just here that I think will solve your problem. Please indicate if it will.

Sorry I am being dogmatic here Jason, but its important !

David

[jasongodev]

My apologies for not capturing the complete picture from the first reading. I now fully understand. Forget my suggestions and I believe your proposed solution will suffice:

If my proposed policy of not mixing betas and releases works for you, I will move to that model and you then could take the only exe file in a Release Dir but not until I restructure. For me, thats already necessary and is a manageble solution.

Our case at Scoop is not an urgent one. Just update us if things are ready on your side.

Thanks again!

[davidbannon]

OK Jason, the betas and Releases are now well separated. There is only one Windows .exe in Release, so easy.
Looks like my scripts were not removing updated Windows betas too, made it even more confusing. With so many files in there, too hard for me to see the duplication. I should have adopted this separate model long ago. Thanks for your input.

I expect to formally release v0.37 in a few weeks.

David