Subject: [Netmod-ver-dt] an abstract view on versioning

From: Juergen Schoenwaelder <[email-masked]>
Date: Thu, 24 May 2018 16:04:36 +0200

Hi,

here is an abstract view / historical view on versioning. If you
define something and you subsequently make semantic changes to it,
then you have two items that need to be distinguished.

In the old SNMP days, the name of an object was an OID. If you
had two semantically different definitions of something, you had
to use two different OIDs (names).

In the YANG days, the name of an object is a (module name, path)
tuple. If you have two semantically different definitions of
something, you have to change one of them, either keep the module name
choose a new path name or keep the path and choose a new module name.

It seems some peope now propose to move to triples where definitions
are defined by (module name, path, version) so that you can keep the
module name and the path stable. But of course, this requires to carry
an additional version number anywhere where it is needed, i.e.,
anywhere where currently a (module name, path) tuple is sufficient.

Obviously, we need to understand why a triple is significantly better
given that changes how we name things are affecting many parts of our
specifications.

/js (still waiting for webex to get going)

-- 
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: Fri, 25 May 2018 17:08:36 +0100

Hi Juergen, all,

> then you have two items that need to be distinguished.
I partly agree with this, but I'm not sure it should always apply:

(i) There are cases where you might want to change the definition, but 
not change the intended semantics (e.g. fix pattern, fix typo in the 
description), etc.  Although obviously this is not a semantic change :-)

(ii) There are cases where the existing semantics are invalid.  In these 
cases, it may be more pragmatic to 'fix' the existing definition, mostly 
safe in the knowledge that no-one can be using it.

(iii) vendors may decide that they want to make non backwards compatible 
changes for business reasons (e.g. it too difficult or expensive to 
support how it was being done before).  Clients can complain about this 
but ultimately they have to handle it.

> choose a new path name or keep the path and choose a new module name.
I see that this holds in theory, but I'm not convinced that it holds in 
practice:

- If a module is under development (e.g. in a draft), then paths and 
semantics can change.

- A given path may not exist in a older revision of a module, or perhaps 
it has been obsoleted in a newer module.  Hence validity of an object at 
least requires knowledge of the module revision.

- Vendors can deviate modules.  Hence different devices, or different 
s/w versions, may end up with different semantics for a particular 
object, which clients may be required to handle.

> given that changes how we name things are affecting many parts of our
So, I'm not necessarily advocating that a triple is always required in 
the mainline case, but I think that there are cases where a triple (or 
more fields) may be required for uniqueness.

But I think that the question that you raise concerning semantic 
versioning is valid:

- If there is a major version change then is a module designer allowed 
to completed rewrite a module?

Thanks,
Rob

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Fri, 25 May 2018 20:49:56 +0200

On Fri, May 25, 2018 at 05:08:36PM +0100, Robert Wilton wrote:
> (i) There are cases where you might want to change the definition, but not
> change the intended semantics (e.g. fix pattern, fix typo in the
> description), etc.?? Although obviously this is not a semantic change :-)

(i) does not apply to my statement since there is no semantic change
hence (i) irrelevant.
 
> (ii) There are cases where the existing semantics are invalid.?? In these

I think we have made bug fixes in the past. I do not think (ii) is
really relevant. (Although I acknowledge that sometimes the boundary
between bug fix and new definition is fuzzy.)

> changes for business reasons (e.g. it too difficult or expensive to support
> how it was being done before).?? Clients can complain about this but
> ultimately they have to handle it.

You still have to definitions. Are you saying that vendors have in
interest to make it impossible two distinguish the two semnatically
different definitions? (Or is it more a consequence of how versioning
is done in practice?) If a vendor has two definitions and does not
want to support one of them anymore, then this is just fine. There
still are two definitions.

> - If a module is under development (e.g. in a draft), then paths and

A module under development is not published. This is fine and irrelevant.

> - A given path may not exist in a older revision of a module, or perhaps it
> has been obsoleted in a newer module.?? Hence validity of an object at least
> requires knowledge of the module revision.

