FreeCAD versioning scheme and possible evolution

[triplus]

Note that this thread isn't all that much oriented towards discussion on what version number FreeCAD might use in the future. It is of a more technical nature, about FreeCAD version scheme. Currently FreeCAD is released annually, around April, and we do backporting, mostly for bug fixes. The problem therefore being, once we started doing backporting, some packagers expressed desires to use different version scheme, for such backport releases, closer to:

Code: Select all

FreeCAD 0.18.4

Instead of:

Code: Select all

FreeCAD 0.18.16146

And are now resulting to downstream packaging oriented workarounds and patches, to basically change number 16146 to 4. Current scheme therefore being:

Code: Select all

MAJOR = 0
MINOR = 18
PATCH = 16146

Some suggest we should start using semantic versioning:

https://semver.org

This would therefore translate to:

Code: Select all

MAJOR = 0
MINOR = 18
PATCH = 4

And there i guess would be an appendix with an hyphen added at the end, like -16147, to indicate a pre-release. Now i read about some pros and cons on the internet, on how others do it and perceive this versioning scheme, i read how Linux does it, and how they changed it a few times in the past ... But lets get back to FreeCAD. Lets say we wouldn't change things all that much and would do:

Code: Select all

MAJOR = 1
MINOR = 0
PATCH = XXXXX

Would this do for us or am i missing something? Backport releases would therefore bump the MINOR number and stable releases obviously would bump the MAJOR number. Do we need to fix any other problems?

P.S. I could be convinced otherwise and my mind is far from set, this is why i opened this thread. Currently i must say i am leaning towards the idea that semantic versioning puts way too much emphasis on the API, it's basically all about the API. FreeCAD being a general purpose and modular CAD framework, utilizing plethora of libraries out there for providing its functionality, used in multiple compile scenarios, i somehow feel that an API focused version scheme isn't best suited for us? In addition if we would use PATCH number for backport releases, what would we use MINOR number for?

[vocx]

...
Would this do for us or am i missing something? Backport releases would therefore bump the MINOR number and stable releases obviously would bump the MAJOR number...

I disagree with this. This is actually related to the next paragraph.

... Currently i must say i am leaning towards the idea that semantic versioning puts way too much emphasis on the API, it's basically all about the API...

Actually, my idea is that since FreeCAD can be used as a library, it should be treated as one. The programming interface is the most important part of it, and it's what gives stability to the whole project.

Modelling things with the mouse is of course possible, but once you understand how to use the programming interface, that's the key to unlocking the power of FreeCAD through scripts that automate modelling, and of course, writing external workbenches. Without a solid programming interface, this is not possible.

So, to me semantic versioning makes the most sense.

The future 1.0 should have a stable API that we can rely on. Precisely in my other thread, I would like to stabilize the API, before we think to even move to 1.0. So, each new yearly version would be 1.1, 1.2, 1.3, 1.4, etc. They would build on top of the stable API. If we decide to break compatibility, then we should move to 2.0.

We shouldn't bump the major number every year, because that would indicate an API incompatibility every year. Or we may end up with this situation, "version 1.0 and 2.0 are API compatible, then 3.0, 4.0, 5.0, 6.0, are API compatible, then 7.0 to 9.0 are API compatible, then...". It doesn't make much sense to me, and will become hard to manage once there are many versions.

To be API stable you have to think about all workbenches, not only about the core C++ functions, or those provided by the App:: namespace. Think about Path, Draft, Arch, FEM, Sketcher, TechDraw, Part, PartDesign, at least.

In addition if we would use PATCH number for backport releases, what would we use MINOR number for?

No. We would use MAJOR for major stable API releases. Then MINOR for updated releases (yearly), and PATCH for bug fixes.

This year's release could be 1.5. Then backported bug fixes would be 1.5.1, 1.5.2, 1.5.3. Next year's release would be 1.6. Then we make bug fixes to both releases, 1.5.4, and 1.6.1. Next year, a new version, 1.7. Bug fixes 1.5.5, 1.6.2, 1.7.1. Obviously, at some point we have to drop support for old versions.

[kkremitzki]

Commit numbers should not end up in final versions, frankly they're a pain in the ass for maintenance.

If I have a version number, say, 0.18.4, and someone says they have 0.18.2, I know there have been two bugfix releases since the version they're using. I know the one in between is 0.18.3. I know that there have been four bugfix releases for 0.18, so it's been maintained a while. The next bugfix version number will not be a new 5-digit number I need to carry around in my working memory, just 5.

Can you do me a favor and sort 19306, 10209, 19791, 16446, and 12568 real quick? What about 4, 2, 3, 5? Did you actually read all those 5-digit numbers or skim them as noise, and if they were important numbers but I had made a transcription error, would you have noticed?

The important difference between 0.18.16117 and 0.18.16146 is not that there were 29 commits, because without commit discipline the number of commits is not proportional to the magnitude of a change. The significant difference is that there were two sets of changes we felt important enough to do a bugfix release for.

Outside of a daily build/development context they are not very useful; it's easy to tell when one is bigger than the other, and it's easy to tell if you have a particular number that it doesn't include, say, the 19501st commit, etc., and it's easy to tell when there have been many changes in the development branch since your build. But besides that it's more harmful than helpful.

[sgrogan]

P.S. I could be convinced otherwise and my mind is far from set, this is why i opened this thread

