Subject: [Netmod-ver-dt] Final updates to YANG module versioning draft?

From: "Rob Wilton (rwilton)" <[email-masked]>
Date: Sun, 10 Mar 2019 17:58:53 +0000

Hi all,

So, I think that I have made my final proposed updated to the draft before publishing tomorrow.   If you have minor trivial corrections that applying them directly might be best, or otherwise if you email me, I will commit them if I have time, although that is somewhat unlikely with the version selection draft still to write ...

A summary of the changes:

-        Markups from review comments

-        Fixed various references

-        Added example of YANG semantic version numbers, and reused the same example for the module and imports.  Possibly the example is slightly long and maybe could be condensed, but I was trying to illustrate all of the key points.

-        Hopefully fixed the semver definitions as we discussed in the meeting on Thursday

-        Heavily updated the section about updates to RFC 7950 rules to give a better description of how to classify modules based on their YANG statements.  Probably these section should be co-located into a subsection of chapter 2, but that will have to wait.

-        Applied some markups to the Guidelines section.  Please can you all (Reshad in particular) check that these changes are OK.

I've also been adding various issues to the Github issue tracker.  It would be good to try and go through these in Prague and knock off as many as we can.  I don't think that we should include all of these in our presentation to the NETMOD WG, probably just the most pertinent ones.
https://github.com/netmod-wg/yang-ver-dt/issues

I've attached the updated doc and diffs, but probably the commit notification is easiest to compare the diffs:

  Branch: refs/heads/develop

  Home:   https://github.com/netmod-wg/yang-ver-dt

  Commit: 5399283c5405937c6de86d95835b575677c4746f

      https://github.com/netmod-wg/yang-ver-dt/commit/5399283c5405937c6de86d95835b575677c4746f

  Author: rwilton <[email-masked]<mailto:[email-masked]>>

  Date:   2019-03-10 (Sun, 10 Mar 2019)

  Changed paths:

    M yang-semver/draft-verdt-netmod-yang-semver.txt

   M yang-semver/draft-verdt-netmod-yang-semver.xml

    M yang-semver/ietf-semver.yang

diff --git a/yang-semver/draft-verdt-netmod-yang-semver.txt b/yang-semver/draft-verdt-netmod-yang-semver.txt
index 5972a77..641ca00 100644
--- a/yang-semver/draft-verdt-netmod-yang-semver.txt
+++ b/yang-semver/draft-verdt-netmod-yang-semver.txt
@@ -6,14 +6,14 @@ Network Working Group                                          B. Claise
 Internet-Draft                                                 J. Clarke
 Updates: 7950 (if approved)                                    R. Rahman
 Intended status: Standards Track                          R. Wilton, Ed.
-Expires: September 8, 2019                           Cisco Systems, Inc.
+Expires: September 11, 2019                          Cisco Systems, Inc.
                                                               B. Lengyel
                                                                 Ericsson
                                                                J. Sterne
                                                                    Nokia
                                                               K. D'Souza
                                                                     AT&T
-                                                           March 7, 2019
+                                                          March 10, 2019

                   YANG Semantic Versioning for Modules
@@ -35,14 +35,14 @@ Status of This Memo
    Internet-Drafts are working documents of the Internet Engineering
    Task Force (IETF).  Note that other groups may also distribute
    working documents as Internet-Drafts.  The list of current Internet-
-   Drafts is at http://datatracker.ietf.org/drafts/current/.
+   Drafts is at https://datatracker.ietf.org/drafts/current/.
 
    Internet-Drafts are draft documents valid for a maximum of six months
    and may be updated, replaced, or obsoleted by other documents at any
    time.  It is inappropriate to use Internet-Drafts as reference
    material or to cite them other than as "work in progress."
 
-   This Internet-Draft will expire on September 8, 2019.
+   This Internet-Draft will expire on September 11, 2019.
 
 Copyright Notice
 
@@ -53,14 +53,14 @@ Copyright Notice

-Claise, et al.          Expires September 8, 2019               [Page 1]
+Claise, et al.         Expires September 11, 2019               [Page 1]
 
 Internet-Draft           YANG Module Versioning               March 2019

    This document is subject to BCP 78 and the IETF Trust's Legal
    Provisions Relating to IETF Documents
