Re: [netmod] yang versioning solution complexity and alternative approaches

["Sterne, Jason (Nokia - CA/Ottawa)" <[e-mail]>]

Hi all,

Just to close part of the loop on this topic:  In addition to the discussions below in this thread and other threads in the WG mailing list, we also had numerous discussions in our weekly calls on the top-level NBC indicator (at the module level) vs the per-node NBC indicators.

In the end, the set of folks on the weekly calls are proposing that:
1) the module level NBC extension is the primary basic mechanism for indicating NBC changes,
2) only the module level extension should be part of the base Module Versioning draft

One of the main reasons for this approach is to keep the base draft (Module Versioning) more simple and more likely to get wider adoption and use, while still meeting the basic requirement of signalling when an NBC change has occurred in a module.

The per-node extensions have been discussed and more clearly defined now. They are in the latest internal working copy of the Schema Comparison draft here (TBD if we move these to their own stand-alone draft):
yang-ver-dt/draft-ietf-netmod-yang-schema-comparision.txt at master · netmod-wg/yang-ver-dt (github.com)<https://github.com/netmod-wg/yang-ver-dt/blob/master/yang-schema-comparison/draft-ietf-netmod-yang-schema-comparision.txt>
In particular please take a look at the following sections:
3.2.  Node compatibility extension statements
7.  Module Versioning Extension YANG Modules (e.g. nbc-change-at)

Rgds,
Jason

From: netmod <[e-mail]> On Behalf Of Joe Clarke (jclarke)
Sent: Wednesday, June 8, 2022 5:03 PM
To: Andy Bierman <[e-mail]>; Jürgen Schönwälder <[e-mail]>; Rob Wilton (rwilton) <[e-mail]>; [e-mail]
Subject: Re: [netmod] yang versioning solution complexity and alternative approaches


On 6/8/22 13:29, Andy Bierman wrote:


On Wed, Jun 8, 2022 at 10:04 AM Jürgen Schönwälder <[e-mail]<mailto:[e-mail]>> wrote:
On Wed, Jun 08, 2022 at 04:40:05PM +0000, Rob Wilton (rwilton) wrote:
> >
> > Rob,
> >
> > discussing details is likely distracting from the main difference in
> > our viewpoints so I will only give a top posting response.
>
> Okay.
>
> I believe that the consensus of the authors on the weekly calls is also that annotations at the "data definition" level are helpful, alongside module and package (i.e., schema level) version numbers.
>
> Hence, my understanding of the main difference is whether non-backwards-compatible changes MUST always be explicitly documented at the data node level (and hence whether that means that data nodes can never be deleted from a YANG module), or whether these annotations are unnecessary, and potentially unhelpfully clutter the YANG module in the cases where tooling can robustly infer whether the change is backwards compatible or not.

For me, its a MUST. If you potentially break things, you have to tell
others. If you choose to violate the YANG 1.1 update rules, you have
to document that. Deleting data nodes (well, data nodes is actually
too limiting but that is likely a detail) is a special case and some
way to document that something was remvoed is indeed needed. I think
it is wrong to use a corner case to design the general case here.


Strongly agree with all of Juergen's concerns.
It is normal engineering practice to identify API changes
in the documentation for a specific API (not at some global level).

I agree that it is normal to reflect API changes.  Typically I see them in release notes.  In my experience, I have seen Java track certain data like "first introduced in" in classes and methods themselves.

There is also precedent for a global, API-level indication of NBC changes, and that is the REST API paradigm of a version component to the URI (e.g., /api/v2/RESOURCE).



The interactions between YANG modules are too complex for a "module-is-NBC"
flag to really help.

The packages work aims to address this interaction using the same labeling at more of a holistic API level.

Joe



IMO only NBC changes are a MUST. BC changes are a MAY.
These changes should not be documented in an extension that MAY be ignored.
The existing description-stmt is mandatory-to-implement for all tools.


Andy


If your YANG module gets cluttered because of NBC changes, perhaps
there is something to be said about the engineering process. To
unclutter a module, you give it a new new and remove the history.  I
do not believe that there is a robust algorithm to infer in the
general case whether a change in NBC or not, so it is pointless to
consider this option.

> Possibly there is also a second difference of opinion as to whether it is appropriate/safe to assume that any changes that are not explicitly marked as being non-backwards-compatible are in fact backwards compatible.  I.e., specifically, is a "backwards-compatible" annotation also required in the cases where a tool cannot safely infer that a change is backwards-compatible.

If NBC markers are a MUST, then everything not marked is a BC
change. In YANG 1.1, everything following the update rules is a BC
change, hence there are no markers. It seems logical to me to keep the
existing assumptions.

> Do you think that accurately represents the difference in opinion
> from your perspective?

There is another one concerning the implementation. If YANG is changed
in such a way that existing deployed tools derive wrong conclusions,
then this is an NBC change to YANG and the YANG version number needs
to be incremented.

/js

--
Jürgen Schönwälder              Jacobs University Bremen gGmbH
Phone: [phone]         Campus Ring 1 | 28759 Bremen | Germany
Fax:   [phone]         <https://www.jacobs-university.de/>

_______________________________________________
netmod mailing list
[e-mail]<mailto:[e-mail]>
https://www.ietf.org/mailman/listinfo/netmod