Semantic versioning for Zephyr SDK

[stephanosio]

Preface

The versioning scheme used by Zephyr SDK is currently more or less arbitrary in the sense that there are no clearly defined rules dictating how the version number is incremented, which leads to various problems such as:

• inconsistent and potentially misleading version numbers
  • given the version number format A.B.C, there are no clear rules dictating when A, B and C are incremented, leaving this decision basically up to what the maintainer feels like.
  • e.g. SDK 0.15.2 and 0.16.0 may be used interchangeably while 0.14.2 and 0.15.0 may not.
• difficulty in discovering a compatible version of SDK from Zephyr build system
  • since the SDK versions are set without any rules based on compatibility/interchangeability, the Zephyr build system cannot determine if an SDK version is compatible with it without some form of discrete Zephyr version-to-SDK version compatibility matrix, which cannot exist for the future Zephyr SDK releases at the time of a Zephyr release.
  • for this reason, Zephyr build system simply looks for the latest version of Zephyr SDK which may not be compatible with the Zephyr version.

Adopt semantic versioning scheme that clearly defines what each version field means and when each version field is allowed to be incremented.

Implementation Plan

Given a version number MAJOR.MINOR.PATCH, increment the:

1. MAJOR version when you make major incompatible change(s) to multiple components that affect the overall user experience.
2. MINOR version when you make minor incompatible change(s) to one or more components that do not affect the overall user experience.
3. PATCH version when you make backwards compatible enhancements and bug fixes.

(loosely based on Semantic Version 2.0.0)

Examples of major incompatible changes

(to multiple components that affect the overall user experience)

• Change the distribution bundle format from self-extracting archive to tarballs with multiple host platform support.
• Change the toolchain triplet format from (arch)-zephyr-elf to (arch)-none-zephyr.

Examples of minor incompatible changes

(to one or more components that do not affect the overall user experience)

• Change ARC toolchain default thread pointer register from r26 to r25.
• Disable C99 format specifier support in newlib nano variant.

Zephyr Build System Integration

Zephyr build system currently selects the latest version of SDK among the detected SDK installations, which may lead to various build issues if the selected version of SDK is not compatible with the version of Zephyr.

With the proposed semantic versioning scheme, the Zephyr build system can select for the highest PATCH version that is under a specific MAJOR.MINOR version to avoid such compatibility issues, since any PATCH versions within a specific MAJOR.MINOR version are guaranteed to be backwards compatible.

Backports and Maintenance Releases

Zephyr releases often use the latest SDK version available and, with the proposed semantic versioning scheme and the subsequent Zephyr build system integration strategy, they will be tied to the latest MAJOR.MINOR version of SDK available at the time of their release.

Since a Zephyr release may be supported for up to two years and it is not feasible to introduce breaking changes to a dot (aka. PATCH) release of Zephyr (i.e. you cannot bump the required SDK version for dot releases of Zephyr), it is necessary to backport any relevant SDK bug fixes and provide maintenance PATCH releases for use with the previous Zephyr releases.

This will be implemented by creating the release branches for every MAJOR.MINOR release, backporting patches to them, and releasing maintenance MAJOR.MINOR.PATCH releases from the release branches.

[stephanosio]

cc @tejlmand @nashif

[tejlmand]

• e.g. SDK 0.15.2 and 0.16.0 may be used interchangeably while 0.14.2 and 0.15.0 may not.

Which is perfectly legal for semantic versioning, and one reason why Zephyr SDK is using major version 0.
Ref: https://semver.org/

4. Major version zero (0.y.z) is for initial development. Anything MAY change at any time. The public API SHOULD NOT be considered stable.

---

Adopt semantic versioning scheme that clearly defines what each version field means and when each version field is allowed to be incremented.

Actually we are following semantic versioning, and this has been discussed long time back and exactly one of the reasons why we are still at major version 0.

So probably this issue should not be about adopting semantic versioning cause we are already following that, see bullet 4. in semver.
This issue should be about what are the requirements to release a major version 1.

[stephanosio]

@tejlmand Did you read the proposal? Because, based on your response, it does not seem like you did.

p.s. also note that this proposal is loosely based on Semantic Versioning 2.0.0, and the MAJOR and MINOR version fields have different semantic.