-   (http://trustee.ietf.org/license-info) in effect on the date of
+   (https://trustee.ietf.org/license-info) in effect on the date of
    publication of this document.  Please review these documents
    carefully, as they describe your rights and restrictions with respect
    to this document.  Code Components extracted from this document must
@@ -71,59 +71,63 @@ Internet-Draft           YANG Module Versioning               March 2019
 Table of Contents
 
    1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   3
-     1.1.  Changes to YANG RFCs  . . . . . . . . . . . . . . . . . .   4
-       1.1.1.  Changes to RFC7950  . . . . . . . . . . . . . . . . .   4
-       1.1.2.  Changes to RFC8525  . . . . . . . . . . . . . . . . .   4
-       1.1.3.  Changes to RFC8407  . . . . . . . . . . . . . . . . .   4
+     1.1.  Updates to YANG RFCs  . . . . . . . . . . . . . . . . . .   4
+       1.1.1.  Updates to RFC7950  . . . . . . . . . . . . . . . . .   4
+       1.1.2.  Updates to RFC8525  . . . . . . . . . . . . . . . . .   4
+       1.1.3.  Updates to RFC8407  . . . . . . . . . . . . . . . . .   5
      1.2.  Complementary solutions for the other requirements  . . .   5
-   2.  YANG Semantic Versioning  . . . . . . . . . . . . . . . . . .   5
+   2.  YANG Semantic Versioning  . . . . . . . . . . . . . . . . . .   6
      2.1.  Classification of changes between module revisions  . . .   6
-     2.2.  YANG Semantic Versioning Scheme for Modules . . . . . . .   6
-     2.3.  YANG Semantic Version Update Rules  . . . . . . . . . . .   8
-     2.4.  YANG Module Semver Extension  . . . . . . . . . . . . . .   9
-   3.  Import by Semantic Version  . . . . . . . . . . . . . . . . .  11
-     3.1.  Module import examples  . . . . . . . . . . . . . . . . .  12
-     3.2.  TODO  . . . . . . . . . . . . . . . . . . . . . . . . . .  13
-   4.  Updates to YANG 1.1 Module Update Rules . . . . . . . . . . .  13
-   5.  Updates to ietf-yang-library  . . . . . . . . . . . . . . . .  14
-     5.1.  Resolving ambiguous module imports  . . . . . . . . . . .  14
-     5.2.  Reporting how deprecated and obsolete nodes are handled .  15
-   6.  YANG status description extension . . . . . . . . . . . . . .  16
-   7.  Semantic versioning of YANG instance data . . . . . . . . . .  16
-   8.  Guidelines  . . . . . . . . . . . . . . . . . . . . . . . . .  17
-     8.1.  Guidelines to YANG model authors  . . . . . . . . . . . .  17
-       8.1.1.  Use of semantic versioning  . . . . . . . . . . . . .  17
+     2.2.  YANG Semantic Versioning Scheme for Modules . . . . . . .   7
+       2.2.1.  Examples for YANG semantic version numbers  . . . . .   8
+     2.3.  YANG Semantic Version Update Rules  . . . . . . . . . . .  10
+     2.4.  YANG Module Semver Extension  . . . . . . . . . . . . . .  11
+   3.  Import by Semantic Version  . . . . . . . . . . . . . . . . .  13
+     3.1.  Module import examples  . . . . . . . . . . . . . . . . .  15
+   4.  Classifying changes in YANG modules . . . . . . . . . . . . .  16
+     4.1.  Editorial changes . . . . . . . . . . . . . . . . . . . .  16
+     4.2.  Backwards-compatible changes  . . . . . . . . . . . . . .  16
+     4.3.  Non-backwards-compatible changes  . . . . . . . . . . . .  17
+   5.  Updates to ietf-yang-library  . . . . . . . . . . . . . . . .  17
+     5.1.  Advertising module version number . . . . . . . . . . . .  17
+     5.2.  Resolving ambiguous module imports  . . . . . . . . . . .  17
+     5.3.  Reporting how deprecated and obsolete nodes are handled .  18
+   6.  YANG status description extension . . . . . . . . . . . . . .  19
+   7.  Semantic versioning of YANG instance data . . . . . . . . . .  19
+   8.  Guidelines  . . . . . . . . . . . . . . . . . . . . . . . . .  20
+     8.1.  Guidelines to YANG model authors  . . . . . . . . . . . .  20
+       8.1.1.  Use of YANG semantic versioning . . . . . . . . . . .  20
        8.1.2.  Making non-backwards-compatible changes to a YANG
-               module  . . . . . . . . . . . . . . . . . . . . . . .  18
-         8.1.2.1.  Removing a data node  . . . . . . . . . . . . . .  20
-         8.1.2.2.  Changing the type of a leaf node  . . . . . . . .  20
-         8.1.2.3.  Reducing the range of a leaf node . . . . . . . .  21
-         8.1.2.4.  Changing the key of a list  . . . . . . . . . . .  21
-         8.1.2.5.  Renaming a node . . . . . . . . . . . . . . . . .  21
-         8.1.2.6.  Changing a default value  . . . . . . . . . . . .  21
-     8.2.  Guidelines to YANG model clients  . . . . . . . . . . . .  21
-   9.  Semantic Version Extension YANG Module  . . . . . . . . . . .  21
-   10. Contributors  . . . . . . . . . . . . . . . . . . . . . . . .  28
-   11. Security Considerations . . . . . . . . . . . . . . . . . . .  28
-   12. IANA Considerations . . . . . . . . . . . . . . . . . . . . .  29
-
-
-
-Claise, et al.          Expires September 8, 2019               [Page 2]
+               module  . . . . . . . . . . . . . . . . . . . . . . .  21
+         8.1.2.1.  Removing a data node  . . . . . . . . . . . . . .  22
+         8.1.2.2.  Changing the type of a leaf node  . . . . . . . .  23
+         8.1.2.3.  Reducing the range of a leaf node . . . . . . . .  23
+         8.1.2.4.  Changing the key of a list  . . . . . . . . . . .  23
+         8.1.2.5.  Renaming a node . . . . . . . . . . . . . . . . .  23
+         8.1.2.6.  Changing a default value  . . . . . . . . . . . .  23
+     8.2.  Guidelines to YANG model clients  . . . . . . . . . . . .  24
+
+
+
+Claise, et al.         Expires September 11, 2019               [Page 2]
 
 Internet-Draft           YANG Module Versioning               March 2019

-     12.1.  YANG Module Registrations  . . . . . . . . . . . . . . .  29
-   13. References  . . . . . . . . . . . . . . . . . . . . . . . . .  29
-     13.1.  Normative References . . . . . . . . . . . . . . . . . .  29
-     13.2.  Informative References . . . . . . . . . . . . . . . . .  30
-   Appendix A.  Appendix . . . . . . . . . . . . . . . . . . . . . .  30
-     A.1.  Open Issues . . . . . . . . . . . . . . . . . . . . . . .  31
-     A.2.  Derived Semantic Version  . . . . . . . . . . . . . . . .  31
-       A.2.1.  The Derived Semantic Version  . . . . . . . . . . . .  31
-       A.2.2.  Implementation Experience . . . . . . . . . . . . . .  31
-   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .  32
+   9.  Semantic Version Extension YANG Modules . . . . . . . . . . .  24
+   10. Contributors  . . . . . . . . . . . . . . . . . . . . . . . .  30
+   11. Security Considerations . . . . . . . . . . . . . . . . . . .  31
+   12. IANA Considerations . . . . . . . . . . . . . . . . . . . . .  31
+     12.1.  YANG Module Registrations  . . . . . . . . . . . . . . .  31
+   13. References  . . . . . . . . . . . . . . . . . . . . . . . . .  32
+     13.1.  Normative References . . . . . . . . . . . . . . . . . .  32
+     13.2.  Informative References . . . . . . . . . . . . . . . . .  32
+   Appendix A.  Appendix . . . . . . . . . . . . . . . . . . . . . .  34
+     A.1.  Open Issues . . . . . . . . . . . . . . . . . . . . . . .  34
+     A.2.  Derived Semantic Version  . . . . . . . . . . . . . . . .  35
+       A.2.1.  The Derived Semantic Version  . . . . . . . . . . . .  35
+       A.2.2.  Implementation Experience . . . . . . . . . . . . . .  35
+   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .  36
 
 1.  Introduction
 
@@ -137,7 +141,7 @@ Internet-Draft           YANG Module Versioning               March 2019
    end up breaking clients.  The solution makes use of semantic version
    numbers to help manage the lifecycle of YANG modules.
 
-   The solution is comprised of the following six parts:
+   The solution is comprised of the following seven parts:
 
       A definition for the YANG semantic versioning scheme for modules,
       and an explanation of how the semver extension can be used to
@@ -149,8 +153,7 @@ Internet-Draft           YANG Module Versioning               March 2019
       definitions.
 
       Updates to the YANG 1.1 module update rules to accommodate the
-      semantic versioning scheme and to provide more consistent handling
-      of changes to the YANG "status" statement.
+      semantic versioning scheme.
 
       Updates and augmentations to ietf-yang-library to include the YANG
       semantic version number in the module descriptions, to report how
@@ -158,35 +161,39 @@ Internet-Draft           YANG Module Versioning               March 2019
       clarify how module imports are resolved when multiple versions
       could otherwise be chosen.
 
-      A YANG extension to add a 'description' statement to the YANG
-      'status' statement to allow additional documentation as to why a
-      node is being deprecated, and what alternatives may be available.

 
-Claise, et al.          Expires September 8, 2019               [Page 3]
+Claise, et al.         Expires September 11, 2019               [Page 3]
 
 Internet-Draft           YANG Module Versioning               March 2019

+      A YANG extension to add a 'description' statement to the YANG
+      'status' statement to allow additional documentation as to why a
+      node is being deprecated, and what alternatives may be available.
+
+      A description of how YANG semantic versioning applies to YANG
+      instance data.
+
       Guidelines to YANG module authors on how the YANG semantic
       versioning rules should be used, along with examples.
 
-   Open issues are listed at Appendix A.1, and also tracked at
-   https://github.com/netmod-wg/yang-ver-dt/issues
+   Open issues are listed at Appendix A.1, and tracked at
+   <https://github.com/netmod-wg/yang-ver-dt/issues>.
 
-1.1.  Changes to YANG RFCs
+1.1.  Updates to YANG RFCs
 
-1.1.1.  Changes to RFC7950
+1.1.1.  Updates to RFC7950
 
    This document proposes updates to [RFC7950] to address some of the
    requirements.  It should be noted that there is also active WG
    discussion on the next steps towards an updated version of YANG, and
    potentially some of the functionality described here could be folded
-   into an updated revision of [RFC7950], although that it might
-   adversely impact when (parts of) a standards based YANG module
-   versioning solution is available for use.
+   into an updated revision of [RFC7950], although that might adversely
+   impact when (parts of) a standards based YANG module versioning
+   solution is available.
 
    The sections listed below provide updates to [RFC7950].  The design
    team does not believe any of the changes require a new version of the
@@ -202,30 +209,30 @@ Internet-Draft           YANG Module Versioning               March 2019
    o  Section 6 defines an extension that adds a description child
       element to the YANG "status" statement.
 
-1.1.2.  Changes to RFC8525
+1.1.2.  Updates to RFC8525
 
    This document updates [RFC8525].  Section 5 defines how a reader of a
    YANG library datastore schema chooses which version of an import-only
    module is used to resolve a module import when the definition is
    otherwise ambiguous.
 
-1.1.3.  Changes to RFC8407
 
-   Section 8 updates [RFC8407] to provide guidelines on how the YANG
-   module semantic versioning can be used to manage the lifecycle of
-   YANG modules when using strict RFC 7950 chapter 11 backwards
-   compatibility rules are not pragmatic.

 
-
-
-Claise, et al.          Expires September 8, 2019               [Page 4]
+Claise, et al.         Expires September 11, 2019               [Page 4]
 
 Internet-Draft           YANG Module Versioning               March 2019

+1.1.3.  Updates to RFC8407
+
+   Section 8 updates [RFC8407] to provide guidelines on how the YANG
+   module semantic versioning can be used to manage the lifecycle of
+   YANG modules when using strict RFC 7950 chapter 11 backwards
+   compatibility rules are not pragmatic.
+
 1.2.  Complementary solutions for the other requirements
 
    This section is to aid the WG understand how the full set of YANG
@@ -267,28 +274,27 @@ Internet-Draft           YANG Module Versioning               March 2019
    particular YANG datastore schema from the set of datastore schema
    that are supported by the server.
 
-2.  YANG Semantic Versioning
-
-   The chapter defines YANG Semantic Versioning, explains how it is used
-   with YANG modules, and the rules associated with changing a module's
-   semantic version number when the module definitions are updated.
-
-

-Claise, et al.          Expires September 8, 2019               [Page 5]
+Claise, et al.         Expires September 11, 2019               [Page 5]
 
 Internet-Draft           YANG Module Versioning               March 2019

+2.  YANG Semantic Versioning
+
+   The chapter defines YANG Semantic Versioning, explains how it is used
+   with YANG modules, and the rules associated with changing a module's
+   semantic version number when the module definitions are updated.
+
    The YANG semantic versioning scheme applies only to YANG modules.
    YANG submodules are not independently versioned by the YANG semantic
    versioning scheme.  Instead, if a versioned module includes one or
    more submodules then those submodules are implicitly versioned as
-   part of the module's 'semver:version' statements, and all 'include'
-   statements MUST specify the revision-date for each of the included
-   submodules.
+   part of the module's 'semver:version' statements, and all the
+   module's 'include' statements MUST specify the revision-date for each
+   of the included submodules.
 
 2.1.  Classification of changes between module revisions
 
@@ -300,8 +306,9 @@ Internet-Draft           YANG Module Versioning               March 2019
    The semantic version change between any two arbitrary revisions of a
    YANG module can be classified into one of four categories:
    'unchanged', 'editorial, 'backwards-compatible' or 'non-backwards-
-   compatible'.  The classification is performed by use of the following
-   rules:
+   compatible'.  A summary of the classification is given below, with
+   the specific rules as they apply to YANG statements provided in
+   Section 4.
 
       The semantic version change between two module revisions is
       defined as 'unchanged' if, after excluding 'revision' and
@@ -309,35 +316,37 @@ Internet-Draft           YANG Module Versioning               March 2019
       remaining changes are insignificant white space changes.
 
       An 'editorial' module semantic version change is where there are
-      changes in the module's statements, or statement ordering, between
-      the two module revisions, but those changes do not affect the
-      syntax or semantic meaning of the module in any way.  An example
-      of an editorial change would be a fix to a spelling mistake in a
-      description statement.
+      changes in the module's statements, between the two module
+      revisions, but those changes do not affect the syntax or semantic
+      meaning of the module in any way.  An example of an editorial
+      change would be a fix to a spelling mistake in a description
+      statement.
 
       A 'backwards-compatible' module semantic version change is where
       some syntax or semantic changes exists between the two module
       revisions, but all changes follow the rules specified in
-      Section 4.
+      Section 4.2.
 
       A 'non-backwards-compatible' module semantic version change is
       where some syntax or semantic changes exists between the two
-      module revisions, and those changes do not follow the rules
-      specified in Section 4.
-
-2.2.  YANG Semantic Versioning Scheme for Modules
 
-   This document defines the YANG semantic versioning scheme that is
-   used for YANG modules.  The versioning scheme has the following
-   properties:

-Claise, et al.          Expires September 8, 2019               [Page 6]
+Claise, et al.         Expires September 11, 2019               [Page 6]
 
 Internet-Draft           YANG Module Versioning               March 2019

+      module revisions, and those changes do not follow the rules for a
+      'backwards-compatible' version change.
+
+2.2.  YANG Semantic Versioning Scheme for Modules
+
+   This document defines the YANG semantic versioning scheme that is
+   used for YANG modules.  The versioning scheme has the following
+   properties:
+
       The YANG semantic versioning scheme is extended from version 2.0.0
       of the semantic versioning scheme defined at semver.org [semver]
       to cover the additional requirements for the management of YANG
@@ -358,7 +367,7 @@ Internet-Draft           YANG Module Versioning               March 2019
       semantic versioning scheme are exactly the same as those defined
       by the semver.org 2.0.0 versioning scheme.
 
-   Every YANG module versioned using a YANG semantic versioning scheme
+   Every YANG module versioned using the YANG semantic versioning scheme
    specifies the module's semantic version number by including the
    'semver:module-version' statement according to the following rules:
 
@@ -376,6 +385,15 @@ Internet-Draft           YANG Module Versioning               March 2019
       version' sub-statement if they have an associated YANG semantic
       version.
 
+
+
+
+
+Claise, et al.         Expires September 11, 2019               [Page 7]
+
+Internet-Draft           YANG Module Versioning               March 2019
+
+
    "The YANG semver version number is expressed as a string of the form:
    'X.Y.Zv'; where X, Y, and Z each represent non-negative integers
    smaller than 32768, and v represents an optional single character
@@ -385,20 +403,10 @@ Internet-Draft           YANG Module Versioning               March 2019
       indicate changes that are non-backwards-compatible to versions
       with a lower major version number.
 
-
-
-
-
-Claise, et al.          Expires September 8, 2019               [Page 7]
-
-Internet-Draft           YANG Module Versioning               March 2019
-
-
    o  'Y' is the MINOR version.  Changes in the minor version number
       indicate changes that are backwards-compatible to versions with
-      the same major version number, but a lower minor version number,
-      unless either version has a patch version with an 'm' or 'M'
-      modifier.
+      the same major version number, but a lower minor version number
+      and no patch 'm' or 'M' modifier.
 
    o  'Zv' is the PATCH version and modifier.  Changes in the patch
       version number can indicate editorial, backwards-compatible, or
@@ -413,18 +421,117 @@ Internet-Draft           YANG Module Versioning               March 2019
 
       *  'M' - the change represents a non-backwards-compatible change
 
-   YANG requires that if two modules have the same revision date then
-   they MUST have the same semantic content.  A similar constraint
-   applies for YANG semantic version numbers, i.e. two revisions of a
-   module that have the same semantic version numbers MUST have the same
-   semantic content.
+   The YANG module name and YANG semantic version number uniquely
+   identifies a revision of a module, with an associated revision date.
+   There MUST NOT be multiple instances of a YANG module definition with
+   the same module name and YANG semantic version number but different
+   content or revision date.
+
+   There MUST NOT be multiple versions of a YANG module that have the
+   same MAJOR, MINOR and PATCH version numbers, but different patch
+   modifier letter.  E.g., module version "1.2.3M" MUST NOT be defined
+   if module version "1.2.3" has already been defined.
+
+2.2.1.  Examples for YANG semantic version numbers
+
+   The following diagram and explanation illustrates how YANG semantic
+   version numbers work.
+
+
+
+
+
+
+
 
-   A module MUST NOT have multiple revision where the version string has
-   the same MAJOR, MINOR and PATCH version numbers, but different PATCH
-   modifier letter.  E.g., module version "1.2.3M" is not allowed if
-   module version "1.2.3" has already been defined.  Neither can there
-   be two different revisions of a YANG module with different content
-   but the same
+
+Claise, et al.         Expires September 11, 2019               [Page 8]
+
+Internet-Draft           YANG Module Versioning               March 2019
+
+
+   Example YANG semantic version numbers for an example module:
+
+           0.1.0
+             |
+           0.2.0
+             |
+           1.0.0
+             |  \
+             |   1.1.0 -> 1.1.1m -> 1.1.2M
+             |    |
+             |   1.2.0 -> 1.2.1M -> 1.2.2M
+             |    |
+             |   1.3.0 -> 1.3.1
+             |
+           2.0.0
+             |
+           3.0.0
+                \
+                 3.1.0
+
+   The tree diagram above illustrates how an example modules version
+   history might evolve.  For example, the tree might represent the
+   following changes, listed in chronological order from oldest revision
+   to newest:
+
+      0.1.0 - first beta module version
+
+      0.2.0 - second beta module version (with NBC changes)
+
+      1.0.0 - first release (may have NBC changes from 0.2.0)
+
+      1.1.0 - added new functionality, leaf "foo" (BC)
+
+      1.2.0 - added new functionality, leaf "baz" (BC)
+
+      1.3.0 - improve existing functionality, added leaf "foo-64" (BC)
+
+      1.3.1 - improve description wording for "foo-64" (Editorial)
+
+      1.1.1m - backport "foo-64" leaf to 1.1.x to avoid implementing
+      "baz" from 1.2.0 (BC)
+
+      2.0.0 - change existing model for performance reasons, e.g. re-key
+      list (NBC)
+
+      1.1.2M - NBC point bug fix, not required in 2.0.0 due to model
+      changes (NBC)
+
+
+
+
+Claise, et al.         Expires September 11, 2019               [Page 9]
+
+Internet-Draft           YANG Module Versioning               March 2019
+
+
+      3.0.0 - NBC bugfix, rename "baz" to "bar"; also add new BC leaf
+      "wibble"; (NBC)
+
+      1.2.1M - backport NBC fix, changing "baz" to "bar"
+
+      1.2.2M - backport "wibble".  This is a BC change but "M" modifier
+      is sticky.
+
+      3.1.0 - introduce new leaf "wobble" (BC)
+
+   The partial ordering relationships based on the semantic versioning
+   numbers can be defined as follows:
+
+      1.0.0 < 1.1.0 < 1.2.0 < 1.3.0 < 2.0.0 < 3.0.0 < 3.1.0
+
+      1.0.0 < 1.1.0 < 1.1.1m < 1.1.2M
+
+      1.0.0 < 1.1.0 < 1.2.0 < 1.2.1M < 1.2.2M
+
+   There is no ordering relationship between 1.1.1M and either 1.2.0 or
+   1.2.1M, except that they share the common ancestor of 1.1.0.
+
+   Looking at the version number alone, the module definition in 2.0.0
+   does not necessarily contain the contents of 1.3.0.  However, the
+   module revision history in 2.0.0 would likely indicate that it was
+   edited from module version 1.3.0.
 
 2.3.  YANG Semantic Version Update Rules
 
@@ -437,79 +544,80 @@ Internet-Draft           YANG Module Versioning               March 2019
 
    The first step is to classify the module change as 'editorial',
    'backwards-compatible', or 'non-backwards-compatible version' using
-   the rules defined in Section 2.1.
+   the rules defined in Section 2.1 and Section 4.
 
    The second step is to calculate the value of the 'semver:version'
    field for the new module revision, based on the value of the
+   'semver:version' field in the base module, any how the module changes
+   have been classified.
+
+   The following rules define how the value for the 'semver:version'
+   argument in the new module revision is calculated:

 
-Claise, et al.          Expires September 8, 2019               [Page 8]
+Claise, et al.         Expires September 11, 2019              [Page 10]
 
 Internet-Draft           YANG Module Versioning               March 2019

-   'semver:version' field in the base module, any how the module changes
-   have been classified.
+   1.  If a module is being updated in a non-backwards-compatible way,
+       then the module version "X.Y.Z[m|M]" MUST be updated to "X+1.0.0"
+       unless that module version has already been defined with
+       different content, in which case the module version "X.Y.Z+1M
+       MUST be used instead.
 
-   The following rules define how the value for the 'semver:version'
-   argument in the new module revision is calculated:
-
-      If a module is being updated in a non-backwards-compatible way,
-      then the module version "X.Y.Z[m|M]" MUST be updated to "X+1.0.0"
-      unless that module version has already been defined with different
-      content, in which case the module version "X.Y.Z+1M MUST be used
-      instead.
+   2.  If a module is being updated in a backwards-compatible way, then
+       the next version number depends on the format of the current
+       version number:
 
-      If a module is being updated in a backwards-compatible way, then
-      the next version number depends on the format of the current
-      version number:
+       i     "X.Y.Z" - the module version MUST be updated to "X.Y+1.0",
+             unless that module version has already been defined with
+             different content, when the module version MUST be updated
+             to "X.Y.Z+1m instead".
 
-         "X.Y.Z" - the module version MUST be updated to "X.Y+1.0",
-         unless that module version has already been defined with
-         different content, when the module version MUST be updated to
-         "X.Y.Z+1m instead".
+       ii    "X.Y.Zm" - the module version MUST be updated to
+             "X.Y.Z+1m".
 
-         "X.Y.Zm" - the module version MUST be updated to "X.Y.Z+1m".
+       iii   "X.Y.ZM" - the module version MUST be updated to
+             "X.Y.Z+1M".
 
-         "X.Y.ZM" - the module version MUST be updated to "X.Y.Z+1M".
+   3.  If a module is being updated in an editorial way, then the next
+       version number depends on the format of the current version
+       number:
 
-      If a module is being updated in an editorial way, then the next
-      version number depends on the format of the current version
-      number:
+       i     "X.Y.Z" - the module version MUST be updated to "X.Y.Z+1"
 
-         "X.Y.Z" - the module version MUST be updated to "X.Y.Z+1"
+       ii    "X.Y.Zm" - the module version MUST be updated to
+             "X.Y.Z+1m".
 
-         "X.Y.Zm" - the module version MUST be updated to "X.Y.Z+1m".
+       iii   "X.Y.ZM" - the module version MUST be updated to
+             "X.Y.Z+1M".
 
-         "X.Y.ZM" - the module version MUST be updated to "X.Y.Z+1M".
-
-      YANG module semantic version numbers beginning with 0, i.e "0.X.Y"
-      are regarded as beta definitions and need not follow the rules
-      above.  Either the MINOR or PATCH version numbers may be updated,
-      regardless of whether the changes are non-backwards-compatible,
-      backwards-compatible, or editorial.
+   4.  YANG module semantic version numbers beginning with 0, i.e
+       "0.X.Y" are regarded as beta definitions and need not follow the
+       rules above.  Either the MINOR or PATCH version numbers may be
+       updated, regardless of whether the changes are non-backwards-
+       compatible, backwards-compatible, or editorial.
 
 2.4.  YANG Module Semver Extension
 
    This document defines a YANG extension to add the YANG module
    semantic version to a Module.  The complete definition of this YANG
-   module is in section XXX.
-
+   module is in Section 9.
 
+           extension module-version {
+             argument semver;
+           }

-Claise, et al.          Expires September 8, 2019               [Page 9]
+Claise, et al.         Expires September 11, 2019              [Page 11]
 
 Internet-Draft           YANG Module Versioning               March 2019

-           extension module-version {
-               argument semver;
-           }
-
    The extension would typically be used this way:
 
        module yang-module-name {
@@ -522,46 +630,66 @@ Internet-Draft           YANG Module Versioning               March 2019
          description
            "to be completed";
 
+         revision 2018-02-28 {
+           description "Added leaf 'wobble'";
+           semver:module-version "3.1.0";
+         }
+
+         revision 2017-12-31 {
+           description "Rename 'baz' to 'bar', added leaf 'wibble'";
+           semver:module-version "3.0.0";
+         }
+
          revision 2017-10-30 {
-           description
-             "Change the module structure";
+           description "Change the module structure";
            semver:module-version "2.0.0";
          }
 
+         revision 2017-08-30 {
+           description "Clarified description of 'foo-64' leaf";
+           semver:module-version "1.3.1";
+         }
+
          revision 2017-07-30 {
-           description
-             "Added new feature XXX";
+           description "Added leaf foo-64";
+           semver:module-version "1.3.0";
+         }
+
+         revision 2017-04-20 {
+           description "Add new functionality, leaf 'baz'";
            semver:module-version "1.2.0";
          }
 
          revision 2017-04-03 {
-           description
-             "Update copyright notice.";
-           semver:module-version "1.0.1";
+           description "Add new functionality, leaf 'foo'";
+           semver:module-version "1.1.0";
          }
 
          revision 2017-04-03 {
-           description
-             "First release version.";
+
+
+
+Claise, et al.         Expires September 11, 2019              [Page 12]
+
+Internet-Draft           YANG Module Versioning               March 2019
+
+
+           description "First release version.";
            semver:module-version "1.0.0";
          }
 
+         revision 2017-01-30 {
+           description "NBC changes to initial revision";
+           semver:module-version "0.2.0";
+         }
+
          revision 2017-01-26 {
-           description
-             "Initial module for inet types";
+           description "Initial module version";
            semver:module-version "0.1.0";
          }
 
          //YANG module definition starts here
 
-
-
-
-Claise, et al.          Expires September 8, 2019              [Page 10]
-
-Internet-Draft           YANG Module Versioning               March 2019
-
-
    See also "Semantic Versioning and Structure for IETF Specifications"
    [I-D.claise-semver] for a mechanism to combine the semantic
    versioning, the GitHub tools, and a potential change to the IETF
@@ -592,11 +720,22 @@ Internet-Draft           YANG Module Versioning               March 2019
    imports if it is augmented by another module.
 
    The ietf-semver module defines the 'version' extension, a
-   substatement to the YANG 'import' statement.  An 'import' statement
-   may contain 'version' statements or a 'revision-date' statement, but
-   not both.  The 'version' statement may be specified multiple times,
-   requiring that the imported module version conforms to at least one
-   of the 'version' statements.
+   substatement to the YANG 'import' statement.
+
+
+
+
+Claise, et al.         Expires September 11, 2019              [Page 13]
+
+Internet-Draft           YANG Module Versioning               March 2019
+
+
+      An 'import' statement MAY contain 'version' statements or a
+      'revision-date' statement, but not both.
+
+      The 'version' statement MAY be specified multiple times, requiring
+      that the imported module version conforms to at least one of the
+      'version' statements.
 
    The argument to the 'version' statement takes one of three valid
    forms:
@@ -611,13 +750,6 @@ Internet-Draft           YANG Module Versioning               March 2019
        "X.Y.Z".  The word "MAX" can be used for 'Y' or 'Z' to represent
        the numerical value 32,767.
 
-
-
-Claise, et al.          Expires September 8, 2019              [Page 11]
-
-Internet-Draft           YANG Module Versioning               March 2019
-
-
    The rules for comparing module version numbers are as follows:
 
    1.  Version "R.S.T" matches version "A.B.C", only if
@@ -640,15 +772,26 @@ Internet-Draft           YANG Module Versioning               March 2019
 
           R < X
 
-   The patch modifier letter is not included as part of module 'version'
-   argument, and is entirely ignored for import statement module version
-   number comparisons.
+   The patch modifier letter is not included as part of the
+   'semver:version' argument, and is entirely ignored for import
+   statement module version number comparisons.
+
+
+
+
+
+
+Claise, et al.         Expires September 11, 2019              [Page 14]
+
+Internet-Draft           YANG Module Versioning               March 2019
+
 
 3.1.  Module import examples
 
    Consider an example module "example-module" that is hypothetically
-   available in the following versions: 0.1.0, 1.0.0, 1.1.0, 1.1.1m,
-   1.1.2M, 1.1.3M, 1.2.0, 2.0.0, 3.0.0.
+   available in the following versions: 0.1.0, 0.2.0, 1.0.0, 1.1.0,
+   1.1.1m, 1.1.2M, 1.2.0, 1.2.1M, 1.2.2M, 1.3.0, 1.3.1, 2.0.0, 3.0.0,
+   and 3.1.0.  E.g. matching the versions illustrated in Section 2.2.1.
 
    The first example selects the specific version 1.1.2M.  A specific
    version import might be used if 1.1.2M contained changes that are
@@ -659,36 +802,30 @@ Internet-Draft           YANG Module Versioning               March 2019
    }
 
    The next example selects module versions that match, or are greater
-   than, version 1.1.0.  This form may be used if there is a dependency
-   on a data node introduced in version 1.1.0.  This is expected to be
+   than, version 1.2.0.  This form may be used if there is a dependency
+   on a data node introduced in version 1.2.0.  This is expected to be
    the most commonly used form of 'import by version'.
 
-   Includes versions: 1.1.0, 1.1.1m, 1.1.2M, 1.1.3M, 1.2.0, 2.0.0 and
-   3.0.0.
-
-
-
-
-Claise, et al.          Expires September 8, 2019              [Page 12]
-
-Internet-Draft           YANG Module Versioning               March 2019
-
+   Includes versions: 1.2.0, 1.2.1M, 1.2.2M, 1.3.0, 1.3.1, 2.0.0, 3.0.0
+   and 3.1.0.
 
    import example-module {
-     semver:version 1.1.0+;
+     semver:version 1.2.0+;
    }
 
    The next example selects module versions that match, or are greater
-   than 1.1.0, but excluding the 1.1.2M and 1.1.3M versions.  This form
-   may be needed if structural non backwards compatible changes are
+   than 1.1.0, but excluding all 1.1.x and 1.2.x 'M' versions.  This
+   form may be needed if structural non backwards compatible changes are
    introduced in a patch 'M' version.  Generally, it is advisable to
    avoid making such changes.
 
-   Includes versions: 1.0.0, 1.1.0, 1.1.1m, 1.2.0, 2.0.0 and 3.0.0.
+   Includes versions: 1.1.0, 1.1.1m, 1.2.0, 1.3.0, 1.3.1, 2.0.0, 3.0.0,
+   and 3.1.0.
 
    import example-module {
-     semver:version 1.0.0-1.1.1;
-     semver:version 1.2.0+;
+     semver:version 1.1.0-1.1.1;
+     semver:version 1.2.0;
+     semver:version 1.3.0+;
    }
 
    The last example selects all module versions with a major version
@@ -696,71 +833,111 @@ Internet-Draft           YANG Module Versioning               March 2019
    compatible changes have been introduced in version 2.0.0 that break
    import backwards compatibility.
 
-   Includes versions: 1.0.0, 1.1.0, 1.1.1m, 1.1.2M, 1.1.3M, 1.2.0.
+
+
+
+
+Claise, et al.         Expires September 11, 2019              [Page 15]
+
+Internet-Draft           YANG Module Versioning               March 2019
+
+
+   Includes versions: 1.0.0, 1.1.0, 1.1.1m, 1.1.2M, 1.2.0, 1.2.1M,
+   1.2.2M, 1.3.0 and 1.3.1.
 
    import example-module {
      semver:version 1.0.0-1.MAX.MAX;
    }
 
-3.2.  TODO
+4.  Classifying changes in YANG modules
+
+   [RFC7950] chapter 11 defines the rules for what constitutes a
+   backwards compatible change in YANG 1.1.  However, the YANG semantic
+   versioning scheme defined in this document uses a slightly modified
+   version of this scheme, and also provides rules to classify changes
+   as editorial, backwards-compatible, or non-backwards-compatible.
+
+4.1.  Editorial changes
+
+   Any changes that do not change the ordering or meaning of the YANG
+   module in any way are classified as 'editorial'.  The following rules
+   define 'editorial':
 
-   TODO - Add text like this to the guidelines.  The import statement
-   SHOULD include a semver:import-versions statement and MUST NOT
-   include a revision statement.  An import statement MUST NOT contain
-   both a semver:import-versions and a revision substatement.  The use
-   of the revision substatement for import should be discouraged.
+   o  Changing any 'description' statement if it does not change the
+      semantic meaning of the statement is relates to.  E.g., fixing
+      spelling or grammar, or changing layout, are all allowed.
 
-   TODO - Perhaps guidance text should also warn about making nbc
-   changes that could break imports.  E.g. this could be an example of
-   where making something obsolete might be better than removing it.
+   o  Adding or updating 'reference' statements.
 
-4.  Updates to YANG 1.1 Module Update Rules
+   o  Adding or updating the 'organization' statement.
 
-   TODO - This section should just specify what the rules are
+   o  Adding a new 'revision' or 'semver:module-version' statement, or
+      correcting a previous 'revision' or 'semver:module-version'
+      statement.
 
-   RFC 7950 section 11, must be updated to allow for non-backward
-   changes provided they follow the semantic versioning guidelines and
-   increase the MAJOR version number when a backward incompatible change
-   is made.  This change is in the spirit of requirement 5.1 from
+   o  A module may be split into a set of submodules or a submodule may
+      be removed, provided the definitions in the module do not change
+      except in the ways described above.
 
+4.2.  Backwards-compatible changes
 
+   [RFC7950] chapter 11 defines the rules for what constitutes a
+   backwards-compatible change in YANG 1.1.  The document update these
+   rules in the following ways:
 
-Claise, et al.          Expires September 8, 2019              [Page 13]
+   o  Adding or changing a 'status' node to 'obsolete' is not a
+      backwards-compatible change.  Other changes/additions of status
+      elements are backwards-compatible, as per [RFC7950].
+
+
+
+
+
+Claise, et al.         Expires September 11, 2019              [Page 16]
 
 Internet-Draft           YANG Module Versioning               March 2019

-   [I-D.verdt-netmod-yang-versioning-reqs].  The following is proposed
-   text for this change.
+   o  Changing the ordering of statements is allowed if it does not
+      chanage the ordering of an rpc's 'input' substatements.
+
+4.3.  Non-backwards-compatible changes
+
+   All other changes to YANG modules that are not classified as
+   'editorial' or 'backwards-compatible' are defined as being non-
+   backwards-compatible.
+
+   Examples of non-backwards-compatible changes include:
+
+   o  Deleting a data node, or changing it to status obsolete.
 
-   "As experience is gained with a module, it may be desirable to revise
-   that module.  Changes to published modules are allowed, even if they
-   have some potential to cause interoperability problems, if the
-   module-version YANG extension is used in the revision statement to
-   clearly indicate the nature of the change."
+   o  Changing the name, type, or units of a data node.
 
-   TODO - Specify that changing status to "deprecated" is an BC change,
-   and changing status to "obsolete" is an NBC change".
+   o  Modifying the description in a way that changes the semantic
+      meaning of the data node.
 
-   A 'backwards-compatible' module semantic version change is where some
-   syntax or semantic changes exists between the two module revisions,
-   but all changes follow the rules specified in Section 4 of "Updating
-   a Module" of [RFC7950], except that no elements have been changed to
-   status 'obsolete', and re-ordering of statements is allowed.
+   o  Any changes that change or reduce the allowed value set of the
+      data node, either through changes in the type definition, or the
+      addition or changes to 'must' statements, or changes in the
+      description.
 
-   Q: Should revision-date history and semantic version be excluded from
-   the comparison?  RW: I've assumed yes.
+   o  Adding or modifying 'when' statements that reduce when the data
+      node is available in the schema.
+
+   o  Making the statement conditional on if-feature.
 
 5.  Updates to ietf-yang-library
 
    YANG library [RFC7895] [RFC8525] is modified to support semantic
    versioning in three ways.
 
+5.1.  Advertising module version number
+
    The ietf-semver YANG module augments the 'module' list in ietf-yang-
    library with a 'version' leaf to optionally declare the YANG semantic
    version of each module.
 
-5.1.  Resolving ambiguous module imports
+5.2.  Resolving ambiguous module imports
 
    A YANG datastore schema, defined in [RFC8525], can specify multiple
    revisions of a YANG module in the schema using the 'import-only'
@@ -769,6 +946,14 @@ Internet-Draft           YANG Module Versioning               March 2019
 
    If a YANG module import statement does not specify a specific version
    or revision within the datastore schema then it could be ambigous as
+
+
+
+Claise, et al.         Expires September 11, 2019              [Page 17]
+
+Internet-Draft           YANG Module Versioning               March 2019
+
+
    to which module revision the import statement should resolve to.
    Hence, a datastore schema constructed by a client using the
    information contained in YANG library may not exactly match the
@@ -778,14 +963,6 @@ Internet-Draft           YANG Module Versioning               March 2019
 
    If a module import statement could resolve to more than one module
    revision defined in the datastore schema, and one of those revisions
-
-
-
-Claise, et al.          Expires September 8, 2019              [Page 14]
-
-Internet-Draft           YANG Module Versioning               March 2019
-
-
    is implemented (i.e., not an 'import-only' module), then the import
    statement MUST resolve to the revision of the module that is defined
    as being implemented by the datastore schema.
@@ -794,15 +971,16 @@ Internet-Draft           YANG Module Versioning               March 2019
    revision defined in the datastore schema, and none of those revisions
    are implemented, but one of more modules revisions specify a YANG
    semantic version, then the import MUST resolve to the module with the
-   greatest version number, according to the rules in Section 3.
+   greatest version number, according to the version comparison rules in
+   Section 3.
 
    If a module import statement could resolve to more than one module
    revision defined in the datastore schema, none of those revisions are
    implemented, and none of the modules revisions have a YANG semantic
    version number, then the import MUST resolve to the module that has
-   the most recent revision-date.
+   the most recent revision date.
 
-5.2.  Reporting how deprecated and obsolete nodes are handled
+5.3.  Reporting how deprecated and obsolete nodes are handled
 
    The ietf-semver YANG module augments YANG library with two leaves to
    allow a server to report how it handles status 'deprecated' and
@@ -821,10 +999,17 @@ Internet-Draft           YANG Module Versioning               March 2019
 
    Implementations that implement the YANG semantic versioning scheme
    defined in this document MUST set the 'deprecated-nodes-implemented'
-   leaf because the refined module update rules in Section 4 assume that
-   this is how servers handle 'deprecated' and 'obsolete' nodes to
+   leaf because the refined module update rules in Section 4 require
+   that this is how servers handle 'deprecated' and 'obsolete' nodes to
    comply with YANG module semantic versioning.
 
+
+
+Claise, et al.         Expires September 11, 2019              [Page 18]
+
+Internet-Draft           YANG Module Versioning               March 2019
+
+
    If a server does not set the 'deprecated-nodes-implemented' leaf,
    then clients MUST NOT rely solely on the YANG module semantic version
    number to determine whether two module versions are backwards
@@ -832,16 +1017,6 @@ Internet-Draft           YANG Module Versioning               March 2019
    has changed to 'deprecated' and whether those nodes are implemented
    by the server.
 
-
-
-
-
-
-Claise, et al.          Expires September 8, 2019              [Page 15]
-
-Internet-Draft           YANG Module Versioning               March 2019
-
-
 6.  YANG status description extension
 
    The ietf-semver module specifies the YANG extension 'status-
@@ -871,10 +1046,10 @@ Internet-Draft           YANG Module Versioning               March 2019
    have an associated YANG semantic version, as compatibility for
    instance data is undefined.
 
-   However, Instance data may reference an associated YANG schema, and
+   However, instance data may reference an associated YANG schema, and
    that schema could make use of semantic version numbers, both for the
    individual YANG modules that comprise the schema, and potentially for
-   the entire schema itself (e.g.  [I-D.rwilton-netmod-yang-packages]).
+   the entire schema itself (e.g., [I-D.rwilton-netmod-yang-packages]).
 
    In this way, the versioning of a schema associated with an instance
    data set, may allow a client to determine whether the instance data
@@ -883,29 +1058,27 @@ Internet-Draft           YANG Module Versioning               March 2019
 
    One common scenario, where instance data may have to cope with
    changes to the schema is for the <startup> datastore when a server is
-   restarted with a different YANG schema (e.g. due to a software
-   upgrade or downgrade).  How a server restores the configuration from
-   <startup> during such upgrades or downgrades is outside the scope of
-   this specification.
-
-

-
-Claise, et al.          Expires September 8, 2019              [Page 16]
+Claise, et al.         Expires September 11, 2019              [Page 19]
 
 Internet-Draft           YANG Module Versioning               March 2019

+   restarted with a different YANG schema (e.g. due to a software
+   upgrade or downgrade).  How a server restores the configuration from
+   <startup> during such upgrades or downgrades is outside the scope of
+   this specification.
+
 8.  Guidelines
 
 8.1.  Guidelines to YANG model authors
 
-   NBC changes to YANG models cause problems to the clients, who are the
-   consumers of the YANG models, and SHOULD be avoided.  However, there
-   are cases where NBC changes are required, e.g. to fix an incorrect
-   YANG model.
+   NBC changes to YANG models may cause problems to clients, who are
+   consumers of YANG models, and SHOULD be avoided.  However, there are
+   cases where NBC changes are required, e.g. to fix an incorrect YANG
+   model.
 
    YANG model authors are recommended to minimize NBC changes and keep
    changes BC whenever possible.
@@ -917,74 +1090,53 @@ Internet-Draft           YANG Module Versioning               March 2019
    impact on clients and YANG model authors SHOULD try to mitigate that
    impact.
 
-   Updates SHOULD be applied to the latest revision of YANG modules.
+8.1.1.  Use of YANG semantic versioning
 
-8.1.1.  Use of semantic versioning
+   Module authors should use the following guidance when applying the
+   module version update rules specified in Section 2.3.
 
-   The scheme from semver.org 2.0.0 SHOULD be used if modifications are
-   always made to the latest revision of the YANG modules.
+   Updates to modules SHOULD be applied to the latest version of YANG
+   modules, avoiding the use the 'm|M' patch modifier.  When used in
+   this way, the YANG semantic version numbers are compatible with the
+   versioning scheme defined by the semver.org 2.0.0 rules.
 
-   The YANG semantic versioning scheme SHOULD be used only if it is
-   needed to do updates to older revisions of the YANG modules.  Once a
-   modifier is added, it is sticky for that "stream".  For example if
-   version 3.4.1M is modified in a BC way, the next version is 3.4.2M.
-   This is to indicate that 3.4.2M is not BC with 3.4.0, however it
-   comes at the cost of not being to indicate the type of change between
-   3.4.1M and 3.4.2M.
+   Changes to older versions of published YANG modules SHOULD be
+   minimized, since there may be a greater impact on clients, and
+   comparing between version numbers becomes more limited if the 'm|M'
+   modifiers are used.  However, if it necessary to make such changes
+   then the following guidelines apply:
 
-   Reuse of an already used module-version MUST be avoided.  For example
-   for the YANG versioning scheme, when updating 3.4.0 in a NBC manner
-   the module author must verify whether version 4.0.0 is available for
-   use and if that version was already used, the updated module must use
-   the version 3.4.1M.
+      Any changes SHOULD also be made to a latest version of the YANG
+      module, if appropriate.
 
-   From a published revision N of a module, the next published revision
-   N+1 of the module SHOULD have one of:
+      Where possible, changes SHOULD be restricted to backwards-
+      compatible changes only.
 
-   1.  MAJOR version incremented by 1, MINOR and PATCH versions set to
-       0.  This indicates that in revision N+1:
 
-       *  There have been one or more non-backwards-compatible changes

 
-Claise, et al.          Expires September 8, 2019              [Page 17]
+Claise, et al.         Expires September 11, 2019              [Page 20]
 
 Internet-Draft           YANG Module Versioning               March 2019

-       *  There may also be new functionality which have been added in a
-          backwards-compatible manner
-
-       *  There may also be bug fixes which have been made in a
-          backwards-compatible manner
-
-   2.  MAJOR version unchanged, MINOR version incremented by 1 and PATCH
-       version set to 0.  This indicates that in revision N+1:
-
-       *  There are no non-backwards-compatible changes
-
-       *  There have been one or more new functionality which have been
-          added in a backwards compatible-manner
-
-       *  There may also be bug fixes which have been made in a
-          backwards-compatible manner
-
-   3.  MAJOR and MINOR versions unchanged, PATCH version incremented by
-       1.  This indicates that in revision N+1:
-
-       *  There are no non-backwards-compatible changes
-
-       *  There is no new functionality which has been added in a
-          backwards compatible-manner
+      NBC changes MAY be made, subject to the constraints defined in
+      Section 2.3.  The impact to clients SHOULD be carefully considered
+      and minimized if possible.
 
-       *  There are no more bug fixes which have been made in a
-          backwards-compatible manner
+   The version numbers associated with a module MUST never be reused.
+   E.g., when updating module version 3.4.0 in a NBC manner the module
+   author must verify whether version 4.0.0 is available for use and if
+   that version was already used, the updated module must use version
+   3.4.1M instead.
 
-       *  There may be editorial changes such a change to a desctiption
-          statement which does not change the semantics of the data node
-          in any way.
+   Patch modifier letters (i.e. 'm' or 'M') are sticky.  For example if
+   version 3.4.1M is modified in a BC way, the next version is 3.4.2M.
+   This is to indicate that 3.4.2M is not BC with 3.4.0, however it
+   comes at the cost of not being to indicate the type of change between
+   3.4.1M and 3.4.2M.
 
    As explained in Appendix A.2.2, while programatically determining a
    semantic version is possible using tools (e.g. the pyang utility),
@@ -999,17 +1151,8 @@ Internet-Draft           YANG Module Versioning               March 2019
    ways in which this can be done:
 
    o  If the server can support NBC versions of the YANG module
-      simultaneously AND the clients support version selection, then the
-      NBC changes MAY be done immediately.  The clients would select the
-
-
-
-
-Claise, et al.          Expires September 8, 2019              [Page 18]
-
-Internet-Draft           YANG Module Versioning               March 2019
-
-
+      simultaneously using version selection, then the NBC changes MAY
+      be done immediately.  Clients would be required to select the
       version which they support and the NBC change would have no impact
       on them.
 
@@ -1028,6 +1171,13 @@ Internet-Draft           YANG Module Versioning               March 2019
        the model but this has the risk of breaking modules which import
        the modified module.
 
+
+
+Claise, et al.         Expires September 11, 2019              [Page 21]
+
+Internet-Draft           YANG Module Versioning               March 2019
+
+
    2.  For A node with status "deprecated" MUST be supported for the
        solution described here to function properly.
 
@@ -1058,27 +1208,31 @@ Internet-Draft           YANG Module Versioning               March 2019
    The following sections have examples on how non-backwards-compatible
    changes can be made.
 
+8.1.2.1.  Removing a data node
+
+   Removing a leaf or container from the data tree, e.g. because support
+   for the corresponding feature is being removed:
+
+   1.  The node's status SHOULD be changed to "deprecated" and it MUST
+       be supported for at least one year.  This is a backwards-
+       compatible change.
+
+   2.  When the node is not available anymore, its status MUST be
+       changed to "obsolete" and the "status-description" updated, this
+       is a non-backwards-compatible change.  The "status-description"
+       SHOULD be used to explain why the node is not available anymore.

-Claise, et al.          Expires September 8, 2019              [Page 19]
-
-Internet-Draft           YANG Module Versioning               March 2019

-8.1.2.1.  Removing a data node
 
-   Removing a leaf or container from the data tree, e.g. because support
-   for the corresponding feature is being removed:
 
-   1.  The node's status SHOULD be changed to "deprecated" and it MUST
-       be supported for at least one year.  This is a backwards-
-       compatible change.
 
-   2.  When the node is not available anymore, its status MUST be
-       changed to "obsolete" and the "status-description" updated, this
-       is a non-backwards-compatible change.  The "status-description"
-       SHOULD be used to explain why the node is not available anymore.
+Claise, et al.         Expires September 11, 2019              [Page 22]
+
+Internet-Draft           YANG Module Versioning               March 2019
+
 
 8.1.2.2.  Changing the type of a leaf node
 
@@ -1113,15 +1267,6 @@ Internet-Draft           YANG Module Versioning               March 2019
            id".  However, if the value can not be mapped, we need a way
            of returning "unsupported" TBD.
 
-
-
-
-
-Claise, et al.          Expires September 8, 2019              [Page 20]
-
-Internet-Draft           YANG Module Versioning               March 2019
-
-
    4.  When node "vpn-id" is not available anymore, its status MUST be
        changed to "obsolete" and the "status-description" is updated.
        This is a non-backwards-compatible change.
@@ -1134,17 +1279,31 @@ Internet-Draft           YANG Module Versioning               March 2019
 
 8.1.2.6.  Changing a default value
 
+
+
+
+
+
+
+Claise, et al.         Expires September 11, 2019              [Page 23]
+
+Internet-Draft           YANG Module Versioning               March 2019
+
+
 8.2.  Guidelines to YANG model clients
 
-   Here are some guidelines for YANG model clients:
+   Guidelines for clients of modules using YANG semantic versioning:
 
    o  Clients SHOULD be liberal when processing data received from a
       server.  For example, the server may have increased the range of
       an operational node causing the client to receive a value whch is
       outside the range of the YANG model revision it was coded against
 
-   o  Clients SHOULD look for status changes in new revisions of YANG
-      models they support.
+   o  Clients SHOULD monitor changes to published YANG modules through
+      their version numbers, and use appropriate tooling to understand
+      the specific changes between module versions.  In particular,
+      clients SHOULD NOT migrate to NBC versions of a module without
+      first understanding the specifics of the NBC changes.
 
    o  Clients SHOULD plan to make changes to match published status
       changes.  When a node's status changes from "current" to
@@ -1152,32 +1311,14 @@ Internet-Draft           YANG Module Versioning               March 2019
       timely fashion.  When a node's status changes to "obsolete",
       clients MUST stop using that node.
 
-   o  A client SHOULD not use unknown NBC versions automatically
+9.  Semantic Version Extension YANG Modules
 
-9.  Semantic Version Extension YANG Module
-
-   The extension and related ietf-yang-library changes described in this
-   module are defined in the YANG module below.
-
-   TODO - Define a separate type (in a ietf-semver-types.yang) file for
-   the YANG semver field definition.  It would be useful for the YANG
-   library augmentation, and possibly in the packages definition if that
-   work progresses.
-
-   TODO - Update the semantic version text to update the main definition
-   in this document
+   YANG module with extensions for defining a module's YANG semantic
+   version number, and importing by version.
 
    <CODE BEGINS> file "[email-masked]"
    module ietf-semver {
      yang-version 1.1;
-
-
-
-Claise, et al.          Expires September 8, 2019              [Page 21]
-
-Internet-Draft           YANG Module Versioning               March 2019
-
-
      namespace "urn:ietf:params:xml:ns:yang:ietf-semver";
      prefix semver;
 
@@ -1197,6 +1338,14 @@ Internet-Draft           YANG Module Versioning               March 2019
                   <mailto:[email-masked]>
 
         Author:   Robert Wilton
+
+
+
+Claise, et al.         Expires September 11, 2019              [Page 24]
+
+Internet-Draft           YANG Module Versioning               March 2019
+
+
                   <mailto:[email-masked]>
 
         Author:   Kevin D'Souza
@@ -1226,14 +1375,6 @@ Internet-Draft           YANG Module Versioning               March 2019
          "* Properly import ietf-yang-library.
           * Fix the name of module-semver => module-version.
           * Fix regular expression syntax.
-
-
-
-Claise, et al.          Expires September 8, 2019              [Page 22]
-
-Internet-Draft           YANG Module Versioning               March 2019
-
-
           * Augment yang-library with booleans as to whether or not
             deprecated and obsolete nodes are present.
           * Add an extension to enable import by semantic version.
@@ -1254,6 +1395,13 @@ Internet-Draft           YANG Module Versioning               March 2019
        semver:module-version "0.1.1";
      }
 
+
+
+Claise, et al.         Expires September 11, 2019              [Page 25]
+
+Internet-Draft           YANG Module Versioning               March 2019
+
+
      typedef version {
        type string {
          pattern '[0-9]{1,5}\.[0-9]{1,5}\.[0-9]{1,5}(m|M)?';
@@ -1282,14 +1430,6 @@ Internet-Draft           YANG Module Versioning               March 2019
            version number, depending on what form modifier 'v' takes:
 
            *  'M' - the change represents a non-backwards-compatible
-
-
-
-Claise, et al.          Expires September 8, 2019              [Page 23]
-
-Internet-Draft           YANG Module Versioning               March 2019
-
-
                     change
 
            *  'm' - the change represents a backwards-compatible change
@@ -1311,6 +1451,13 @@ Internet-Draft           YANG Module Versioning               March 2019
           The rules for updating the module-version number are described
           in section XXX of 'YANG Semantic Versioning for Modules';
 
+
+
+Claise, et al.         Expires September 11, 2019              [Page 26]
+
+Internet-Draft           YANG Module Versioning               March 2019
+
+
           By comparing the module-version between two revisions of a
           given module, one can determine if different revisions are
           backwards compatible or not, as well as whether or not new
@@ -1324,9 +1471,10 @@ Internet-Draft           YANG Module Versioning               March 2019
           statements.  Zero or one module-version statement is allowed
           per parent statement. No substatements are allowed.
 
-          'revision' statements in submodule MAY contain a
-          'module-version' statement for documentation purposes, but it
-          has no effect on the including module's semantic version.";
+          'revision' statements in submodules MAY contain a
+          'module-version' statement for documentation purposes, but
+          its meaning is undefined, and has no effect on the including
+          module's semantic version.";
        reference
          "draft-verdt-netmod-yang-semver:
           YANG Semantic Versioning for Modules";
@@ -1338,14 +1486,6 @@ Internet-Draft           YANG Module Versioning               March 2019
          "This extension specifies an acceptable set of semantic
           versions of a given module that may be imported.
 
-
-
-
-Claise, et al.          Expires September 8, 2019              [Page 24]
-
-Internet-Draft           YANG Module Versioning               March 2019
-
-
           The statement MUST only be a substatement of the import
           statement.
 
@@ -1366,6 +1506,14 @@ Internet-Draft           YANG Module Versioning               March 2019
               (ii) "+ '\d+\.\d+\.\d+\+ '+"
                 Matches exact version or greater, e.g. 3.6.1+
 
+
+
+
+Claise, et al.         Expires September 11, 2019              [Page 27]
+
+Internet-Draft           YANG Module Versioning               March 2019
+
+
               (iii) "+' \d+\.\d+.\d+-\d+\.(\d+|MAX).(\d|MAX)+ '+"
                 Matches inclusive range,
                 e.g. 3.6.1-7.8.4, or 3.2.1-3.MAX.MAX";
@@ -1393,15 +1541,10 @@ Internet-Draft           YANG Module Versioning               March 2019
    }
    <CODE ENDS>
 
-   <CODE BEGINS> file "[email-masked]"
-
-
-
-Claise, et al.          Expires September 8, 2019              [Page 25]
-
-Internet-Draft           YANG Module Versioning               March 2019
-
+   YANG module with augmentations to YANG Library to support semantic
+   version numbers.
 
+   <CODE BEGINS> file "[email-masked]"
    module ietf-yl-semver {
      yang-version 1.1;
      namespace "urn:ietf:params:xml:ns:yang:ietf-yl-semver";
@@ -1419,6 +1562,14 @@ Internet-Draft           YANG Module Versioning               March 2019
        "IETF NETMOD (Network Modeling) Working Group";
      contact
        "WG Web:   <https://datatracker.ietf.org/wg/netmod/>
+
+
+
+Claise, et al.         Expires September 11, 2019              [Page 28]
+
+Internet-Draft           YANG Module Versioning               March 2019
+
+
         WG List:  <mailto:[email-masked]>
 
         Author:   Benoit Claise
@@ -1450,14 +1601,6 @@ Internet-Draft           YANG Module Versioning               March 2019
 
      revision 2019-02-27 {
        description
-
-
-
-Claise, et al.          Expires September 8, 2019              [Page 26]
-
-Internet-Draft           YANG Module Versioning               March 2019
-
-
          "Moved YANG library augmentations into a separate module.";
        reference
          "draft-verdt-netmod-yang-semver:
@@ -1475,6 +1618,14 @@ Internet-Draft           YANG Module Versioning               March 2019
             match the semver:version value in specific revision of the
             module loaded in this module-set.";
          reference
+
+
+
+Claise, et al.         Expires September 11, 2019              [Page 29]
+
+Internet-Draft           YANG Module Versioning               March 2019
+
+
            "draft-verdt-netmod-yang-semver: YANG Semantic Versioning";
        }
      }
@@ -1506,14 +1657,6 @@ Internet-Draft           YANG Module Versioning               March 2019
             absent then the behaviour is unspecified.";
          reference
            "draft-verdt-netmod-yang-semver: Reporting how deprecated and
-
-
-
-Claise, et al.          Expires September 8, 2019              [Page 27]
-
-Internet-Draft           YANG Module Versioning               March 2019
-
-
             obsolete nodes are handled";
        }
      }
@@ -1532,6 +1675,13 @@ Internet-Draft           YANG Module Versioning               March 2019
 
    o  Ebben Aries
 
+
+
+Claise, et al.         Expires September 11, 2019              [Page 30]
+
+Internet-Draft           YANG Module Versioning               March 2019
+
+
    o  Jason Sterne
 
    o  Joe Clarke
@@ -1560,16 +1710,6 @@ Internet-Draft           YANG Module Versioning               March 2019
    The document does not define any new protocol or data model.  There
    are no security impacts.
 
-
-
-
-
-
-Claise, et al.          Expires September 8, 2019              [Page 28]
-
-Internet-Draft           YANG Module Versioning               March 2019
-
-
 12.  IANA Considerations
 
 12.1.  YANG Module Registrations
@@ -1591,6 +1731,13 @@ Internet-Draft           YANG Module Versioning               March 2019
 
       Name: ietf-yl-semver
 
+
+
+Claise, et al.         Expires September 11, 2019              [Page 31]
+
+Internet-Draft           YANG Module Versioning               March 2019
+
+
       XML Namespace: urn:ietf:params:xml:ns:yang:ietf-yl-semver
 
       Prefix: yl-semver
@@ -1616,20 +1763,13 @@ Internet-Draft           YANG Module Versioning               March 2019
 
    [RFC8407]  Bierman, A., "Guidelines for Authors and Reviewers of
               Documents Containing YANG Data Models", BCP 216, RFC 8407,
-              DOI 10.17487/RFC8407, October 2018, <https://www.rfc-
-              editor.org/info/rfc8407>.
-
-
-
-Claise, et al.          Expires September 8, 2019              [Page 29]
-
-Internet-Draft           YANG Module Versioning               March 2019
-
+              DOI 10.17487/RFC8407, October 2018,
+              <https://www.rfc-editor.org/info/rfc8407>.
 
    [RFC8525]  Bierman, A., Bjorklund, M., Schoenwaelder, J., Watsen, K.,
               and R. Wilton, "YANG Library", RFC 8525,
-              DOI 10.17487/RFC8525, March 2019, <https://www.rfc-
-              editor.org/info/rfc8525>.
+              DOI 10.17487/RFC8525, March 2019,
+              <https://www.rfc-editor.org/info/rfc8525>.
 
 13.2.  Informative References
 
@@ -1643,6 +1783,17 @@ Internet-Draft           YANG Module Versioning               March 2019
               YANG Module Update Procedure", draft-clacla-netmod-yang-
               model-update-06 (work in progress), July 2018.
 
+
+
+
+
+
+
+Claise, et al.         Expires September 11, 2019              [Page 32]
+
+Internet-Draft           YANG Module Versioning               March 2019
+
+
    [I-D.claise-semver]
               Claise, B., Barnes, R., and J. Clarke, "Semantic
               Versioning and Structure for IETF Specifications", draft-
@@ -1671,30 +1822,89 @@ Internet-Draft           YANG Module Versioning               March 2019
    [yangcatalog]
               "YANG Catalog", <https://yangcatalog.org>.
 
-Appendix A.  Appendix
+13.3.  URIs
+
+   [1] https://github.com/netmod-wg/yang-ver-dt/issues/14
 
+   [2] https://github.com/netmod-wg/yang-ver-dt/issues/11
 
+   [3] https://github.com/netmod-wg/yang-ver-dt/issues/13
 
+   [4] https://github.com/netmod-wg/yang-ver-dt/issues/12
 
+   [5] https://github.com/netmod-wg/yang-ver-dt/issues/10
 
-Claise, et al.          Expires September 8, 2019              [Page 30]
+   [6] https://github.com/netmod-wg/yang-ver-dt/issues/9
+
+   [7] https://github.com/netmod-wg/yang-ver-dt/issues/8
+
+   [8] https://github.com/netmod-wg/yang-ver-dt/issues/7
+
+   [9] https://github.com/netmod-wg/yang-ver-dt/issues/6
+
+
+
+
+Claise, et al.         Expires September 11, 2019              [Page 33]
 
 Internet-Draft           YANG Module Versioning               March 2019

+   [10] https://github.com/netmod-wg/yang-ver-dt/issues/5
+
+   [11] https://github.com/netmod-wg/yang-ver-dt/issues/4
+
+   [12] https://github.com/netmod-wg/yang-ver-dt/issues/15
+
+   [13] https://github.com/netmod-wg/yang-ver-dt/issues/2
+
+Appendix A.  Appendix
+
 A.1.  Open Issues
 
-   o  Do we need a new version of YANG?
-      While eventually this will fold into a new version, the belief is
-      this solution can work with extensions alone with an update to the
-      [RFC7950] text concerning module updates.
+   Open issues are being tracked at <https://github.com/netmod-wg/yang-
+   ver-dt/issues>.  Currently open issues are:
+
+   o  Do we need a new version of YANG? #14 [1]
+
+   o  Add guidance text about warning NBC changes might break imports
+      #11 [2]
+
+   o  Add a naming convention for versioned YANG file#13 [3]
+
+   o  Define editorial, bc, nbc impact of adding, changing, removing
+      extension stmts#12 [4]
+
+   o  How to version modules in IETF drafts (after they have been
+      published at 1.0.0 or later#10 [5]
+
+   o  The solution does not strictly support semver 2.0.0#9 [6]
+
+   o  Are whitespace changes allow between two module instances with the
+      same version (or revision)?#8 [7]
+
+   o  Do we assume that a module has an implicit semver if none as been
+      specified?#7 [8]
+
+   o  Is changing the ordering of nodes an NBC change?#6 [9]
+
+   o  Should version statement be at top level or under revision
+      statement?#5 [10]
+
+   o  Figure out whether changing the imports constitute a BC or NBC
+      change#4 [11]
+
+   o  Does BC or NBC depend on whether the node is config true/false?#15
+      [12]
+
+   o  Status obsolete nodes#2 [13]
+
+
+
+Claise, et al.         Expires September 11, 2019              [Page 34]
+
+Internet-Draft           YANG Module Versioning               March 2019
 
-   o  We could consider a new naming convention for module files.
-      Today, module files are named using a [email-masked]
-      notation.  We could consider module%semver.yang or
-      module#version.yang variants.  Re-using the '@' for version is not
-      ideal, so another separator character should be used.  In this
-      manner, both version and revision could be used.
 
 A.2.  Derived Semantic Version
 
@@ -1729,15 +1939,6 @@ A.2.2.  Implementation Experience
 
    o  the derived-semantic-version leaf is established by examining the
       the YANG module themselves.  As such derived-semantic-version only
-
-
-
-
-Claise, et al.          Expires September 8, 2019              [Page 31]
-
-Internet-Draft           YANG Module Versioning               March 2019
-
-
       takes syntax into account as opposed to the meaning of various
       elements when it computes the semantic version.
 
@@ -1754,6 +1955,13 @@ Internet-Draft           YANG Module Versioning               March 2019
           versions assume non-backward compatible changes were done.,
           thus bump its derived semantic MAJOR version.
 
+
+
+Claise, et al.         Expires September 11, 2019              [Page 35]
+
+Internet-Draft           YANG Module Versioning               March 2019
+
+
       3.  Else, run "pyang --check-update-from" on module A, revision N
           and revision N+1 to see if backward-incompatible changes
           exist.
@@ -1783,17 +1991,6 @@ Internet-Draft           YANG Module Versioning               March 2019
 
 Authors' Addresses
 
-
-
-
-
-
-
-Claise, et al.          Expires September 8, 2019              [Page 32]
-
-Internet-Draft           YANG Module Versioning               March 2019
-
-
    Benoit Claise
    Cisco Systems, Inc.
    De Kleetlaan 6a b1
@@ -1814,6 +2011,13 @@ Internet-Draft           YANG Module Versioning               March 2019
    Email: [email-masked]

+
+
+Claise, et al.         Expires September 11, 2019              [Page 36]
+
+Internet-Draft           YANG Module Versioning               March 2019
+
+
    Reshad Rahman
    Cisco Systems, Inc.
 
@@ -1842,14 +2046,6 @@ Internet-Draft           YANG Module Versioning               March 2019
    Email: [email-masked]

-
-
-
-Claise, et al.          Expires September 8, 2019              [Page 33]
-
-Internet-Draft           YANG Module Versioning               March 2019
-
-
    Kevin D'Souza
    AT&T
    200 S. Laurel Ave
@@ -1873,32 +2069,4 @@ Internet-Draft           YANG Module Versioning               March 2019

-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Claise, et al.          Expires September 8, 2019              [Page 34]
+Claise, et al.         Expires September 11, 2019              [Page 37]
diff --git a/yang-semver/draft-verdt-netmod-yang-semver.xml b/yang-semver/draft-verdt-netmod-yang-semver.xml
index 0ff171f..75a72c5 100755
--- a/yang-semver/draft-verdt-netmod-yang-semver.xml
+++ b/yang-semver/draft-verdt-netmod-yang-semver.xml
@@ -132,7 +132,7 @@
   version numbers to help manage the lifecycle of YANG modules.</t>
   
   <t>
-  The solution is comprised of the following six parts:
+  The solution is comprised of the following seven parts:
        <list style="bullets">
        <t>A definition for the YANG semantic versioning scheme for
        modules, and an explanation of how the semver extension can be
@@ -143,8 +143,7 @@
        inter-module version dependencies to be captured within YANG
        module definitions.</t>
        <t>Updates to the YANG 1.1 module update rules to accommodate the
-       semantic versioning scheme and to provide more consistent
-       handling of changes to the YANG "status" statement.</t>
+       semantic versioning scheme.</t>
        <t>Updates and augmentations to ietf-yang-library to include the
        YANG semantic version number in the module descriptions, to
        report how 'deprecated' and 'obsolete' nodes are handled by a
@@ -154,24 +153,26 @@
        'status' statement to allow additional documentation as to why a
        node is being deprecated, and what alternatives may be
        available.</t>
+       <t>A description of how YANG semantic versioning applies to YANG
+       instance data.</t>
        <t>Guidelines to YANG module authors on how the YANG semantic
-       versioning rules should be used, along with examples. </t>
+       versioning rules should be used, along with examples.</t>
      </list>
   </t>
 
-  <t>Open issues are listed at <xref target="open_issues"/>, and also
-  tracked at https://github.com/netmod-wg/yang-ver-dt/issues</t>
+  <t>Open issues are listed at <xref target="open_issues"/>, and
+  tracked at <eref target="https://github.com/netmod-wg/yang-ver-dt/issues"/>.</t>
 
-  <section anchor="changes" title="Changes to YANG RFCs">
-    <section anchor="changes_7950" title="Changes to RFC7950">
+  <section anchor="changes" title="Updates to YANG RFCs">
+    <section anchor="changes_7950" title="Updates to RFC7950">
       <t>This document proposes updates to <xref target="RFC7950"/> to
       address some of the requirements.  It should be noted that there
       is also active WG discussion on the next steps towards an updated
       version of YANG, and potentially some of the functionality
       described here could be folded into an updated revision of <xref
-      target="RFC7950"/>, although that it might adversely impact when
+      target="RFC7950"/>, although that might adversely impact when
       (parts of) a standards based YANG module versioning solution is
-      available for use.</t>
+      available.</t>
 
       <t>The sections listed below provide updates to <xref
       target="RFC7950"/>.  The design team does not believe any of the
@@ -191,14 +192,14 @@
 	</list>
       </t>
     </section>
-    <section anchor="changes_rfc8525" title="Changes to RFC8525">
+    <section anchor="changes_rfc8525" title="Updates to RFC8525">
       <t>This document updates <xref target="RFC8525"/>.  <xref
       target="ietf_yang_library_updates"/> defines how a reader of a
       YANG library datastore schema chooses which version of an
       import-only module is used to resolve a module import when the
       definition is otherwise ambiguous.</t>
     </section>
-    <section anchor="changes_rfc8407" title="Changes to RFC8407">
+    <section anchor="changes_rfc8407" title="Updates to RFC8407">
       <t><xref target="guidelines"/> updates <xref target="RFC8407"/> to
       provide guidelines on how the YANG module semantic versioning can
       be used to manage the lifecycle of YANG modules when using strict RFC
@@ -255,9 +256,9 @@
   YANG submodules are not independently versioned by the YANG semantic
   versioning scheme.  Instead, if a versioned module includes one or
   more submodules then those submodules are implicitly versioned as part
-  of the module's 'semver:version' statements, and all 'include'
-  statements MUST specify the revision-date for each of the included
-  submodules.</t>
+  of the module's 'semver:version' statements, and all the module's
+  'include' statements MUST specify the revision-date for each of the
+  included submodules.</t>

   <section anchor="version_classification" title="Classification of changes between module revisions">
@@ -269,8 +270,9 @@
     <t>The semantic version change between any two arbitrary revisions
     of a YANG module can be classified into one of four categories:
     'unchanged', 'editorial, 'backwards-compatible' or
-    'non-backwards-compatible'.  The classification is performed by
-    use of the following rules:
+    'non-backwards-compatible'.  A summary of the classification is
+    given below, with the specific rules as they apply to YANG
+    statements provided in <xref target="update_rules"/>.
     <list style="bullets">
       <t>The semantic version change between two module revisions is
       defined as 'unchanged' if, after excluding 'revision' and
@@ -278,21 +280,21 @@
       remaining changes are insignificant white space changes.</t>
       
       <t>An 'editorial' module semantic version change is where there
-      are changes in the module's statements, or statement ordering,
-      between the two module revisions, but those changes do not affect
-      the syntax or semantic meaning of the module in any way.  An
-      example of an editorial change would be a fix to a spelling
-      mistake in a description statement.</t>
+      are changes in the module's statements, between the two module
+      revisions, but those changes do not affect the syntax or semantic
+      meaning of the module in any way.  An example of an editorial
+      change would be a fix to a spelling mistake in a description
+      statement. </t>
 
       <t>A 'backwards-compatible' module semantic version change is
       where some syntax or semantic changes exists between the two
       module revisions, but all changes follow the rules specified in
-      <xref target="update_rules"/>.</t>
+      <xref target="bc_update_rules"/>.</t>
 
       <t>A 'non-backwards-compatible' module semantic version change is
       where some syntax or semantic changes exists between the two
-      module revisions, and those changes do not follow the rules
-      specified in <xref target="update_rules"/>.</t>
+      module revisions, and those changes do not follow the rules for a
+      'backwards-compatible' version change.</t>
     </list>
     </t>
   </section>
@@ -312,7 +314,7 @@
       semantic versioning scheme supports limited updates to older
       versions of YANG modules, to allow for bug fixes and enhancements
       to module versions that are not the latest.</t>
-      
+
       <t>Module definitions that follow the semver.org 2.0.0 versioning
       scheme are fully compatible with implementations that understand
       the YANG semantic versioning scheme.</t>
@@ -323,7 +325,7 @@
       by the semver.org 2.0.0 versioning scheme.</t>
     </list>
     </t>
-    <t>Every YANG module versioned using a YANG semantic versioning
+    <t>Every YANG module versioned using the YANG semantic versioning
     scheme specifies the module's semantic version number by including
     the 'semver:module-version' statement according to the following
     rules:
@@ -354,9 +356,8 @@
 
        <t>'Y' is the MINOR version.  Changes in the minor version number
        indicate changes that are backwards-compatible to versions with
-       the same major version number, but a lower minor version number,
-       unless either version has a patch version with an 'm' or 'M'
-       modifier.</t>
+       the same major version number, but a lower minor version number
+       and no patch 'm' or 'M' modifier.</t>
 
        <t>'Zv' is the PATCH version and modifier.  Changes in the patch
        version number can indicate editorial, backwards-compatible, or
@@ -372,17 +373,74 @@
        </t>
      </list>
     </t>
-    <t>YANG requires that if two modules have the same revision date
-    then they MUST have the same semantic content.  A similar constraint
-    applies for YANG semantic version numbers, i.e. two revisions of a
-    module that have the same semantic version numbers MUST have the
-    same semantic content.</t>
-    <t>A module MUST NOT have multiple revision where the version string
-    has the same MAJOR, MINOR and PATCH version numbers, but different
-    PATCH modifier letter.  E.g., module version "1.2.3M" is not allowed
-    if module version "1.2.3" has already been defined.  Neither can
-    there be two different revisions of a YANG module with different
-    content but the same </t>
+    <t>The YANG module name and YANG semantic version number uniquely
+    identifies a revision of a module, with an associated revision date.
+    There MUST NOT be multiple instances of a YANG module definition
+    with the same module name and YANG semantic version number but
+    different content or revision date.</t>
+    <t>There MUST NOT be multiple versions of a YANG module that have
+    the same MAJOR, MINOR and PATCH version numbers, but different patch
+    modifier letter.  E.g., module version "1.2.3M" MUST NOT be defined
+    if module version "1.2.3" has already been defined.</t>
+    <section anchor="example_versions" title="Examples for YANG semantic version numbers">
+      <t>The following diagram and explanation illustrates how YANG semantic version numbers work.</t>
+      <figure>
+        <preamble>Example YANG semantic version numbers for an example module:</preamble>
+      <artwork>
+        0.1.0
+          |
+        0.2.0
+          |  
+        1.0.0
+          |  \
+          |   1.1.0 -> 1.1.1m -> 1.1.2M
+          |    |
+          |   1.2.0 -> 1.2.1M -> 1.2.2M
+          |    |
+          |   1.3.0 -> 1.3.1
+          |
+        2.0.0
+          |
+        3.0.0
+             \
+              3.1.0
+      </artwork>
+    </figure>
+    <t>The tree diagram above illustrates how an example modules version
+    history might evolve.  For example, the tree might represent the
+    following changes, listed in chronological order from oldest
+    revision to newest:
+    <list>
+      <t>0.1.0  - first beta module version</t>
+      <t>0.2.0  - second beta module version (with NBC changes)</t>
+      <t>1.0.0  - first release (may have NBC changes from 0.2.0)</t>
+      <t>1.1.0  - added new functionality, leaf "foo" (BC)</t>
+      <t>1.2.0  - added new functionality, leaf "baz" (BC)</t>
+      <t>1.3.0  - improve existing functionality, added leaf "foo-64" (BC)</t>
+      <t>1.3.1  - improve description wording for "foo-64" (Editorial)</t>
+      <t>1.1.1m - backport "foo-64" leaf to 1.1.x to avoid implementing "baz" from 1.2.0 (BC)</t>
+      <t>2.0.0  - change existing model for performance reasons, e.g. re-key list (NBC)</t>
+      <t>1.1.2M - NBC point bug fix, not required in 2.0.0 due to model changes (NBC)</t>
+      <t>3.0.0  - NBC bugfix, rename "baz" to "bar"; also add new BC leaf "wibble"; (NBC)</t>
+      <t>1.2.1M - backport NBC fix, changing "baz" to "bar"</t>
+      <t>1.2.2M - backport "wibble".  This is a BC change but "M" modifier is sticky.</t>
+      <t>3.1.0  - introduce new leaf "wobble" (BC)</t>
+    </list>
+    </t>
+    <t>The partial ordering relationships based on the semantic versioning numbers can be defined as follows:
+    <list>
+      <t>1.0.0 &lt; 1.1.0 &lt; 1.2.0 &lt; 1.3.0 &lt; 2.0.0 &lt; 3.0.0 &lt; 3.1.0</t>
+      <t>1.0.0 &lt; 1.1.0 &lt; 1.1.1m &lt; 1.1.2M</t>
+      <t>1.0.0 &lt; 1.1.0 &lt; 1.2.0 &lt; 1.2.1M &lt; 1.2.2M</t>
+    </list>
+    </t>
+    <t>There is no ordering relationship between 1.1.1M and either 1.2.0 or
+    1.2.1M, except that they share the common ancestor of 1.1.0.</t>
+    <t>Looking at the version number alone, the module definition in
+    2.0.0 does not necessarily contain the contents of 1.3.0.  However,
+    the module revision history in 2.0.0 would likely indicate that it
+    was edited from module version 1.3.0.</t>
+    </section>
   </section>
   
   <section anchor="semver_update_rules" title="YANG Semantic Version Update Rules">
@@ -395,7 +453,8 @@
 
     <t>The first step is to classify the module change as 'editorial',
     'backwards-compatible', or 'non-backwards-compatible version' using
-    the rules defined in <xref target="version_classification"/>.</t>
+    the rules defined in <xref target="version_classification"/> and
+    <xref target="update_rules"/>.</t>
 
     <t>The second step is to calculate the value of the 'semver:version'
     field for the new module revision, based on the value of the
@@ -404,7 +463,7 @@
 
     <t>The following rules define how the value for the 'semver:version'
     argument in the new module revision is calculated:
-    <list>
+    <list style="numbers">
       <t>If a module is being updated in a non-backwards-compatible
       way, then the module version "X.Y.Z[m|M]" MUST be updated to
       "X+1.0.0" unless that module version has already been defined with
@@ -414,7 +473,7 @@
       <t>If a module is being updated in a backwards-compatible way,
       then the next version number depends on the format of the current
       version number:
-      <list>
+      <list style="format %i">
 	<t>"X.Y.Z" - the module version MUST be updated to "X.Y+1.0",
 	unless that module version has already been defined with
 	different content, when the module version MUST be updated to
@@ -429,7 +488,7 @@
       <t>If a module is being updated in an editorial way, then the next
       version number depends on the format of the current version
       number:
-      <list>
+      <list style="format %i">
 	<t>"X.Y.Z" - the module version MUST be updated to "X.Y.Z+1"</t>
 	<t>"X.Y.Zm" - the module version MUST be updated to
 	"X.Y.Z+1m".</t>
@@ -449,21 +508,20 @@
   <section anchor="semver_extension" title="YANG Module Semver Extension">
     <t>This document defines a YANG extension to add the YANG module
     semantic version to a Module.  The complete definition of this YANG
-    module is in section XXX.
+    module is in <xref target="yang_modules"/>.
     </t>
 
     <figure>
       <artwork>
         extension module-version {
-            argument semver;
+          argument semver;
         }
       </artwork>
     </figure>
-    <t>
-    The extension would typically be used this way:
+    <t>The extension would typically be used this way:
     </t>
     <figure>
-       <artwork>
+      <artwork>
     module yang-module-name {
 
       namespace "name-space";
@@ -474,43 +532,63 @@
       description
         "to be completed";
 
+      revision 2018-02-28 {
+        description "Added leaf 'wobble'";
+        semver:module-version "3.1.0";
+      }
+
+      revision 2017-12-31 {
+        description "Rename 'baz' to 'bar', added leaf 'wibble'";
+        semver:module-version "3.0.0";
+      }
+	
       revision 2017-10-30 {
-        description
-          "Change the module structure";
+        description "Change the module structure";
         semver:module-version "2.0.0";
       }
 
+      revision 2017-08-30 {
+        description "Clarified description of 'foo-64' leaf";
+        semver:module-version "1.3.1";
+      }
+
       revision 2017-07-30 {
-        description
-          "Added new feature XXX";
+        description "Added leaf foo-64";
+        semver:module-version "1.3.0";
+      }
+
+      revision 2017-04-20 {
+        description "Add new functionality, leaf 'baz'";
         semver:module-version "1.2.0";
       }
 
       revision 2017-04-03 {
-        description
-          "Update copyright notice.";
-        semver:module-version "1.0.1";
+        description "Add new functionality, leaf 'foo'";
+        semver:module-version "1.1.0";
       }
 
       revision 2017-04-03 {
-        description
-          "First release version.";
+        description "First release version.";
         semver:module-version "1.0.0";
       }
 
+      revision 2017-01-30 {
+        description "NBC changes to initial revision";
+        semver:module-version "0.2.0";
+      }
+
       revision 2017-01-26 {
-        description
-          "Initial module for inet types";
+        description "Initial module version";
         semver:module-version "0.1.0";
       }
 
       //YANG module definition starts here
-       </artwork>
+      </artwork>
     </figure>
-
-	<t>
-    See also "Semantic Versioning and Structure for IETF Specifications" <xref target="I-D.claise-semver"/> for a mechanism
-    to combine the semantic versioning, the GitHub tools, and a potential change to the IETF process.
+   <t>See also "Semantic Versioning and Structure for IETF
+   Specifications" <xref target="I-D.claise-semver"/> for a mechanism to
+   combine the semantic versioning, the GitHub tools, and a potential
+   change to the IETF process.
     </t>
   </section>
 </section>
@@ -539,11 +617,15 @@
   imports if it is augmented by another module.</t>
 
   <t>The ietf-semver module defines the 'version' extension, a
-  substatement to the YANG 'import' statement.  An 'import' statement
-  may contain 'version' statements or a 'revision-date' statement, but
-  not both.  The 'version' statement may be specified multiple times,
-  requiring that the imported module version conforms to at least one of
-  the 'version' statements.</t>
+  substatement to the YANG 'import' statement.
+  <list>
+    <t>An 'import' statement MAY contain 'version' statements or a
+    'revision-date' statement, but not both.</t>
+    <t>The 'version' statement MAY be specified multiple times,
+    requiring that the imported module version conforms to at least one
+    of the 'version' statements.</t>
+  </list>
+  </t>
 
   <t>The argument to the 'version' statement takes one of three valid forms:
   <list style="numbers">
@@ -579,14 +661,16 @@
     </list>
     </t>
   </list>
-  The patch modifier letter is not included as part of module 'version'
-  argument, and is entirely ignored for import statement module version
-  number comparisons.
+  The patch modifier letter is not included as part of the
+  'semver:version' argument, and is entirely ignored for import
+  statement module version number comparisons.
   </t>
   <section title="Module import examples">
       <t>Consider an example module "example-module" that is
-      hypothetically available in the following versions: 0.1.0, 1.0.0,
-      1.1.0, 1.1.1m, 1.1.2M, 1.1.3M, 1.2.0, 2.0.0, 3.0.0.</t>
+      hypothetically available in the following versions: 0.1.0, 0.2.0,
+      1.0.0, 1.1.0, 1.1.1m, 1.1.2M, 1.2.0, 1.2.1M, 1.2.2M, 1.3.0, 1.3.1,
+      2.0.0, 3.0.0, and 3.1.0.  E.g. matching the versions illustrated
+      in <xref target="example_versions"/>.</t>
 
       <t>The first example selects the specific version 1.1.2M.  A
       specific version import might be used if 1.1.2M contained changes
@@ -600,31 +684,32 @@ import example-module {
       </figure>
 
       <t>The next example selects module versions that match, or are
-      greater than, version 1.1.0.  This form may be used if there is a
-      dependency on a data node introduced in version 1.1.0.  This is
+      greater than, version 1.2.0.  This form may be used if there is a
+      dependency on a data node introduced in version 1.2.0.  This is
       expected to be the most commonly used form of 'import by version'.</t>
-      <t>Includes versions: 1.1.0, 1.1.1m, 1.1.2M, 1.1.3M,
-      1.2.0, 2.0.0 and 3.0.0.</t>
+      <t>Includes versions: 1.2.0, 1.2.1M, 1.2.2M, 1.3.0, 1.3.1, 2.0.0,
+      3.0.0 and 3.1.0.</t>
       <figure>
         <artwork>
 import example-module {
-  semver:version 1.1.0+;
+  semver:version 1.2.0+;
 }
         </artwork>
       </figure>
 
       <t>The next example selects module versions that match, or are
-      greater than 1.1.0, but excluding the 1.1.2M and 1.1.3M versions.
-      This form may be needed if structural non backwards compatible
-      changes are introduced in a patch 'M' version.  Generally, it is
-      advisable to avoid making such changes.</t>
-      <t>Includes versions: 1.0.0, 1.1.0, 1.1.1m, 1.2.0, 2.0.0 and
-      3.0.0.</t>
+      greater than 1.1.0, but excluding all 1.1.x and 1.2.x 'M'
+      versions.  This form may be needed if structural non backwards
+      compatible changes are introduced in a patch 'M' version.
+      Generally, it is advisable to avoid making such changes.</t>
+      <t>Includes versions: 1.1.0, 1.1.1m, 1.2.0, 1.3.0, 1.3.1, 2.0.0,
+      3.0.0, and 3.1.0.</t>
       <figure>
         <artwork>
 import example-module {
-  semver:version 1.0.0-1.1.1;
-  semver:version 1.2.0+;
+  semver:version 1.1.0-1.1.1;
+  semver:version 1.2.0;
+  semver:version 1.3.0+;
 }
         </artwork>
       </figure>
@@ -633,8 +718,8 @@ import example-module {
       version number of 1.  This form may be useful if significant non
       backwards compatible changes have been introduced in version 2.0.0
       that break import backwards compatibility.</t>
-      <t>Includes versions: 1.0.0, 1.1.0, 1.1.1m, 1.1.2M, 1.1.3M,
-      1.2.0.</t>
+      <t>Includes versions: 1.0.0, 1.1.0, 1.1.1m, 1.1.2M, 1.2.0, 1.2.1M,
+      1.2.2M, 1.3.0 and 1.3.1.</t>
       <figure>
         <artwork>
 import example-module {
@@ -643,56 +728,76 @@ import example-module {
         </artwork>
       </figure>
   </section>
-  <section title="TODO">
-       <t>
-       TODO - Add text like this to the guidelines.  The import
-       statement SHOULD include a semver:import-versions statement and
-       MUST NOT include a revision statement.  An import statement MUST
-       NOT contain both a semver:import-versions and a revision
-       substatement.  The use of the revision substatement for import
-       should be discouraged.
-      </t>
-    <t>TODO - Perhaps guidance text should also warn about making nbc
-    changes that could break imports.  E.g. this could be an example of
-    where making something obsolete might be better than removing
-    it.</t>
-  </section>
 </section>
 
-<section title="Updates to YANG 1.1 Module Update Rules" anchor="update_rules">
-<t>TODO - This section should just specify what the rules are</t>
-      <t>
-          RFC 7950 section 11, must be updated to allow for non-backward changes provided they follow the
-          semantic versioning guidelines and increase the MAJOR version number when a backward incompatible
-          change is made.  This change is in the spirit of requirement 5.1 from <xref target="I-D.verdt-netmod-yang-versioning-reqs"/>.
-          The following is proposed text for this change.</t>
-
-      <t>
-      "As experience is gained with a module, it may be desirable to revise that module.
-      Changes to published modules are allowed, even if they have some potential to cause interoperability
-      problems, if the module-version YANG extension is used in the revision statement to clearly indicate the nature of the change."
-      </t>
-      <t>TODO - Specify that changing status to "deprecated" is an BC change, and changing status to "obsolete" is an NBC change".</t>
-      <t>A 'backwards-compatible' module semantic version change is
-      where some syntax or semantic changes exists between the two
-      module revisions, but all changes follow the rules specified in <xref target="update_rules"/>
-      of "Updating a
-      Module" of [RFC7950], except that no elements have been changed to
-      status 'obsolete', and re-ordering of statements is allowed.</t>
-
-      <t>Q: Should revision-date history and semantic version be excluded
-      from the comparison? RW: I've assumed yes.</t>
-
+<section title="Classifying changes in YANG modules" anchor="update_rules">
+  <t><xref target="RFC7950"/> chapter 11 defines the rules for what
+  constitutes a backwards compatible change in YANG 1.1.  However, the
+  YANG semantic versioning scheme defined in this document uses a
+  slightly modified version of this scheme, and also provides rules to
+  classify changes as editorial, backwards-compatible, or
+  non-backwards-compatible.</t>
+  <section anchor="editorial_update_rules" title="Editorial changes">
+    <t>Any changes that do not change the ordering or meaning of the
+    YANG module in any way are classified as 'editorial'.  The following
+    rules define 'editorial':
+   <list style="symbols">
+     <t>Changing any 'description' statement if it does not change the
+     semantic meaning of the statement is relates to.  E.g., fixing
+     spelling or grammar, or changing layout, are all allowed.</t>
+     <t>Adding or updating 'reference' statements.</t>
+     <t>Adding or updating the 'organization' statement.</t>
+     <t>Adding a new 'revision' or 'semver:module-version'
+     statement, or correcting a previous 'revision' or
+     'semver:module-version' statement.</t>
+     <t>A module may be split into a set of submodules or a submodule
+     may be removed, provided the definitions in the module do not
+     change except in the ways described above.</t>
+    </list></t>
   </section>
+  <section anchor="bc_update_rules" title="Backwards-compatible changes">
+    <t><xref target="RFC7950"/> chapter 11 defines the rules for what
+    constitutes a backwards-compatible change in YANG 1.1.  The document
+    update these rules in the following ways:
+    <list style="symbols">
+      <t>Adding or changing a 'status' node to 'obsolete' is not a
+      backwards-compatible change.  Other changes/additions of status
+      elements are backwards-compatible, as per <xref
+      target="RFC7950"/>.</t>
+      <t>Changing the ordering of statements is allowed if it does not
+      chanage the ordering of an rpc's 'input' substatements.</t>
+    </list></t>
+  </section>
+  <section anchor="nbc_update_rules" title="Non-backwards-compatible changes">
+    <t>All other changes to YANG modules that are not classified as
+    'editorial' or 'backwards-compatible' are defined as being
+    non-backwards-compatible.</t>
+    <t>Examples of non-backwards-compatible changes include:
+    <list style="symbols">
+      <t>Deleting a data node, or changing it to status obsolete.</t>
+      <t>Changing the name, type, or units of a data node.</t>
+      <t>Modifying the description in a way that changes the semantic
+      meaning of the data node.</t>
+      <t>Any changes that change or reduce the allowed value set of the
+      data node, either through changes in the type definition, or the
+      addition or changes to 'must' statements, or changes in the
+      description.</t>
+      <t>Adding or modifying 'when' statements that reduce when the data
+      node is available in the schema.</t>
+      <t>Making the statement conditional on if-feature.</t>
+    </list></t>
+  </section>
+</section>
 
-  <section title="Updates to ietf-yang-library" anchor="ietf_yang_library_updates">
+<section title="Updates to ietf-yang-library" anchor="ietf_yang_library_updates">
     <t>YANG library <xref target="RFC7895"/> <xref target="RFC8525"/> is
     modified to support semantic versioning in three ways.</t>
 
+    <section title="Advertising module version number">
     <t>The ietf-semver YANG module augments the 'module' list in
     ietf-yang-library with a 'version' leaf to optionally declare the
     YANG semantic version of each module.</t>
-
+    </section>
     <section title="Resolving ambiguous module imports">
       <t>A YANG datastore schema, defined in
       <xref target="RFC8525"/>, can specify multiple
@@ -716,12 +821,12 @@ import example-module {
       revisions are implemented, but one of more modules revisions
       specify a YANG semantic version, then the import MUST resolve to
       the module with the greatest version number, according to the
-      rules in <xref target="import_semver"/>.</t>
+      version comparison rules in <xref target="import_semver"/>.</t>
       <t>If a module import statement could resolve to more than one
       module revision defined in the datastore schema, none of those
       revisions are implemented, and none of the modules revisions have
       a YANG semantic version number, then the import MUST resolve to
-      the module that has the most recent revision-date.</t>
+      the module that has the most recent revision date.</t>
     </section>
     <section title="Reporting how deprecated and obsolete nodes are handled">
       <t>The ietf-semver YANG module augments YANG library with two
@@ -743,7 +848,7 @@ import example-module {
      <t>Implementations that implement the YANG semantic versioning
      scheme defined in this document MUST set the
      'deprecated-nodes-implemented' leaf because the refined module
-     update rules in <xref target="update_rules"/> assume that this is
+     update rules in <xref target="update_rules"/> require that this is
      how servers handle 'deprecated' and 'obsolete' nodes to comply with
      YANG module semantic versioning.</t>
      <t>If a server does not set the 'deprecated-nodes-implemented'
@@ -789,10 +894,10 @@ target="I-D.ietf-netmod-yang-instance-file-format"/> do not have an
 associated YANG semantic version, as compatibility for instance data is
 undefined.</t>
 
-<t>However, Instance data may reference an associated YANG schema, and
+<t>However, instance data may reference an associated YANG schema, and
 that schema could make use of semantic version numbers, both for the
 individual YANG modules that comprise the schema, and potentially for
-the entire schema itself (e.g. <xref
+the entire schema itself (e.g., <xref
 target="I-D.rwilton-netmod-yang-packages"/>).</t>
 
 <t>In this way, the versioning of a schema associated with an instance
@@ -810,48 +915,35 @@ of this specification.</t>
 
 <section anchor="guidelines" title="Guidelines">
    <section anchor="guidelines_authors" title="Guidelines to YANG model authors">
-      <t>NBC changes to YANG models cause problems to the clients, who are the consumers of the YANG models, and SHOULD be 
-         avoided. However, there are cases where NBC changes are required, e.g. to fix an incorrect YANG model.</t>
+      <t>NBC changes to YANG models may cause problems to clients, who are consumers of YANG models, and SHOULD be 
+         avoided.  However, there are cases where NBC changes are required, e.g. to fix an incorrect YANG model.</t>
       <t>YANG model authors are recommended to minimize NBC changes and keep changes BC whenever possible.</t>
       <t>The use of status "deprecated" with the status-description statement allows clients to plan a migration to alternative 
          data nodes.</t>
       <t>When NBC changes are introduced, consideration should be given to the impact on clients and YANG model authors SHOULD 
          try to mitigate that impact.</t>
-      <t>Updates SHOULD be applied to the latest revision of YANG modules.</t>
-      <section anchor="authors_semver" title="Use of semantic versioning">
-      <t>The scheme from semver.org 2.0.0 SHOULD be used if modifications are always made to the latest revision of the YANG 
-         modules.</t>
-      <t>The YANG semantic versioning scheme SHOULD be used only if it is needed to do updates to older revisions of the YANG 
-         modules. Once a modifier is added, it is sticky for that "stream". For example if version 3.4.1M is modified in a BC way, the next
+      <section anchor="authors_semver" title="Use of YANG semantic versioning">
+	<t>Module authors should use the following guidance when applying the module version update rules specified in <xref target="semver_update_rules"/>.</t>
+	<t>Updates to modules SHOULD be applied to the latest version of
+	YANG modules, avoiding the use the 'm|M' patch modifier.  When
+	used in this way, the YANG semantic version numbers are
+	compatible with the versioning scheme defined by the semver.org
+	2.0.0 rules.</t>
+	<t>Changes to older versions of published YANG modules SHOULD be
+	minimized, since there may be a greater impact on clients, and
+	comparing between version numbers becomes more limited if the
+	'm|M' modifiers are used.  However, if it necessary to make such
+	changes then the following guidelines apply:
+	<list>
+	  <t>Any changes SHOULD also be made to a latest version of the YANG module, if appropriate.</t>
+	  <t>Where possible, changes SHOULD be restricted to backwards-compatible changes only.</t>
+	  <t>NBC changes MAY be made, subject to the constraints defined in <xref target="semver_update_rules"/>. The impact to clients SHOULD be carefully considered and minimized if possible.</t>
+	</list>    
+	</t>
+	<t>The version numbers associated with a module MUST never be reused.  E.g., when updating module version 3.4.0 in a NBC manner the module author must verify whether version 4.0.0 is available for use and if that version was already used, the updated module must use version 3.4.1M instead.</t> 
+	<t>Patch modifier letters (i.e. 'm' or 'M') are sticky.  For example if version 3.4.1M is modified in a BC way, the next
          version is 3.4.2M. This is to indicate that 3.4.2M is not BC with 3.4.0, however it comes at the cost of not being to indicate the 
          type of  change between 3.4.1M and 3.4.2M.</t>
-      <t>Reuse of an already used module-version MUST be avoided. For example for the YANG versioning scheme, when updating 3.4.0 in a NBC manner the module author must verify whether version 4.0.0 is available for use and if that version was already used, the updated module must use the version 3.4.1M.</t>
-      <t>From a published revision N of a module, the next published revision N+1 of the module SHOULD
-         have one of:
-         <list style="numbers">
-            <t>MAJOR version incremented by 1, MINOR and PATCH versions set to 0. This indicates that in revision N+1:
-               <list style="symbols">
-               <t>There have been one or more non-backwards-compatible changes</t>
-               <t>There may also be new functionality which have been added in a backwards-compatible manner</t>
-               <t>There may also be bug fixes which have been made in a backwards-compatible manner</t>
-               </list></t>
-            <t>MAJOR version unchanged, MINOR version incremented by 1 and PATCH version set to 0. This indicates that
-               in revision N+1:
-               <list style="symbols">
-               <t>There are no non-backwards-compatible changes</t>
-               <t>There have been one or more new functionality which have been added in a backwards compatible-manner</t>
-               <t>There may also be bug fixes which have been made in a backwards-compatible manner</t>
-               </list></t>
-            <t>MAJOR and MINOR versions unchanged, PATCH version incremented by 1. This indicates that in revision N+1:
-               <list style="symbols">
-                  <t>There are no non-backwards-compatible changes</t>
-                  <t>There is no new functionality which has been added in a backwards compatible-manner</t>
-                  <t>There are no more bug fixes which have been made in a backwards-compatible manner</t>
-                  <t>There may be editorial changes such a change to a desctiption statement which does not change the semantics
-                     of the data node in any way.</t>
-               </list></t>
-         </list>
-      </t>
       <t>As explained in <xref target="implementation_experience"/>, while programatically determining a semantic version is possible
          using tools (e.g. the pyang utility), human overisght is highly recommended because of some special cases which can not be detected by tools.
          Therefore, a model author SHOULD use both means to determine a model's semantic version.</t>
@@ -859,7 +951,7 @@ of this specification.</t>
        <section title="Making non-backwards-compatible changes to a YANG module">
        <t>There are various valid situations where a YANG module has to be modified in a non-backwards-compatible way. Here are the different ways in which this can be done:
           <list style="symbols">
-             <t>If the server can support NBC versions of the YANG module simultaneously AND the clients support version selection, then the NBC changes MAY be done immediately. The clients would select the version which they support and the NBC change would have no impact on them.</t>
+             <t>If the server can support NBC versions of the YANG module simultaneously using version selection, then the NBC changes MAY be done immediately.  Clients would be required to select the version which they support and the NBC change would have no impact on them.</t>
              <t>When possible, NBC changes are done incrementally to provide clients time to adapt to NBC changes.</t>
           </list>
        </t>
@@ -916,29 +1008,21 @@ of this specification.</t>
        </section>
    </section>
    <section anchor="guidelines_clients" title="Guidelines to YANG model clients">
-      <t>Here are some guidelines for YANG model clients:
+     <t>Guidelines for clients of modules using YANG semantic versioning:
          <list style="symbols">
             <t>Clients SHOULD be liberal when processing data received from a server. For example, the server may have increased the range of an operational node causing the client to receive a value whch is outside the range of the YANG model revision it was coded against</t>
-            <t>Clients SHOULD look for status changes in new revisions of YANG models they support.</t>
+            <t>Clients SHOULD monitor changes to published YANG modules through their version numbers, and use appropriate tooling to understand the specific changes between module versions.  In particular, clients SHOULD NOT migrate to NBC versions of a module without first understanding the specifics of the NBC changes.</t>
             <t>Clients SHOULD plan to make changes to match published status changes. When a node's status changes from "current" to "deprecated", clients SHOULD plan to stop using that node in a timely fashion. When a node's status changes to "obsolete", clients MUST stop using that node.</t>
-            <t>A client SHOULD not use unknown NBC versions automatically</t>
          </list> 
       </t>
    </section>
 </section>
 
-<section anchor="yang_module" title="Semantic Version Extension YANG Module">
-  <t>
-    The extension and related ietf-yang-library changes described in this module are
-    defined in the YANG module below.
-  </t>
-  <t>TODO - Define a separate type (in a ietf-semver-types.yang) file
-  for the YANG semver field definition.  It would be useful for the YANG
-  library augmentation, and possibly in the packages definition if that
-  work progresses.</t>
-  <t>TODO - Update the semantic version text to update the main definition in this document</t>
+<section anchor="yang_modules" title="Semantic Version Extension YANG Modules">
   <t>
     <figure>
+      <preamble> YANG module with extensions for defining a module's
+      YANG semantic version number, and importing by version.</preamble>
       <artwork><![CDATA[
 <CODE BEGINS> file "[email-masked]"
 module ietf-semver {
@@ -1073,9 +1157,10 @@ module ietf-semver {
        statements.  Zero or one module-version statement is allowed
        per parent statement. No substatements are allowed.
 
-       'revision' statements in submodule MAY contain a
-       'module-version' statement for documentation purposes, but it
-       has no effect on the including module's semantic version.";
+       'revision' statements in submodules MAY contain a
+       'module-version' statement for documentation purposes, but
+       its meaning is undefined, and has no effect on the including
+       module's semantic version.";
     reference
       "draft-verdt-netmod-yang-semver: 
        YANG Semantic Versioning for Modules";
@@ -1135,7 +1220,9 @@ module ietf-semver {
 <CODE ENDS>
 ]]></artwork>
 </figure>
-    <figure>
+<figure>
+  <preamble>YANG module with augmentations to YANG Library to support
+  semantic version numbers.</preamble>
       <artwork><![CDATA[
 <CODE BEGINS> file "[email-masked]"
 module ietf-yl-semver {
@@ -1342,19 +1429,22 @@ module ietf-yl-semver {
 
 <section anchor="appendix" title="Appendix">
   <section anchor="open_issues" title="Open Issues">
-    <t>
+    <t>Open issues are being tracked at <eref target="https://github.com/netmod-wg/yang-ver-dt/issues"/>.  Currently open issues are:
+      
       <list style="symbols">
-        <t>Do we need a new version of YANG?
-          <vspace/>
-          While eventually this will fold into a new version, the belief is this solution can
-          work with extensions alone with an update to the <xref target="RFC7950"/> text concerning
-          module updates.</t>
-        <t>We could consider a new naming convention for module files. Today, module files
-          are named using a  [email-masked] notation.  We could consider module%semver.yang
-          or module#version.yang variants.
-          Re-using the '@' for version is not ideal, so another separator character should be used.
-          In this manner, both version and revision could be used.
-          </t>
+        <t>Do we need a new version of YANG? <eref target="https://github.com/netmod-wg/yang-ver-dt/issues/14">#14</eref></t>
+	<t>Add guidance text about warning NBC changes might break imports <eref target="https://github.com/netmod-wg/yang-ver-dt/issues/11">#11</eref></t>
+	<t>Add a naming convention for versioned YANG file<eref target="https://github.com/netmod-wg/yang-ver-dt/issues/13">#13</eref></t>
+	<t>Define editorial, bc, nbc impact of adding, changing, removing extension stmts<eref target="https://github.com/netmod-wg/yang-ver-dt/issues/12">#12</eref></t>
+	<t>How to version modules in IETF drafts (after they have been published at 1.0.0 or later<eref target="https://github.com/netmod-wg/yang-ver-dt/issues/10">#10</eref></t>
+	<t>The solution does not strictly support semver 2.0.0<eref target="https://github.com/netmod-wg/yang-ver-dt/issues/9">#9</eref></t>
+	<t>Are whitespace changes allow between two module instances with the same version (or revision)?<eref target="https://github.com/netmod-wg/yang-ver-dt/issues/8">#8</eref></t>
+	<t>Do we assume that a module has an implicit semver if none as been specified?<eref target="https://github.com/netmod-wg/yang-ver-dt/issues/7">#7</eref></t>
+	<t>Is changing the ordering of nodes an NBC change?<eref target="https://github.com/netmod-wg/yang-ver-dt/issues/6">#6</eref></t>
+	<t>Should version statement be at top level or under revision statement?<eref target="https://github.com/netmod-wg/yang-ver-dt/issues/5">#5</eref></t>
+	<t>Figure out whether changing the imports constitute a BC or NBC change<eref target="https://github.com/netmod-wg/yang-ver-dt/issues/4">#4</eref></t>
+	<t>Does BC or NBC depend on whether the node is config true/false?<eref target="https://github.com/netmod-wg/yang-ver-dt/issues/15">#15</eref></t>
+	<t>Status obsolete nodes<eref target="https://github.com/netmod-wg/yang-ver-dt/issues/2">#2</eref></t>
       </list>
     </t>
   </section>
diff --git a/yang-semver/ietf-semver.yang b/yang-semver/ietf-semver.yang
index 6efd5e8..4842004 100644
--- a/yang-semver/ietf-semver.yang
+++ b/yang-semver/ietf-semver.yang
@@ -130,9 +130,10 @@ module ietf-semver {
        statements.  Zero or one module-version statement is allowed
        per parent statement. No substatements are allowed.
 
-       'revision' statements in submodule MAY contain a
-       'module-version' statement for documentation purposes, but it
-       has no effect on the including module's semantic version.";
+       'revision' statements in submodules MAY contain a
+       'module-version' statement for documentation purposes, but
+       its meaning is undefined, and has no effect on the including
+       module's semantic version.";
     reference
       "draft-verdt-netmod-yang-semver: 
        YANG Semantic Versioning for Modules";