[netmod] Limitations of semver

[Robert Wilton <[e-mail]>]

Although, we may like to think otherwise, I do not believe that semver 
is a silver bullet that will solve all YANG versioning problems.

Yes, it is popular and used, perhaps quite successfully, in lots of 
projects.  But there are many other large scale projects that have not 
adopted semver, e.g. 
https://gist.github.com/jashkenas/cbd2b088e20279ae2c8e states that none 
of the following properly use semver: Node doesn't follow SemVer, Rails 
doesn't do it, Python doesn't do it, Ruby doesn't do it, jQuery doesn't 
(really) do it, even npm doesn't follow SemVer.

The reason why I don't think that vanilla semver works for YANG is for 
two reasons:
(1) Semver is often used where API and implementation are versioned 
together (e.g. code libraries).  I.e. the "patch" field is semver is 
really about fixes to the implementation that do not change the API in 
anyway.  But a YANG module definition is really defining an API contract 
between client and server.
(2) Semver makes the assumption that all changes can be made to the head 
of the development branch, and that clients are able to relatively 
easily update to the latest version if required.  In fact, for an open 
source project it is a beneficial feature if you can force your clients 
to migrate to the latest API and code because there are less different 
versions to support.

But when applied to YANG modules there are two significant differences:
(1) The server implementations are not being versioned with the YANG 
API.  They may be multiple vendor products implementing the same YANG 
module, or there may be multiple products across multiple vendors 
implementing the same YANG module.  Asking a customer to move to the 
latest release to pick up a bug fix is not a realistic option, since the 
vendor/device may not even implement the latest version of the YANG 
module.  Also moving to the latest version of one particular YANG module 
could have cascading dependencies on other YANG modules.

(2) I would expect YANG modules, and the requirements to support them, 
to be much more long lived than open source projects that are using 
semver.  Where vendors are being paid to support software releases that 
have shipped with particular modules, customer have an expectation that 
they can get point fixes to those releases without being forced to 
update to major versions.

Hence, the proposal for modified semver.  Its aim is to be semver plus 
the minimal added changes to allow it to primarily support bug fixes 
(including nbc ones) to older releases.

The alternative, of using vanilla semver, looks similar to what we have 
today:
- vendors will increment the major version number for every release so 
that they they can increment the minor version number for bug fixes.
- or vendors will use deviations as a mechanism to get round where the 
API is wrong,
- or most likely, vendors will just fix the bug and increment the 
"patch" version number anyway breaking the semver rules, just as they 
ignore the YANG module updated rules today.

Perhaps this will all lead to the schema diff tool that I also like, if 
clients reach the point where they cannot trust the semver version 
numbers because it cannot actually encode the changes that are happening 
to the module.

As a vendor, I know that we have bug fixes going into older modules, Rob 
S indicated that OpenConfig does as well.  So, I think that the key 
question is whether we want the versioning scheme to be able to sensibly 
label bug fixes.  If we do, then I don't think that vanilla semver will 
meet the requirement.

Thanks,
Rob