FreeCAD versioning scheme and possible evolution

Have some feature requests, feedback, cool stuff to share, or want to know where FreeCAD is going? This is the place.
Forum rules
Be nice to others! Read the FreeCAD code of conduct!
triplus
Posts: 9278
Joined: Mon Dec 12, 2011 4:45 pm

FreeCAD versioning scheme and possible evolution

Post by triplus » Thu Feb 20, 2020 3:57 pm

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
Posts: 3349
Joined: Thu Oct 18, 2018 9:18 pm

Re: FreeCAD versioning scheme and possible evolution

Post by vocx » Thu Feb 20, 2020 5:11 pm

triplus wrote:
Thu Feb 20, 2020 3:57 pm
...
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.
triplus wrote:
Thu Feb 20, 2020 3:57 pm
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.
Last edited by vocx on Wed Mar 04, 2020 4:20 pm, edited 1 time in total.
Always add the important information to your posts if you need help.
To support the documentation effort, and code development, your donation is appreciated: paypal.
User avatar
kkremitzki
Posts: 1929
Joined: Thu Mar 03, 2016 9:52 pm
Location: Texas

Re: FreeCAD versioning scheme and possible evolution

Post by kkremitzki » Thu Feb 20, 2020 8:03 pm

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.
Like my FreeCAD work? I'd appreciate any level of support via Patreon, Liberapay, or PayPal! Read more about what I do at my blog.
User avatar
sgrogan
Posts: 5646
Joined: Wed Oct 22, 2014 5:02 pm

Re: FreeCAD versioning scheme and possible evolution

Post by sgrogan » Thu Feb 20, 2020 11:04 pm

triplus wrote:
Thu Feb 20, 2020 3:57 pm
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.
triplus wrote:
Thu Feb 20, 2020 3:57 pm
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
Site Admin
Posts: 15500
Joined: Thu Feb 19, 2009 10:32 am

Re: FreeCAD versioning scheme and possible evolution

Post by wmayer » Sat Feb 22, 2020 12:40 pm

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?
User avatar
bernd
Posts: 9324
Joined: Sun Sep 08, 2013 8:07 pm
Location: Zürich, Switzerland

Re: FreeCAD versioning scheme and possible evolution

Post by bernd » Sat Feb 22, 2020 2:21 pm

+ to wernwrs point, short numbers for release updates and commit numbers for dev builds.
vocx
Posts: 3349
Joined: Thu Oct 18, 2018 9:18 pm

Re: FreeCAD versioning scheme and possible evolution

Post by vocx » Sat Feb 22, 2020 3:46 pm

wmayer wrote:
Sat Feb 22, 2020 12:40 pm
...
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?
Last edited by vocx on Sat Feb 22, 2020 6:40 pm, edited 1 time in total.
Always add the important information to your posts if you need help.
To support the documentation effort, and code development, your donation is appreciated: paypal.
wmayer
Site Admin
Posts: 15500
Joined: Thu Feb 19, 2009 10:32 am

Re: FreeCAD versioning scheme and possible evolution

Post by wmayer » Sat Feb 22, 2020 3:54 pm

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
Posts: 9278
Joined: Mon Dec 12, 2011 4:45 pm

Re: FreeCAD versioning scheme and possible evolution

Post by triplus » Sat Feb 22, 2020 5:30 pm

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.
User avatar
kkremitzki
Posts: 1929
Joined: Thu Mar 03, 2016 9:52 pm
Location: Texas

Re: FreeCAD versioning scheme and possible evolution

Post by kkremitzki » Sat Feb 22, 2020 10:26 pm

wmayer wrote:
Sat Feb 22, 2020 12:40 pm
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/
Like my FreeCAD work? I'd appreciate any level of support via Patreon, Liberapay, or PayPal! Read more about what I do at my blog.
Post Reply

Who is online

Users browsing this forum: jmaustpc and 2 guests