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

From: "Sterne, Jason (Nokia - CA/Ottawa)" <[email-masked]>
Date: Thu, 23 May 2019 13:57:27 +0000

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.

(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.

(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.

Jason