[tejlmand]

@tejlmand Did you read the proposal?

I did, and to a large extent I agree to the path forward in order to define when to have a first major revision 1.

What I oppose is the indication in the preface that we are not following semantic versioning (or something which resembles it), when in fact we are currently conforming to the scheme because our major version is 0, which means there are no rules and we can basically do as we please (Note I strongly agree that we should improve on this and hence aim at having a major revision >=1).

[stephanosio]

What I oppose is the indication in the preface that we are not following semantic versioning (or something which resembles it), when in fact we are currently conforming to the scheme because our major version is 0, which means there are no rules and we can basically do as we please

That is one way to look at it; but, to say we are following the Semantic Versioning 2.0.0 specifications is stretching it a bit too far because, for all practical purposes, we are not.

According to Semantic Versioning 2.0.0, "Major version zero (0.y.z) is for initial development." Zephyr SDK is well beyond the "initial development" phase and we are currently using it in production; in that sense, we are NOT following the Semantic Versioning 2.0.0.

Also Semantic Versioning 2.0.0 is not the only form of "semantic versioning" out there and we do not intend to follow it as is, as described in this proposal, mainly because Zephyr SDK is, in many ways, dissimilar to conventional software libraries, which the Semantic Versioning 2.0.0 mainly targets.

[tejlmand]

According to Semantic Versioning 2.0.0, "Major version zero (0.y.z) is for initial development." Zephyr SDK is well beyond the "initial development" phase and we are currently using it in production; in that sense, we are NOT following the Semantic Versioning 2.0.0.

From an older Toolchain WG, back before we had Windows and macOS support:

Anas: Zephyr SDK is a reference, not a product

Now that we have gotten support on all major platforms, then I agree we should be moving to a major release 1, but I still think that before doing that, then best would be to have host tools support on all platform.

Toolchain on all platforms (Windows, macOS, Linux) were introduced in Zephyr SDK 0.14, march 2022.
Host tools are still only present on Linux release.

So imo it was not until 0.14 we could consider if we should move out of "initial development".
Whether or not host tools are a requirement for moving out of initial development is open for discussion, but I don't believe you can say: Zephyr SDK is well beyond the "initial development" phase

I guess it's for a project to decide what is considered initial development, not semantic versioning.
But I guess we are getting into semantics now 😉 my point was mainly that I disagreed with the indication that we just randomly chose a version number, when in fact there was a reason for being at major version 0.

[tejlmand]

Extra comment:

major incompatible change(s)
minor incompatible change(s)

how can an incompatible change be major or minor, if it's incompatible then it's incompatible, so I suggest removing major and minor in those sentences and instead make precise when we consider an incompatible change should warrant a major bump.

For example:

MAJOR version when you make incompatible change(s) to components in the toolchain or changes to host tools which affects the overall user experience.
MINOR version when you make incompatible change(s) to one or more components in non-mandatory extra components not required for building a project.

Example where a major bump is required are incompatible changes to gcc, ld, objcopy, and similar tools that are used for build, link and postprocessing.
Example where a minor bump is acceptable are incompatible changes to bossac, qemu, openocd.

That in my opinion remove the ambiguity on when an incompatible change is impacting enough users to warrant a major bump.
It still has a slight opening for discussions on when a change in for example qemu is allowed to bump major, but it makes it clearer when major must be bumped. That is when something related to building changes.

[stephanosio]

But I guess we are getting into semantics now my point was mainly that I disagreed with the indication that we just randomly chose a version number, when in fact there was a reason for being at major version 0.

Sure, all the nits aside, at least for the major version 0, I agree that was a conscious decision.

What this proposal mostly concerns, however, is to bring the "semantic versioning" to even 0.y.z versions, of which the y and z parts are currently more or less random, because we have been seeing various user experience-related problems related to this, as described in this issue, and we do need a solution, which this issue proposes.

Another option would be to wait until what we consider 1.y.z. (i.e. with host tools) comes and we start enforcing either the proposed or the de-facto standard semantic versioning scheme; but, that will take some time and we do not want the user experience issues to persist until then.

[stephanosio]

