Prusaslicer: Better versioning scheme (and tags!)

[quasipedia]

Up until now (1.38.5) the project use a 3 number versioning scheme for releases which does not seem to follow any mainstream convention.

One of the most noticeable drawbacks is that essential information like the quality of the build (alpha/beta/RC) are hidden in the text description coming with the release, making difficult to follow the development, automate upgrades in a safe way and benefit from GitHub goodies that come in the API with semver tagging.

For example, the current last releases have been named:

• 1.37.2
• 1.38.2 (what happend to 1.38.0 and 1.38.1? Text says it is "alpha")
• 1.38.3 (beta)
• 1.38.4 (beta again, should have probably called "beta2", but it also introduces breaking changes, by bumping the number traditionally used for patch releases and new features!)
• 1.38.5 (a release candidate)

Possibly a more standard and informative sequence could have been:

• 1.37.2
• 1.38-alpha
• 1.38-beta
• 1.38-beta2
• 1.38-rc

or - if wishing to follow semver in a more pedantic way:

• 1.37.2
• 1.38-alpha
• 1.38-beta
• 1.39-beta
• 1.39-rc

That said - though - it is awesome to see how the project is proceeding steadfastly and how good the work being done is. Thank you a lot for contributing this to the 3D printing ecosystem! 💜 💜 💜

[bubnikv]

Hello Mac.

There is some reasoning behind our versioning system, though I admit there is always a room for improvement, and we are open for proposals.

The current version number (major, minor, revision) is picked from the label by the build system. We also produce continuous integration builds, where the version is extended with a fourth digit indicating number of commits since the last label. This scheme ensures tracability of the builds against the source code base, which is very important for bug tracking. I believe this system is sound and quite common. I don't quite agree with your proposal to reduce the version number to just major.minor for the alpha, beta and rc, but I agree that it would be cool to have the build status incorporated into the label. I will think about the implementation possibilities.

Do you have some examples of projects implementing the version numbering you proposed?

1.38.2 (what happend to 1.38.0 and 1.38.1? Text says it is "alpha")

The other builds were internal alphas, and because we use the same versioning internally AND externally, and we are producing many alpha builds before giving them to the public, there will naturally be gaps in the revision numbers. In many cases, the first internal alphas are major.minor.0.xx, so the first public alpha is major.minor.1. In the case of missing 1.38.1, I decided after placing the label that this version was not ready for public, but I did not want to mess with the build numbers already released internally (and the label published externally), so the first public alpha happend to be 1.38.2.

1.38-beta
1.39-beta

I agree that a "breaking change" should bump up the minor version, but on the other side that would trigger a flood of comments from our users: What happened with the 1.38 release? The world is not black and white.

Vojtech

[quasipedia]

Hi @bubnikv ! I never doubted there is some reasoning behind code tagging! :) I'm just saying that the reasoning is somewhat obscure (at least to me). :)

I don't quite agree with your proposal to reduce the version number to just major.minor for the alpha, beta and rc

Oh, that was not the meaning of the proposal. Other projects would use 1.38.0-beta instead of 1.38-beta. The main thing is though: if you are using semver (not perfect, but by far the most common versioning scheme and the one GitHub comes with "magic" out of the box), beta iterations substitute patch ones, as they serve the same purpose (fixing bugs). The thing is: an alpha or beta or RC in semver is not considered a proper "release" but rather a "prerelease". This is why projects that stick to it often offer two or three "channels" (regular releases, pre-releases, dev snapshots).

We also produce continuous integration builds, where the version is extended with a fourth digit indicating number of commits since the last label

In semver build metadata is relegated to the label coming after the patch number. Again: I'm not saying semver is perfect (you could go with romver if you wanted to, or even sentver, but semver is widespread and lots of tools are able to parse the tags out-of-the box.
Should you want to follow the standard, I know of two different practices:

1. Append a +<number> to the build (it is intuitive to know the order of builds then). An hypothetical example could be: 2.0.0-rc.2+1
2. Append the first digits of the git commit hash the build is based upon (not intuitive but makes build very repeatable). Again, hypothetical example: 2.0.0-beta.1+adb29a

Do you have some examples of projects implementing the version numbering you proposed?

Pretty much any project using git+semver, really. :)

• Atom by GitHub
• React by Facebook
• Angular by Google
• Typescript by Microsoft
• ...

I agree that a "breaking change" should bump up the minor version, but on the other side that would trigger a flood of comments from our users: What happened with the 1.38 release? The world is not black and white.

I'm not saying it is either! :) And this is why - while I like semver a lot - I do see it has its limits. Yet: there is value in following widely adopted standards, and you can always refer inquires to the documentation without having to engage in lengthy explanations. I'm unaware of what your pipeline is, but should you wish to give it a go, there are plenty of tools that can help automate tagging for you. One that I know of (but that I have no direct experience with is GitVer.

[bubnikv]

Thank you for all the information. I will look into it.

On Fri, Dec 22, 2017 at 11:06 AM, Mac Ryan [e-mail] wrote:

Hi @bubnikv https://github.com/bubnikv ! I never doubted there is some
reasoning behind code tagging! :) I'm just saying that the reasoning is
somewhat obscure (at least to me). :)