No. The entire (module, path) name always refers to the same published
definition. It never changes. You can built on the fact that it does
not change.

> - Vendors can deviate modules.?? Hence different devices, or different s/w
> versions, may end up with different semantics for a particular object, which
> clients may be required to handle.

Yes, but this does not change the underlying definition. The deviation
can actually rely on the definition being deviated to be always the
same.

> So, I'm not necessarily advocating that a triple is always required in the
> mainline case, but I think that there are cases where a triple (or more
> fields) may be required for uniqueness.

It will be required. Hence we can't simply ignore this (and then
discover this in 3-5 years from now).

> But I think that the question that you raise concerning semantic versioning
> is valid:
> 
> - If there is a major version change then is a module designer allowed to
> completed rewrite a module?

I believe you can't have any soft rules.

/js

---

From: Robert Wilton <[email-masked]>
Date: Wed, 30 May 2018 11:17:33 +0100

> between bug fix and new definition is fuzzy.)
OK, but this is a case where I think that the existing YANG update rules 
feel like they are too strict.

> different definitions?
No, vendors don't generally try and make the lives of their customers 
difficult.

>   (Or is it more a consequence of how versioning
> is done in practice?)
Yes.

I think that some vendors are struggling to follow YANG's strict update 
rules. E.g. perhaps the YANG modules are generated from an internal 
schema format.  If that internal schema changes, probably due to a bug 
fix or an enhancement, then the external schema can also end up changing.

I appreciate that vendors can do better here, but this is a tricky 
problem to solve.

>   If a vendor has two definitions and does not
Perhaps, but during the NDMA development many folks were complaining 
that it would cause too much churn to the draft modules, which are being 
implemented.

> definition. It never changes. You can built on the fact that it does
This isn't true.  According to 7950 sec 11, an updated revision is 
allowed to loosen the definition (e.g. expand range, remove when 
statements, etc), so there is no guarantee that the definition will be 
the same in different revisions.

E.g. if a server implements a newer revision of a module that adds a new 
enum value, then that server could return an enum value that a client 
implementing an older revision of the module does not understand.

> can actually rely on the definition being deviated to be always the
My point is that the clients already have to cope with deviated nodes.  
I.e. the (module-name, path) pair doesn't really uniquely define a data 
node.  It also depends on revision (as per above), and deviations.

> discover this in 3-5 years from now).
OK, I think that this should be discussed further.

> I believe you can't have any soft rules.
But I think that you state above that the rules for bugfixes are already 
fuzzy.

Thanks,
Rob

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Wed, 30 May 2018 12:50:12 +0200

On Wed, May 30, 2018 at 11:17:33AM +0100, Robert Wilton wrote:
> This isn't true.  According to 7950 sec 11, an updated revision is allowed
> to loosen the definition (e.g. expand range, remove when statements, etc),
> so there is no guarantee that the definition will be the same in different
> revisions.
> 

An old client configuring values will continue to work with a new
server. A server generating state data with values unknown to the
client should be tolerated by the client. It won't break configuration
though.
 
> My point is that the clients already have to cope with deviated nodes.  I.e.
> the (module-name, path) pair doesn't really uniquely define a data node.  It
> also depends on revision (as per above), and deviations.

The (module-name, path) pair uniquely identifies a data node. The
definition of the node may have been deviated but all of that is
defined and does not change the fact that the (module-name, path)
pair identifies uniquely a data node. (You do not get multiple data
nodes due to deviations.)

> OK, I think that this should be discussed further.

Take the move from Python 2.x.y to Python 3.x.y. And sometimes even
the difference in the middle number matters. Saying there is only
Python once you introduce an additional naming component is not
matching my experience.

> But I think that you state above that the rules for bugfixes are already

As far as I can recall, RFC 7590 does not talk about bug fixes
specifically. My understanding of section 11 (which may be wrong) is
that it applies to regular updates of a module, not to fixes of
bugs. Still, when fixing a bug, people should take into account
whether the fix can have side effects or may be more than a bug fix.

/js