how can an incompatible change be major or minor, if it's incompatible then it's incompatible, so I suggest removing major and minor in those sentences and instead make precise when we consider an incompatible change should warrant a major bump.

I agree the current wording involving the "major" and "minor" incompatible changes for the conditions under which the MAJOR and MINOR version numbers must be bumped are rather vague and imprecise; but, the ambiguity is intentional -- the idea is to leave the details regarding the "major" version bump up to the discretion of the community and the SDK maintainer because:

• the "major" version number does not play any role in ensuring the discoverability of a compatible SDK version from the Zephyr build system
• it is only intended to be used as a rough indicator of how big of a change one can expect from a new release (hence, to be bumped upon a "major" incompatible change) -- relying on the maintainer's judgement would be better than pre-defined rules in this case.

In fact, we could very well do with just two version number fields -- i.e. MAJOR and MINOR in which a MAJOR bump indicates an incompatible change and a MINOR bump indicates a compatible change; but, the concern with that approach is that we could very well end up with the major version of 255 in the foreseeable future, which is not necessarily a bad thing but not very conventional and/or intuitive either.

Let us discuss this in the upcoming Toolchain WG meeting with a broader audience and try to find what works the best for us.

[tejlmand]

because we have been seeing various user experience-related problems related to this, as described in this issue, and we do need a solution, which this issue proposes.

and I agree very much to this, we should surely improve on this, irrespective of whether we are bumping to a 1.x release or sticking for some longer time to 0.x.
Note, nothing in semantic versioning forbids a 0.x release from adhering some self-imposed restrictions / rules so we are free to setup own guide-lines / rules.

but, the ambiguity is intentional -- the idea is to leave the details regarding the "major" version bump up to the discretion of the community and the SDK maintainer because

I prefer to be a bit more precise to avoid long discussions on whether or not a specific change is important enough / impacting sufficient amount of users to warrant a major bump. I'm concerned that being to vague here bears a risk of still experiencing various user-related problems.

Just because we start out with a more precise conditions on when to bump doesn't mean we can't adjust those based on later experiences and feedback / wishes of community and maintainer.

but, the concern with that approach is that we could very well end up with the major version of 255 in the foreseeable future

I'm not sharing that concern.
Based on the major following the description I proposed above I don't see why we should suddenly start changing major version so frequently.

Let us discuss this in the upcoming Toolchain WG meeting with a broader audience and try to find what works the best for us.

Agreed, and thanks for opening this rfc.
It's very valuable, and to me it mostly seems we are discussing details, meaning we share the intention on the overall proposal 👍

[stephanosio]

but, the concern with that approach is that we could very well end up with the major version of 255 in the foreseeable future

I'm not sharing that concern. Based on the major following the description I proposed above I don't see why we should suddenly start changing major version so frequently.

You forgot to quote the preceding condition: "In fact, we could very well do with just two version number fields" in which case the MAJOR bump would be done for both "major" and "minor" incompatible changes, which was an example I gave to point out that the x and y bump in the version number x.y.z based on the proposed versioning scheme are semantically equivalent and it was only the human perception of these numbers that motivated the x and y to be separate fields.

Example where a major bump is required are incompatible changes to gcc, ld, objcopy, and similar tools that are used for build, link and postprocessing. Example where a minor bump is acceptable are incompatible changes to bossac, qemu, openocd.

There are many problems with the above proposal (i.e. major bump for incompatible toolchain changes and minor bump for incompatible host tool changes):

• Does an architecture-specific (e.g. only affecting the SPARC architecture) incompatible GCC change really warrant a MAJOR bump?
• Does a QEMU update that breaks all supported architectures deserve only a MINOR bump?
• What about other changes not involving toolchain or host tools? For instance, a major change in the distribution format and/or the setup script that completely changes the OOB user experience?

In my opinion, the initial proposal does sufficiently lay out the basic and essential requirements for MAJOR and MINOR version bump without going into too much details so as to require the description of every permutation of the incompatible changes (which we would surely want to avoid):

Given a version number MAJOR.MINOR.PATCH, increment the:

1. MAJOR version when you make major incompatible change(s) to multiple components that affect the overall user experience.
2. MINOR version when you make minor incompatible change(s) to one or more components that do not affect the overall user experience.