I don't quite agree with your proposal to reduce the version number to
just major.minor for the alpha, beta and rc

Oh, that was not the meaning of the proposal. Other projects would use
1.38.0-beta instead of 1.38-beta. The main thing is though: if you are
using semver (not perfect, but by far the most common versioning scheme and
the one GitHub comes with "magic" out of the box), beta iterations
substitute patch ones, as they serve the same purpose (fixing bugs). The
thing is: an alpha or beta or RC in semver is not considered a proper
"release" but rather a "prerelease". This is why projects that stick to it
often offer two or three "channels" (regular releases, pre-releases, dev
snapshots).

We also produce continuous integration builds, where the version is
extended with a fourth digit indicating number of commits since the last
label

In semver https://semver.org/ build metadata is relegated to the label
coming after the patch number. Again: I'm not saying semver is perfect (you
could go with romver
http://blog.legacyteam.info/2015/12/romver-romantic-versioning/ if you
wanted to, or even sentver http://sentimentalversioning.org/, but
semver is widespread and lots of tools are able to parse the tags
out-of-the box.
Should you want to follow the standard, I know of two different practices:

1. Append a + to the build (it is intuitive to know the order
   of builds then). An hypothetical example could be: 2.0.0-rc.2+1
2. Append the first digits of the git commit hash the build is based
   upon (not intuitive but makes build very repeatable). Again, hypothetical
   example: 2.0.0-beta.1+adb29a

Do you have some examples of projects implementing the version numbering
you proposed?

Pretty much any project using git+semver, really. :)

• Atom by GitHub https://github.com/atom/atom/tags
• React by Facebook https://github.com/facebook/react/tags
• Angular by Google https://github.com/angular/angular/tags
• Typescript by Microsoft
  https://github.com/Microsoft/TypeScript/tags
• ...

I agree that a "breaking change" should bump up the minor version, but on
the other side that would trigger a flood of comments from our users: What
happened with the 1.38 release? The world is not black and white.

I'm not saying it is either! :) And this is why - while I like semver a
lot - I do see it has its limits. Yet: there is value in following widely
adopted standards, and you can always refer inquires to the documentation
https://semver.org/ without having to engage in lengthy explanations.
I'm unaware of what your pipeline is, but should you wish to give it a go,
there are plenty of tools that can help automate tagging for you. One that
I know of (but that I have no direct experience with is GitVer
https://gitversion.readthedocs.io/en/latest/.

—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
https://github.com/prusa3d/Slic3r/issues/645#issuecomment-353565932, or mute
the thread
https://github.com/notifications/unsubscribe-auth/AFj5IynTXjsbP3q78r4-YWei1aMgQeCxks5tC383gaJpZM4RKjJ1
.

[bubnikv]

Thanks for all the hints. Our versioning scheme seems to be quite romantic, if not sentimental :-)

I think going forward with semver for the next release makes a lot of sense.

The thing is: an alpha or beta or RC in semver is not considered a proper "release" but rather a "prerelease". This is why projects that stick to it often offer two or three "channels" (regular releases, pre-releases, dev snapshots).

Would you please give me a hint to an example of the pre-release or dev snapshot channels? What is the recommended way of providing the change logs with these secondary channels? We are happily using the github release page, but I admit I don't like mixing the alpha, beta and release builds either. The four projects you mentioned before seem to publish the releases and betas, but not the alpha builds on the github release page.

[quasipedia]

I don't know what is the recommended way to do this nor if there exist a "github realease page way" to do this. I can only contribute by making some observations and examples "for inspiration purposes" 😄:

GitHub seems to be able to do a lot of magic by inferring information from semver tagging. For example, in the atom release page I believe the "prerelease" and "verified" labels as seen here

are computed by parsing the "beta" in the tag name and the gpg signature. This information is also available from the API and could be used in CI to for example upload a package to a specific rpm/deb repo (beta or regular). I believe this is exactly what atom is doing BTW, but they moved to repos very very recently. Previously they only used two different pages for a download of the latest release in each channel (regular and beta).

GitHub users should immediately spot the difference between stable and prerealise, but if you wanted to make the download more friendly for people not used to GH you could upload the AppImages to the prusa website as part of your CI job.

FreeCAD does some magic with their github release page. They have this 0.17_pre release from 14 Dec 2016 (so older than 1 year) that has fresh AppImages every night or so. I guess they may do some magic by simply uploading new assets? I am not sure.

Sorry I cannot help more, but I haven't used the release page on my repos much myself. :)

[bubnikv]

We have just released an alpha with the version_1.39.1-alpha
so I hope we follow the semver correctly :-)

I will update the build server to correctly insert the + sign after the label later. AFAIK then the semver will be implemented fully.

Thanks for your help and time indeed.

[bubnikv]

I think we are doing good now, so we can close this issue. Thanks for all the help.