Subject: [Netmod-ver-dt] version handling of YANG bugfixes

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

I regard a YANG module as acting as an API between client and server.

Looking at the semver rules (semver.org) then a bugfix to a YANG module 
would be regarded as an API change, and as such increment the version 
number in the following ways:
i) If the bugfix is non backwards compatible, then the major version 
number is incremented.
ii) If the bugfix is backwards compatible, but changes the semantics in 
any way, then the minor version number is incremented.
iii) If the bugfix has no change to semantics in any way (e.g. cosmetic 
change in a description statement), then the patch version number is 
incremented.

Conversely the rules in the clacla -06 draft (section 2.1.1) are a bit 
different:
a) x is the MAJOR version. It is incremented when the new version of the 
specification is incompatible with previous versions.
b) y is the MINOR version. It is incremented when new functionality is 
added in a manner that is backward-compatible with previous versions.
c) z is the PATCH version. It is incremented when bug fixes are made in 
a backward-compatible manner."

I have two thoughts on this:

1) I think the the semver.org definition of when to update the 
MINOR/PATCH version due to a bugfix is more consistent and better, 
because it means that it is always safe to go from module version A.B.C 
to version A.D.E, where (D > B) || (D == B && E > C).  If you follow the 
current clacla rules then I do think that this rule holds (i.e. software 
coded against A.B.C, where C > 0 could fail against version A.D.E, where 
D > B).

2) I think that we need to have some nuance on a what an "nbc bugfix 
is", and specifically on when it must be declared as a major version 
change.  I.e. we may want to allow some discretion on whether bugfixes 
are classified as nbc or not.  I think that there are cases where the 
strict YANG 1.1. upgrade rules might define a change as not being 
backwards compatible, but for all intents and purposes it is backwards 
compatible because nobody would be expected to use the invalid values 
(for example, the YANG description describes the correct behaviour, but 
there is a mistake in the 'pattern' or 'must' statement).

What are other folks thoughts on this?

Thanks,
Rob

---

From: "Reshad Rahman (rrahman)" <[email-masked]>
Date: Mon, 24 Sep 2018 13:03:28 +0000

Rob, can you explain the following on clacla rules? MINOR/PATCH can only be incremented when changes are backwards compatible (new functionality or bug fix). 

As for your comment in 2, I'm fine with what you're proposing, as long as the new rules are well defined.

Regards,
Reshad.

On 2018-09-24, 6:55 AM, "Netmod-ver-dt on behalf of Robert Wilton" <[email-masked] on behalf of rwilton=[email-masked]> wrote:

    

    

    Thanks,
    Rob
    
    _______________________________________________
    Netmod-ver-dt mailing list
    [email-masked]
    https://www.ietf.org/mailman/listinfo/netmod-ver-dt

---

From: Joe Clarke <[email-masked]>
Date: Mon, 24 Sep 2018 09:32:52 -0400

> a backward-compatible manner."

FYI, this was our intention.  The "bugfix" mentioned for PATCH was an
example meant to be something like a description or reference change
where semantics were not touched.

I agree, we could be clearer there.

> coded against A.B.C, where C > 0 could fail against version A.D.E, where

That was not our intention.

> there is a mistake in the 'pattern' or 'must' statement).

I would opt for a MAJOR bump in accordance to the rules you mentioned
above.  The reason being is that people may code around a bug, and
knowing that the semantics have changed (have been fixed) is useful.

Joe

---

From: Robert Wilton <[email-masked]>
Date: Mon, 24 Sep 2018 16:09:51 +0100

> I agree, we could be clearer there.
Ah, OK.  Good.

> knowing that the semantics have changed (have been fixed) is useful.
So I think that this is partly tied up with whether we need to allow 
bugfixes against older revisions.  If we use a 3 tuple semantic version 
number, and are strict on bumping major version numbers, then that may 
prevent obvious bugfixes in YANG modules for older releases that have 
already shipped.  Is it realistic to disallow this?

E.g. I'm thinking of the case where new backwards compatible 
functionality is added to an existing YANG module in an older release 
train.  It would be nice to be able to mark that functionality as beta 
(e.g. version < 0.X.Y for that added functionality), or to be able to 
apply obvious bug fixes to it if it doesn't quite work properly.  One 
solution is to put the new functionality into a separate module that 
allows it to be versioned independently, but that is quite a heavy 
handed approach.

Thanks,
Rob

> .

---

From: Joe Clarke <[email-masked]>
Date: Mon, 24 Sep 2018 12:42:13 -0400

>> That was not our intention.

I should add while that wasn't the intention, the propose "import-by"
semantics would allow for it.

> already shipped.  Is it realistic to disallow this?

No, it's not.  Vendors would do it anyway.

> allows it to be versioned independently, but that is quite a heavy

That does seem overly complicated and would likely not be employed too
often.

But we are now defining our own semantic rules independent from
semver.org.  We're now saying you can bump MAJOR when nothing changes,
and you can _not_ bump MAJOR when there's been an NBC change as long as
that change is a bugfix (for some value of bugfix).

This reemphasizes the need for tooling to capture this, since one can
not rely on the version to hint at changes.

Joe

---

From: "Sterne, Jason (Nokia - CA/Ottawa)" <[email-masked]>
Date: Tue, 25 Sep 2018 21:14:47 +0000

Does SemVer actually preclude bumping the major when no nbc changes have been made ?

I've been wondering the same thing as Rob for bug fixes to the YANG. Adding a "must" statement, for example, may just improve the documentation of a constraint that was *always there* in the server. No client could have ever violated the (missing) "must" statement because the server would have failed at commit time anyways.

Similarly for correcting a range that was incorrect in the YANG module. The server never would have accepted the invalid values (at least not at commit time).

I'm not necessarily advocating that we allow those changes without bumping the major rev, but it is probably worth a discussion.

Jason

> -----Original Message-----
> From: Netmod-ver-dt <[email-masked]> On Behalf Of Joe
> Clarke
> Sent: Monday, September 24, 2018 12:42 PM
> To: Robert Wilton <[email-masked]>; [email-masked]
> Subject: Re: [Netmod-ver-dt] version handling of YANG bugfixes
>

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Tue, 25 Sep 2018 23:39:22 +0200

Hi,

I think we discussed this before - at least I wrote about it. I
believe that a bug fix is unproblematic (i.e., not an nbc change) if
the original intention was clear to implementors. If, for example, you
have a leaf and it is clear from the description and the context that
it holds an IP address but you messed up the pattern of the type, then
you fix the pattern and move on. On the other hand, if you have a leaf
that represents an amount of type and the type and the description and
the unit statements disagree which units are used, then you simply
have something that is ambiguous and it will be difficult to label one
implementation as correct and another one as incorrect. Hence, to fix
the bug, you will have to introduce an nbc change.

Bottom line, bug fixes require human brains to decide whether the
original intention was clear for implementors from the context or not.
And in some cases, this will be a judgment call.

/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/>