Re: [Netmod-ver-dt] Comments on draft-verdt-netmod-yang-module-versioning.txt (May 16 version)

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

All looks good - thx.  I'm nervous about wording that says we "allow" NBC changes, but we do need to say it somewhere.  You seem to have good statements surrounding it to temper that statement.

jason

From: Rob Wilton (rwilton) <[e-mail]>
Sent: Tuesday, June 4, 2019 5:14 AM
To: Sterne, Jason (Nokia - CA/Ottawa) <[e-mail]>; [e-mail]
Subject: RE: Comments on draft-verdt-netmod-yang-module-versioning.txt (May 16 version)

Hi Jason,

I've attached the latest version of the doc, after applying the comments from Balazs's review.

Inline with [RW]

From: Netmod-ver-dt <[e-mail]<mailto:[e-mail]>> On Behalf Of Sterne, Jason (Nokia - CA/Ottawa)
Sent: 23 May 2019 14:57
To: [e-mail]<mailto:[e-mail]>
Subject: [Netmod-ver-dt] Comments on draft-verdt-netmod-yang-module-versioning.txt (May 16 version)

Hi guys,

Some comments on this file (May 16 version):
https://github.com/netmod-wg/yang-ver-dt/blob/develop/yang-mod-ver/draft-verdt-netmod-yang-module-versioning.txt

(A)
Replace this abstract:

   This document specifies a new YANG module update procedure to allow
   for limited non-backwards-compatible changes, as an alternative
   proposal to module update rules in the YANG 1.1 specifications.  This
document updates RFC 7950, RFC 8407 and RFC 8525.

with this (to avoid the implication that we are simply trying to "allow" NBC changes):

   This document specifies a method for documenting non-backwards-compatible changes that have occurred in a YANG module. Guidelines for managing the lifecycle of YANG modules are also provided. This document updates RFC 7950 (primarily the module update rules), RFC 8407 and RFC 8525.
[RW]
I've merged, and expanded this slightly.

What about the following text?

   This document specifies a new YANG module update procedure that can
   document when non-backwards-compatible changes have occurred during
   the evolution of a YANG module.  It provides a variant to the YANG
   import statement to better represent inter-module dependencies.  It
   provides help and guidelines for managing the lifecycle of YANG
   modules and individual schema nodes.  This document updates RFC 7950,
   RFC 8407 and RFC 8525.




(B)
replace this paragraph in section 1:

   Specifically, this document recognises a need to sometimes allow YANG
   modules to evolve with non-backwards-compatible changes, which could
cause breakage to clients and importing YANG modules.

with the following:

   Specifically, this document recognises a need to describe when a non-backwards-compatible (NBC) change has occurred in a YANG module [optional: in cases where the NBC change has been deemed necessary].  An NBC change can cause an incompatibility between a client using an older revision of the YANG module and a server using a newer revision.
[RW]
After updating with the comments from Balazs, the current text is:


   Specifically, this document recognises a need (within standards

   organizations, vendors, and the industry) to sometimes allow YANG

   modules to evolve with non-backwards-compatible changes, which could

   cause breakage to clients and importing YANG modules.  Accepting that

   non-backwards-compatible changes do sometimes occur, it is important

   to have mechanisms to report where these changes occur, and to manage

   their effect on clients and the broader YANG ecosystem.

I think that it is OK to say that NBC changes are sometimes allowed, specifically that is what our guidelines text currently states.  I agree that there may still be push back on this.


(C)
In section 2, remove the following sentence from its paragraph/bullet and separate it down into its own paragraph fully left justified.  It isn't really part of the list of 'updates' to RFC7950.  We're just reinforcing that a rule is still in place.

As per [RFC7950], YANG module revisions
      continue to be uniquely identified by the module's revision-date,
      and hence all revisions of a module MUST have unique revision