I agree, I brought it up because it appears that most projects claim to be following this convention.

Currently i must say i am leaning towards the idea that semantic versioning puts way too much emphasis on the API, it's basically all about the API. FreeCAD being a general purpose and modular CAD framework, utilizing plethora of libraries out there for providing its functionality, used in multiple compile scenarios, i somehow feel that an API focused version scheme isn't best suited for us?

I agree with vocx because FreeCAD can be used as a library and is even licensed as such. I also agree that this will get complicated quickly so maybe it's not for FreeCAD.

I'll admit I'm warming to the year + update model, with an underlying version not necessarily exposed to the user. Something like FreeCAD 2021-Update1, which is 0.19.98765-PY3.8_QT5.14 under the hood. I could be convinced otherwise though.

[wmayer]

Can you do me a favor and sort 19306, 10209, 19791, 16446, and 12568 real quick? What about 4, 2, 3, 5? Did you actually read all those 5-digit numbers or skim them as noise, and if they were important numbers but I had made a transcription error, would you have noticed?

The important difference between 0.18.16117 and 0.18.16146 is not that there were 29 commits, because without commit discipline the number of commits is not proportional to the magnitude of a change. The significant difference is that there were two sets of changes we felt important enough to do a bugfix release for.

I agree on this with respect to stable releases. Actually the 16146 from your example is not the patch number but the build number.

But how should things behave for the daily versions, then? You need an increasing number and therefore IMO the best choice is still the build number. And how is the numbering scheme supposed to work when we make a development version a stable version?
For the current 0.19 development version we have 0.19.19697 and what number should it become when releasing the stable version? Wouldn't cause 0.19.0 for most package managers a problem because it's considered as an older version and thus won't be installed?

[bernd]

+ to wernwrs point, short numbers for release updates and commit numbers for dev builds.

[vocx]

...
For the current 0.19 development version we have 0.19.19697 and what number should it become when releasing the stable version? Wouldn't cause 0.19.0 for most package managers a problem because it's considered as an older version and thus won't be installed?

Maybe we could just use the third number as the first official release, and add a fourth just for development.

Code: Select all

0.19.0.19697  development
0.19.1        first official stable
0.19.1.20000  development
0.19.2        second official stable

Would that work?

[wmayer]

Would that work?

Yes, this should work. But we then still need a way how to handle that for development versions a fourth part is added to the version number and for a release we have only three. And also for a release the build number should be shown in the About dialog at least.

[triplus]

OK, therefore as there is only one of each:

Code: Select all

0.18.0
0.18.1
0.18.2

Commit number should be omitted everywhere or just in some specific places? Having an access to commit number from Python likely still does make sense? Number .1 and .2 ... hence indicating a back-port releases. As for the rest:

Code: Select all

0.18.0-XXXXX
0.18.1-YYYYY
0.18.2-ZZZZZ

Where an addition of commit number indicates a pre-relese. A pre-relese to a stable or a backport relese. Now as for the technical part. We likely have been camping in the MINOR release section a bit too long and it is really starting to show? For the sake of the argument, doing this:

Code: Select all

1.0
1.1
1.2

Mayor number representing a stable release and minor number representing a point releases. And therefore:

Code: Select all

1.0-XXXXX
1.1-YYYYY
1.2-ZZZZZ

An addition of commit number indicates a pre-relese.

That should be doable without any mayor changes to how we currently manage version scheme in the code (mayor, minor and patch)? We would need to figure out on how/when/where to set a "bit" to exclude commit number and the hyphen, though. Should this for example be done with a specific commit or to be set as a part of the build process itself. I am currently leaning towards the idea of using a specific git commit. Next commit, again unseting the bit and bumping mayor/minor number accordingly.

[kkremitzki]

I agree on this with respect to stable releases. Actually the 16146 from your example is not the patch number but the build number.

I just meant "patch" as in "major.minor.patch", i.e. the 3rd position, a.k.a "micro".

But how should things behave for the daily versions, then? You need an increasing number and therefore IMO the best choice is still the build number. And how is the numbering scheme supposed to work when we make a development version a stable version?
For the current 0.19 development version we have 0.19.19697 and what number should it become when releasing the stable version? Wouldn't cause 0.19.0 for most package managers a problem because it's considered as an older version and thus won't be installed?

Yes, the build number is fine to still include in daily builds. I was going to mention this but I didn't want my rant to get too long. 0.19.19697 should be 0.19~dev19697:

Code: Select all

>>> from packaging.version import parse
>>> parse('0.19') > parse('0.19~dev19697')
True
>>> parse('0.19.0') > parse('0.19~dev19697')
True
>>> parse('0.19~rc1') > parse('0.19~dev19697')
True
>>> parse('0.19') > parse('0.19~rc1')
True

Code: Select all

$ dpkg --compare-versions 0.19 gt 0.19~dev19697
$ echo $?
0
$ dpkg --compare-versions 0.19~rc1 gt 0.19~dev19697
$ echo $?
0
$ dpkg --compare-versions 0.19 gt 0.19~rc1
$ echo $?
0

If for example ~ causes problems on some platform we support, it's fine for Debian to use something else as we use this regex to mangle the upstream version into the Debian package version:

Code: Select all

uversionmangle=s/(\d)[_\.\-\+]?((RC|rc|pre|dev|beta|alpha|b|a)\d*)$/$1~$2/