Move to a more ordinary versioning scheme or document current scheme

[pmetzger]

calc currently uses a unique (or perhaps merely very unusual) four part version scheme. I've been using calc for many years and I'm not actually sure I know what the versions mean.

A three part version scheme (major.minor.patch, where major is incremented for incompatible changes or "big" changes, minor is incremented for feature additions, patch for pure bug fixes) or two part (where the first part is incremented when features are changed and the second part is incremented for bug fixes) would not require explanation to most users.

Failing that, it would be nice to get an explanation in the README and docs about what the version numbers mean.

The move to Calc 3 might be a good time for this.

[lcn2]

The README.RELEASE file documents the version system.

The command

; make release

Will also print this documentation.

We will reference this request in the TODO list under issue #103.

Thanks for the feedback. As this is part of the TODO for version 3, we will now close this issue with our thanks.

[Leif-W]

Just saw this. Wished to comment. A 4 part version is not uncommon, unique, or unusual in any way. Many software over the years have used 4 part versions. Even the CMake build system supports 4 parts documented as major[.minor[.patch[.tweak]]]. Many Windows exes and dlls also use 4 part versions. This is assumed common knowledge. The only unusual thing here is the ignorance to assume that there is only SEMVER with it's default 3-part version, despite SEMVER plainly allowing 4 part versions as compatible. Furthermore, before SEMVER made everyone as stupid as a computer, there used to commonly be word suffixed version schemes with their own numbers, such as 1.2.3-beta5, 3.2.1-gamma-7, 4.5.6alpha1, 6.5.4-pre1, or so on. You simply understood the Greek alphabet - alpha, beta, gamma, then pre, then release. There were also sometimes -daily or -nightly or unstable versions as well as platforms, sometimes. It wasn't as simple to parse as an integer logical comparison operator on the dotted parts, but was generally trivial to parse and compare. Why 4 parts? Sometimes it's desirable to differentiate between low priority bug fixes, and high priority security fixes. A set of bug fixes may not yet be ready to land and may be preempted by the need for a hotfix. Thus 4 parts allows additional nuance. There's no breaking changes thus no need to increment the 2nd minor number. I don't care if it's 3 or 4 parts or any other scheme. I just don't think it's correct to call 4 part versions unusual as the sole argument to pressure anyone to change to 3. I'm not a fan of SEMVER as trading nuance and intelligence for faux simplicity and stupidity gives a false sense of security. Although it can help as most system package manager systems seem unable to provide hooks for custom comparator functions.

[lcn2]

You made a number of good points, @Leif-W

Thanks 🙏 for sharing.

For calc version 3, we have a planning issue #103 where, in our analysis, a 3-level version is being considered.

The current model is that the top level version changes whenever the underlying object memory layout changes. Calc version 3 does involve a change to the way numbers are stored in memory (at the request of some with hardware acceleration support, BTW) so the top level version is changing from 2 to 3.

The second level version would change whenever new API interfaces such as new builtin functions are introduced. So, say after version 3 is released we wish to add a new builtin function called fizzbin().

There isn't a plan for a fizzbin() builtin function.  We are just making up an example. 

The release of the same memory model with a new API would have us change the version number to "3.1". Those with a dependency on memory layout (such as with those with hardware acceleration) would know that version "3.1" would NOT change the memory model. However folks would know that the API did change (due to the new builtin function called fizzbin()) because the 2nd version level changed. Someone with their own custom fizzbin() function might want to reconsider the custom function name and/or use of the new builtin function.

Then of course we have releases, bug fixes, documentation improvements, etc. Such would be released as "3.1.0", "3.1.1", "3.1.2", etc.

So our "promise", if you will, is that while calc remains at version 3, all 3.x.y releases will have compatible if not identical memory footprints/layouts.

And while calc remains at version "3.a", all 3.a.b releases will have the same API/builtin function name space.

Your point about the used of 4-level version systems, @Leif-W, is well taken. In our view, 4-level version systems have their advantages and uses.

However, calc might not need such 4-level versions system given the above "promises". We certainly could use 4-levels, but we don't see a compelling reason at this time. Issuing a new, for example, calc version 3.2.4 after version 3.2.3 would be for some bug fix or documentation improvement over version 3.2.3. Version 3.2.4 would have the same memory model and the same API as version 3.2.3.

That's our current thinking on future calc version numbers. We remain open to suggestions and feedback, as always is welcome 🙏.

UPDATE 0

Your point, @Leif-W, about high priority and low priority bug fixes is a good one.

Nevertheless calc might not need such a fine granularity on fixes to use a 4-level version system.

However, if we did find ourselves in need of such fix priorities, we could certainly change from a 3-level to 4-level if needed.