dates.
(D)
In section 2.1, replace this text:

   This section updates [RFC7950] chapter 11 to provide a more flexible
   approach that allows for some non-backwards-compatible changes during
   YANG module updates.

   Where pragmatic, updates to YANG modules SHOULD be backwards-
compatible, as described in Section 2.1.1.

with this (the guidelines can recommend to avoid NBC changes, and what we're changing here in this particular section doesn't really directly allow or support NBC changes anyways):

This section updates [RFC7950] chapter 11 to modify and clarify the definition of a non-backwards-compatible (NBC) change, and to allow a method of describing when an NBC change occurs in a YANG module.

(E)
section 2.1.2 -> change ' brekaage' to 'breakage'

I'm also not sure if the examples of NBC changes makes sense to include here. Especially the 2nd, 4th 5th and 6th bullets which are clearly described already in section 11 of RFC 7950.  Maybe just keep examples 1 & 3 and any others that are somewhat new based on our updates, or aren't terribly clear in section 11 of RFC 7950

That's as far as I've gotten for now.
[RW]
I've quite heavily reworked the initial parts of section 2.  Please can you check whether you think that these comments still apply with the current text:


2.  Refinements to YANG revision handling



   [RFC7950] assumes, but does not explicitly state, that the revision

   history for a YANG module is strictly linear, i.e., it is prohibited

   to have two independent revisions of a YANG module that are both

   directly derived from the same parent revision.



   This document clarifies [RFC7950] to explicitly allow non linear

   development of YANG module revisions, so modules MAY have multiple

   revisions that directly derive from the same parent revision.  As per

   [RFC7950], YANG module revisions continue to be uniquely identified

   by the module's revision-date, and hence all revisions of a module

   MUST have unique revision dates.



   [RFC7950] chapter 11 requires that all updates to a YANG module are

   backwards compatible to the previous revision of the module.  This

   document allows for more flexible evolution of YANG modules: Non-

   backwards-compatible changes between module revisions are allowed and

   are documented using a new 'nbc-changes' extension statement in the

   module revision history.



2.1.  Updating a YANG module with a new revision



   This section updates [RFC7950] chapter 11 to refine the rules for

   permissible changes when a new YANG module revision is created.



   Where pragmatic, updates to YANG modules SHOULD be backwards-

   compatible, following the definition in Section 2.1.1.



   A new module revision MAY contain non-backwards-compatible changes,

   i.e., the semantics of an existing definition MAY be changed in a

   non-backwards-compatible way without requiring a new definition with

   a new identifier.  A new module revision with non-backwards-

   compatible changes MUST include a 'rev:nbc-changes' extension

   substatement to signal the potential for incompatibility to existing

   module users and readers.



2.1.1.  Backwards-compatible changes



   The following statements update [RFC7950] chapter 11 to define what

   changes constitute an allowable backwards-compatible change to a YANG

   module:



   o  A "status" "deprecated" statement may be added, or changed from

      "current" to "deprecated", but adding or changing "status" to

      "obsolete" is not a backwards-compatible change.



   o  Obsolete definitions MAY be removed from published modules, and

      are classified as backwards-compatible changes.  In some

      circumstances it may be helpful to retain the obsolete definitions

      to ensure that their identifiers are not reused with a different

      meaning.



   o  In statements that have any data definition statements as

      substatements, those data definition substatements MAY be

      reordered, as long as they do not change the ordering or any 'rpc'

      'input' substatements.  If new data definition statements are

      added, they can be added anywhere in the sequence of existing

      substatements.



2.1.2.  Non-backwards-compatible changes



   Any changes to YANG modules that are not classified by Section 2.1.1

   as being backwards-compatible are classified as 'non-backwards-

   compatible' changes.



   One particular change to [RFC7950] chapter 11 is that adding or

   changing a 'status' state to 'obsolete' is classified as a non-

   backwards-compatible change, because it could break any clients

   relying on servers implementing the obsoleted data node.



2.2.  nbc-changes revision extension statement
...
Thanks,
Rob


Jason