Subject: [Netmod-ver-dt] A more flexible form of Semantic Versioning?

From: Robert Wilton <[email-masked]>
Date: Fri, 21 Sep 2018 15:05:31 +0100

One definition of semantic version is defined at https://semver.org/, 
which defines 11 rules using RFC 2119 language.

The rule for updating the major version number is rule 8:

8. Major version X (X.y.z | X > 0) MUST be incremented if any backwards 
incompatible changes are introduced to the public API. It MAY include 
minor and patch level changes. Patch and minor version MUST be reset to 
0 when major version is incremented.

This rule does not say that the Major version number can only ever be 
incremented if backwards incompatible changes have been made, although I 
believe that is the intent. But I'm wondering whether a valid 
interpretation of these semantic versioning rules would be to allow 
implementations to arbitrarily increase the Major version number even if 
no backwards incompatible changes have been made (e.g. they could 
increment the Major version number for every new major software release 
train, giving them the flexibility to introduce new backwards compatible 
changes to the YANG module in an older software release train if required).

Note, I'm not suggesting that everyone should always follow this 
approach, just wondering out loud if it is an option.  The downside is 
that a major version change conveys less information.  The upside is 
that it may reduce complexity for a common vendor deployment model, by 
avoiding a 4 tuple version number.

Thoughts?

Rob

---

From: Joe Clarke <[email-masked]>
Date: Fri, 21 Sep 2018 10:31:41 -0400

> avoiding a 4 tuple version number.

I think one could increment major arbitrarily.  However, this would
break an intent to use MAJOR as a hint to operators that they need to
inspect the module to understand what NBC changes have been made.

This goes back to tooling.  With the right tooling to identify changes,
then arbitrary bumps in MAJOR shouldn't matter.  But right now we don't
have tooling with 100% coverage.

Joe

---

From: "Sterne, Jason (Nokia - CA/Ottawa)" <[email-masked]>
Date: Fri, 21 Sep 2018 15:41:57 +0000

I've always thought that it would be acceptable (maybe not ideal, but acceptable) to bump the major this way. An increase in the major rev can mean >= 0 nbc changes.  When the major increments, tools will have to diff anyways. It is probably OK if that diff finds 5, 2, or 0 nbc changes.

It is much better to unnecessarily bump a major than to not bump a major when there has been an nbc change.

Jason

> -----Original Message-----
> From: Netmod-ver-dt <[email-masked]> On Behalf Of Joe
> Clarke
> Sent: Friday, September 21, 2018 10:32 AM
> To: Robert Wilton <rwilton=[email-masked]>; netmod-ver-
> [email-masked]
> Subject: Re: [Netmod-ver-dt] A more flexible form of Semantic Versioning?
> 
> _______________________________________________
> Netmod-ver-dt mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/netmod-ver-dt

---

From: Joe Clarke <[email-masked]>
Date: Fri, 21 Sep 2018 12:04:34 -0400

> I've always thought that it would be acceptable (maybe not ideal, but acceptable) to bump the major this way. An increase in the major rev can mean >= 0 nbc changes.  When the major increments, too…

That's my point: tools will have to diff.  But if the tool can't cover
changes like description/reference, then a human will have to look at
the module.  And if you're bumping MAJOR just because, that causes more
pain to the operator.

> It is much better to unnecessarily bump a major than to not bump a major when there has been an nbc change.

Of course.  But if there hasn't been an NBC change, it really shouldn't
be bumped.

Joe

---

From: "Sterne, Jason (Nokia - CA/Ottawa)" <[email-masked]>
Date: Fri, 21 Sep 2018 16:07:09 +0000

Ideally it wouldn't, but if we want to avoid a separate stream identified, and reuse the major rev as the stream ID, then vendors will need to bump it even when there isn't an nbc change sometimes.

> From: Joe Clarke <[email-masked]>
> Sent: Friday, September 21, 2018 12:05 PM
> To: Sterne, Jason (Nokia - CA/Ottawa) <[email-masked]>; Robert
> Wilton <[email-masked]>; [email-masked]
> > I've always thought that it would be acceptable (maybe not ideal, but
> acceptable) to bump the major this way. An increase in the major rev can
> mean >= 0 nbc changes.  When the major increments, tools will have to diff
> anyways. It is probably OK if that diff finds 5, 2, or 0 nbc changes.
> 
> >>> incremented if backwards incompatible changes have been made,
> although
> >> I

---

From: Robert Wilton <[email-masked]>
Date: Mon, 24 Sep 2018 11:27:35 +0100

So my aim here is to have a scheme that is flexible enough that it will 
work for all the main scenarios:

So, the proposal is to:
  (i) REQUIRE that the major version is updated whenever an nbc changes 
occurs (bugfixes tbd)
  (ii) RECOMMEND that the major version is only updated whenever an nbc 
change occurs.
  (iii) but MAY be incremented even if no nbc change has occurred.

Where the modules are versioned independently of the implementation, 
then I would expect that rules (i) and (ii) would be followed.

However, where the modules are versioned alongside major software 
version (e.g. Jason's example), then rules (i) and (iii) could be used.  
The key benefit here being that there is no need to introduce a 4 tuple 
version number.

The main cost of allowing rule (iii) seems to be:
  (a) Will the subtle change in semver semantics be confusing to users 
because the semver scheme is different from semver.org?  But possibly it 
will need to be slightly different anyway ...
  (b) It means that operators would have to check for nbc updates more 
often due to higher numbers of major version changes. However, only 
models that are using rules (i) and (iii) are impacted.

What mitigations are there for introducing rule (iii):
  (1) A diff tool already exists, although it may potentially generate 
unnecessary false positives (e.g. flagging an nbc change due to a benign 
description change).  However, this false positives could be reduced via 
annotation with an extension stmt that flags the change as not being nbc).
  (2) Even a nbc major version change doesn't mean that a client is 
necessarily impacted, it depends on the subset of the schema that they 
are actually using (again, more advanced diff tooling may help here).
  (3) I see the version number is really just forward guidance to the 
operators, even if they trusted it, they will test (and perhaps also 
diff the full schema) regardless because that is the only way to be sure 
that it will work.

It feels to me that the benefits of allowing this may outweigh the 
drawbacks.

Thanks,
Rob

On 21/09/2018 17:07, Sterne, Jason (Nokia - CA/Ottawa) wrote:
>> From: Joe Clarke<[email-masked]>
>> To: Sterne, Jason (Nokia - CA/Ottawa)<[email-masked]>; Robert
>> Wilton<[email-masked]>;[email-masked]
>>>> From: Netmod-ver-dt<[email-masked]>  On Behalf Of
>> Joe
>>>> Clarke
>>>> To: Robert Wilton<rwilton=[email-masked]>; netmod-ver-
>>>> [email-masked]
>>>>> One definition of semantic version is defined athttps://semver.org/,

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Mon, 24 Sep 2018 12:40:10 +0200

On Mon, Sep 24, 2018 at 11:27:35AM +0100, Robert Wilton wrote:
> So my aim here is to have a scheme that is flexible enough that it will work
> for all the main scenarios:
> 
> So, the proposal is to:
> Where the modules are versioned independently of the implementation, then I
> would expect that rules (i) and (ii) would be followed.
> 
> However, where the modules are versioned alongside major software version
> (e.g. Jason's example), then rules (i) and (iii) could be used.  The key
> benefit here being that there is no need to introduce a 4 tuple version
> number.

A 4 tuple version number is needed if we support nbc changes on
branches (aka streams). Yes, the rules above make this impossible but
then the real design decision being made here is hidden behind a
collection of RFC 2119 statements. I rather have this explicitely
said: nbc changes can only be made on the latest version.

>  (b) It means that operators would have to check for nbc updates more often
> due to higher numbers of major version changes. However, only models that
> are using rules (i) and (iii) are impacted.

It is a business decision; was Juniper not versioning by JunOS release?

> necessarily impacted, it depends on the subset of the schema that they are
> actually using (again, more advanced diff tooling may help here).
> operators, even if they trusted it, they will test (and perhaps also diff
> the full schema) regardless because that is the only way to be sure that it
> will work.
> 

I would even drop (ii) and (iii) and instead add text explaining the
pros and cons of different strategies in some guidelines section.

/js

-- 
Juergen Schoenwaelder           Jacobs University Bremen gGmbH
Phone: +49 421 200 3587         Campus Ring 1 | 28759 Bremen | Germany
Fax:   +49 421 200 3103         <https://www.jacobs-university.de/>

---

From: Robert Wilton <[email-masked]>
Date: Mon, 24 Sep 2018 15:56:33 +0100

> said: nbc changes can only be made on the latest version.
Ah yes. I wasn't trying to hide the design decision of disallowing nbc 
changes on branches.  Although having said that, my preference (putting 
aside bugfixes for the moment) is that nbc changes should only be 
allowed against the latest version.  This feels like a fair compromise 
between flexibility for the module designer, and impact on the client.

The scenario that I was specifically trying to allow for is backwards 
compatible module updates to be added to an already shipped major 
software release (since we make use of this). Allowing the module 
designer to automatically increment the module major version number for 
every major software release leaves the door open to allowing backwards 
compatible updates to older YANG modules.  Without this, module owners 
are limited by what they can do in an older software release train (e.g. 
for a module that already already has been updated in a backwards 
compatible way for the latest, potentially unreleased, software release).

> It is a business decision; was Juniper not versioning by JunOS release?
Yes, but I think that they were doing this by changing the namespace for 
each JunOS release which is arguably even more impactful that just 
changing a version number.

> pros and cons of different strategies in some guidelines section.
OK.  Putting aside the specific wording of the text, it sounds like in 
principle you might be OK with the idea of allowing the major version 
number to be incremented even if no changes have occurred. Is that right?

Thanks,
Rob

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Mon, 24 Sep 2018 17:50:23 +0200

> each JunOS release which is arguably even more impactful that just changing
> a version number.

If you know upfront that things are versioned this way, I am not sure
this approach is more impactful than having some other versioning
mechanism in place. Would be nice to know how well this work for
Juniper, they have years of experience...

/js