[Docs] [txt|pdf|xml|html] [Tracker] [Email] [Diff1] [Diff2] [Nits]

Versions: (draft-clacla-netmod-yang-model-update) 00 01

Network Working Group                                          B. Claise
Internet-Draft                                                 J. Clarke
Updates: 7950 (if approved)                                    R. Rahman
Intended status: Standards Track                          R. Wilton, Ed.
Expires: September 12, 2019                          Cisco Systems, Inc.
                                                              B. Lengyel
                                                                Ericsson
                                                               J. Sterne
                                                                   Nokia
                                                              K. D'Souza
                                                                    AT&T
                                                          March 11, 2019


                  YANG Semantic Versioning for Modules
                   draft-verdt-netmod-yang-semver-00

Abstract

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

Status of This Memo

   This Internet-Draft is submitted in full conformance with the
   provisions of BCP 78 and BCP 79.

   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 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 12, 2019.

Copyright Notice

   Copyright (c) 2019 IETF Trust and the persons identified as the
   document authors.  All rights reserved.





Claise, et al.         Expires September 12, 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
   (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
   include Simplified BSD License text as described in Section 4.e of
   the Trust Legal Provisions and are provided without warranty as
   described in the Simplified BSD License.

Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   3
     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  . . . . . . . . . . . . . . . . . .   6
     2.1.  Classification of changes between module revisions  . . .   6
     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  . . . . . . . . . . . . . . . . . . . . . . .  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 12, 2019               [Page 2]


Internet-Draft           YANG Module Versioning               March 2019


   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

   This document defines a solution to the YANG module lifecycle
   problems described in [I-D.verdt-netmod-yang-versioning-reqs],
   covering all of the specified requirements except for requirements:
   2.2, 3.1, and 3.2.

   Specifically, this document recognises a need to sometimes allow YANG
   modules to evolve with non-backwards-compatible changes, which might
   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 seven parts:

      A definition for the YANG semantic versioning scheme for modules,
      and an explanation of how the semver extension can be used to
      annotate modules with their semantic version number.

      A YANG extension to allow YANG module imports to be restricted to
      modules with particular semantic versions, allowing inter-module
      version dependencies to be captured within YANG module
      definitions.

      Updates to the YANG 1.1 module update rules to accommodate the
      semantic versioning scheme.

      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 server, and to
      clarify how module imports are resolved when multiple versions
      could otherwise be chosen.





Claise, et al.         Expires September 12, 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 tracked at
   <https://github.com/netmod-wg/yang-ver-dt/issues>.

1.1.  Updates to YANG RFCs

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 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
   YANG language.  It is believed that the extensions as they are
   defined can coexist with existing YANG 1.1 clients.

   o  Section 4 describes modification to the [RFC7950] Section 11
      module update text to advise the use of semantic versioning as
      described in this document.

   o  Section 3 describes an extension to do import by semantic version.

   o  Section 6 defines an extension that adds a description child
      element to the YANG "status" statement.

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.






Claise, et al.         Expires September 12, 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
   versioning requirements are intended to be holistically addressed and
   is intended to be removed if this draft is adopted by the WG.

   As stated previously, this draft does not address requirements 2.2,
   3.1 and 3.2 of the requirements specified in
   [I-D.verdt-netmod-yang-versioning-reqs].  Instead, additional work is
   needed to address those requirements, which the design team believes
   would be best addressed in separate drafts.  It is hoped that the WG
   agrees that viable solutions to the other requirements exist that
   complement the solution proposed in this draft, and thus this work
   can usefully progress in parallel.  In particular, there is value to
   the industry to achieve standardization of a partial solution that
   addresses the majority, but not all, of the stated requirements, on
   the agreement that a full solution will follow.

   The two additional drafts are:

   A tooling based solution is proposed for requirement 2.2, that allows
   two YANG schema versions to be algorithmically compared, with the
   algorithm reporting the list of differences between the two YANG
   schema and whether each change is regarded as being editorial,
   backwards-compatible, or non-backwards-compatible.  Annotations to
   the YANG modules, via the use of extension statements, may help
   improve the accuracy of the comparison algorithm, particularly for
   statements that are very hard for an algorithm to correctly classify
   the scope of any differences (e.g., a change in the semantic
   behaviour of a data node defined via modifications to the associated
   YANG description statement).  Given that requirement 2.2 is a soft
   requirement (SHOULD rather than MUST), and practical experience with
   the tooling is required, it is proposed that this work is deferred at
   this time.

   A proposed solution for requirements 3.1 and 3.2 is via the use of
   YANG packages [I-D.rwilton-netmod-yang-packages] and a protocol based
   version selection scheme that can be used by clients to choose a
   particular YANG datastore schema from the set of datastore schema
   that are supported by the server.




Claise, et al.         Expires September 12, 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 the
   module's 'include' statements MUST specify the revision-date for each
   of the included submodules.

2.1.  Classification of changes between module revisions

   The principle aim of YANG semantic versioning is to allow a user of a
   YANG module to understand the overall significance of any changes
   between two module revisions solely based on the semantic version
   number.

   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'.  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
      'semver:version' statements and their substatements, the only
      remaining changes are insignificant white space changes.

      An 'editorial' module semantic version change is where there 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.

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

      A 'non-backwards-compatible' module semantic version change is
      where some syntax or semantic changes exists between the two




Claise, et al.         Expires September 12, 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
      module lifecyles that cannot be addressed using the semver.org
      2.0.0 versioning scheme alone.

      Unlike the semver.org 2.0.0 versioning scheme, the YANG 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.

      Module definitions that follow the semver.org 2.0.0 versioning
      scheme are fully compatible with implementations that understand
      the YANG semantic versioning scheme.

      If module updates are always restricted to the latest version of
      the module only, then the version numbers used by the YANG
      semantic versioning scheme are exactly the same as those defined
      by the semver.org 2.0.0 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:

      The module MUST include at least one revision statement.

      The most recent module revision statement MUST include a
      'semver:module-version' sub-statement, that defines the module's
      YANG semantic version.

      The preceding module revision statement SHOULD also include a
      'semver:module-version' sub-statement, to allow the module's
      semantic version history to be derived.

      All other revision statements MAY include a 'semver:module-
      version' sub-statement if they have an associated YANG semantic
      version.





Claise, et al.         Expires September 12, 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
   suffix: 'm' or 'M'.

   o  'X' is the MAJOR version.  Changes in the major version number
      indicate changes that are non-backwards-compatible to versions
      with a lower major version number.

   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
      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
      non-backwards-compatible changes relative to versions with the
      same major and minor version numbers, but lower patch version
      number, depending on what form modifier 'v' takes:

      *  If the modifier letter is absent, the change represents an
         editorial change

      *  'm' - the change represents a backwards-compatible change

      *  'M' - the change represents a non-backwards-compatible change

   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.









Claise, et al.         Expires September 12, 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 12, 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

   When a new revision of a module is produced, then the following rules
   define how the YANG semantic version number for the new module
   revision is calculated, based on the changes between the two module
   revisions, and the YANG semantic version number of the base module
   revision that the changes are derived from.  A two step process is
   used:

   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 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 12, 2019              [Page 10]


Internet-Draft           YANG Module Versioning               March 2019


   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.

   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:

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

       ii    "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".

   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:

       i     "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".

       iii   "X.Y.ZM" - the module version MUST be updated to
             "X.Y.Z+1M".

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

           extension module-version {
             argument semver;
           }



Claise, et al.         Expires September 12, 2019              [Page 11]


Internet-Draft           YANG Module Versioning               March 2019


   The extension would typically be used this way:

       module yang-module-name {

         namespace "name-space";
         prefix "prefix-name";

         import ietf-semver { prefix "semver"; }

         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";
           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 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 "Add new functionality, leaf 'foo'";
           semver:module-version "1.1.0";
         }

         revision 2017-04-03 {



Claise, et al.         Expires September 12, 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 version";
           semver:module-version "0.1.0";
         }

         //YANG module definition starts here

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

3.  Import by Semantic Version

   RFC 7950 allows YANG module 'import' statements to optionally require
   the imported module to have a particular revision date.  In practice,
   importing a module with an exact revision date is overly burdensome
   because it requires the importing module to be updated whenever any
   change to the imported module occurs.  The alternative choice of
   using an import statement without a revision date is also not ideal
   because the importing module may not work with all possible revisions
   of the imported module.

   With semantic versioning, it is desirable for a importing module to
   specify the set of module versions of the imported module that are
   anticipated to be compatible.

   This document specifies a YANG extension for selecting which versions
   of a module may be imported.  It is designed around the assumption
   that most changes to a YANG module do not break importing modules,
   even if the changes themselves are not backwards compatible.  E.g.,
   fixing an incorrect pattern statement or description for a leaf would
   not break an import, changing the name of a leaf could break an
   import but frequently would not, but removing a container would break
   imports if it is augmented by another module.

   The ietf-semver module defines the 'version' extension, a
   substatement to the YANG 'import' statement.




Claise, et al.         Expires September 12, 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:

   1.  "A.B.C" - import the exact module version that matches "A.B.C".

   2.  "A.B.C+" - import any module version that matches, or is greater
       than, "A.B.C".

   3.  "A.B.C-X.Y.Z" - import any module version that matches, or is
       greater than, "A.B.C"; and also matches, or is less than,
       "X.Y.Z".  The word "MAX" can be used for 'Y' or 'Z' to represent
       the numerical value 32,767.

   The rules for comparing module version numbers are as follows:

   1.  Version "R.S.T" matches version "A.B.C", only if

          R = A, S = B, and T = C

   2.  Version "R.S.T" is greater than version "A.B.C", only if

          R = A, S = B, and T > C; or

          R = A and S > B; or

          R > A

   3.  Version "R.S.T" is less than version "X.Y.Z", only if

          R = X, S = Y, and T < Z; or

          R = X and S < Y; or

          R < X

   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 12, 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, 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
   incompatible with other versions.

   import example-module {
     semver:version 1.1.2;
   }

   The next example selects module versions that match, or are 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'.

   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.2.0+;
   }

   The next example selects module versions that match, or are 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.

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





Claise, et al.         Expires September 12, 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;
   }

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':

   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.

   o  Adding or updating 'reference' statements.

   o  Adding or updating the 'organization' statement.

   o  Adding a new 'revision' or 'semver:module-version' statement, or
      correcting a previous 'revision' or 'semver:module-version'
      statement.

   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:

   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 12, 2019              [Page 16]


Internet-Draft           YANG Module Versioning               March 2019


   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.

   o  Changing the name, type, or units of a data node.

   o  Modifying the description in a way that changes the semantic
      meaning of the data node.

   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.

   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.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'
   list, with the requirement from [RFC7950] that only a single revision
   of a YANG module may be implemented.

   If a YANG module import statement does not specify a specific version
   or revision within the datastore schema then it could be ambiguous as



Claise, et al.         Expires September 12, 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
   datastore schema actually used by the server.

   The following rules remove the ambiguity:

   If a module import statement could resolve to more than one module
   revision defined in the datastore schema, and one of those revisions
   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.

   If a module import statement could resolve to more than one module
   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 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.

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
   status 'obsolete' nodes.  The leaves are:

   deprecated-nodes-implemented:  If present, this leaf indicates that
      all schema nodes with a status 'deprecated' child statement are
      implemented equivalently as if they had status 'current', or
      otherwise deviations MUST be used to explicitly remove
      'deprecated' nodes from the schema.  If this leaf is absent then
      the behavior is unspecified.

   obsolete-nodes-absent:  If present, this leaf indicates that the
      server does not implement any status 'obsolete' nodes.  If this
      leaf is absent then the behaviour is unspecified.

   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 require
   that this is how servers handle 'deprecated' and 'obsolete' nodes to
   comply with YANG module semantic versioning.



Claise, et al.         Expires September 12, 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
   compatible, and MUST also consider whether the status of any nodes
   has changed to 'deprecated' and whether those nodes are implemented
   by the server.

6.  YANG status description extension

   The ietf-semver module specifies the YANG extension 'status-
   description' that can be used as a substatement of the status
   statement.  The argument to this extension can contain freeform text
   to help readers of the module understand why the node was deprecated
   or made obsolete, when it is anticipated that the node will no longer
   be available for use, and potentially reference other schema elements
   that can be used instead.  An example is shown below.

   leaf imperial-temperature {
     type int64;
     units "degrees Fahrenheit";
     status deprecated {
       semver:status-description
         "Imperial measurements are being phased out in favor
          of their metric equivalents.  Use metric-temperature
          instead.";
     }
     description
       "Temperature in degrees Fahrenheit.";
   }

7.  Semantic versioning of YANG instance data

   Instance data sets [I-D.ietf-netmod-yang-instance-file-format] do not
   have an associated YANG semantic version, as compatibility for
   instance data is undefined.

   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]).

   In this way, the versioning of a schema associated with an instance
   data set, may allow a client to determine whether the instance data
   could also be used in conjunction with other versions of the YANG
   schema, or other versions of the modules that define the schema.

   One common scenario, where instance data may have to cope with
   changes to the schema is for the <startup> datastore when a server is



Claise, et al.         Expires September 12, 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 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.

   The use of status "deprecated" with the status-description statement
   allows clients to plan a migration to alternative data nodes.

   When NBC changes are introduced, consideration should be given to the
   impact on clients and YANG model authors SHOULD try to mitigate that
   impact.

8.1.1.  Use of YANG semantic versioning

   Module authors should use the following guidance when applying the
   module version update rules specified in Section 2.3.

   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.

   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 is necessary to make such changes
   then the following guidelines apply:

      Any changes SHOULD also be made to a new latest version of the
      YANG module, if appropriate.

      Where possible, changes SHOULD be restricted to backwards-
      compatible changes only.






Claise, et al.         Expires September 12, 2019              [Page 20]


Internet-Draft           YANG Module Versioning               March 2019


      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.

   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.

   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 able 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),
   human oversight 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.

8.1.2.  Making non-backwards-compatible changes to a YANG module

   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:

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

   o  When possible, NBC changes are done incrementally to provide
      clients time to adapt to NBC changes.

   Here are some guidelines on how non-backwards compatible changes can
   be made incrementally:

   1.  The changes should be made incrementally, e.g. a data node's
       status SHOULD NOT be changed directly from "current" to
       "obsolete" (see Section 4.7 of [RFC8407]), instead the status
       SHOULD first be marked "deprecated" and then when support is
       removed its status MUST be changed to "obsolete".  Instead of
       using the "obsolete" status, the data node MAY be removed from
       the model but this has the risk of breaking modules which import
       the modified module.



Claise, et al.         Expires September 12, 2019              [Page 21]


Internet-Draft           YANG Module Versioning               March 2019


   2.  A node with status "deprecated" MUST be supported for the
       solution described here to function properly.

   3.  A node with status "deprecated" SHOULD be available for at least
       one year before its status is changed to "obsolete", see
       Section 4.7 of [RFC8407].

   4.  Support for a node which is "obsolete" is indicated by the node
       "obsolete-nodes-present, see Section 5.

   5.  The new extension "status-description" SHOULD be used for nodes
       which are "obsolete" or "deprecated".

   6.  For status "deprecated", the "status-description" SHOULD also
       indicate until when support for the node is guaranteed.  If there
       is a replacement data node, rpc, action or notification for the
       deprecated node, this SHOULD be stated in the "status-
       description".

   7.  When obsoleting or deprecating data nodes, the "deprecated" or
       "obsolete" status SHOULD be applied at the highest possible level
       in the data tree.  For example, when deprecating all data nodes
       in a container, the "deprecated" status SHOULD be applied to the
       container.  For clarity, the status MAY be added in all the
       affected nodes but the status-description SHOULD be added only at
       the highest level in the tree.

   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 12, 2019              [Page 22]


Internet-Draft           YANG Module Versioning               March 2019


8.1.2.2.  Changing the type of a leaf node

   Changing the type of a leaf-node. e.g. consider a "vpn-id" node of
   type integer being changed to a string:

   1.  The status of node "vpn-id" SHOULD be changed to "deprecated" and
       the node SHOULD be available for at least one year.  This is a
       backwards-compatible change.

   2.  A new node, e.g. "vpn-name", of type string is added to the same
       location as the existing node "vpn-id".  This new node has status
       "current" and its description SHOULD explain that it is replacing
       node "vpn-id".

   3.  During the period of time where both nodes are available, how the
       server behaves when either node is set is outside the scope of
       this document and will vary on a case by case basis.  Here are
       some options:

       1.  A server MAY prevent the new node from being set if the old
           node is already set (and vice-versa).  The new node MAY have
           a when statement to achieve this.  The old node MUST NOT have
           a when statement since this would be a non-backwards-
           compatible change, but the server MAY reject the old node
           from being set if the new node is already set.

       2.  If the new node is set and a client does a get or get-config
           operation on the old node, the server MAY map the value.  For
           example, if the new node "vpn-name" has value "123" then the
           server MAY return integer value 123 for the old node "vpn-
           id".  However, if the value can not be mapped, we need a way
           of returning "unsupported" TBD.

   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.

8.1.2.3.  Reducing the range of a leaf node

8.1.2.4.  Changing the key of a list

8.1.2.5.  Renaming a node

8.1.2.6.  Changing a default value







Claise, et al.         Expires September 12, 2019              [Page 23]


Internet-Draft           YANG Module Versioning               March 2019


8.2.  Guidelines to 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 which is
      outside the range of the YANG model revision it was coded against

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

9.  Semantic Version Extension YANG Modules

   YANG module with extensions for defining a module's YANG semantic
   version number, and importing by version.

   <CODE BEGINS> file "ietf-semver@2019-02-07.yang"
   module ietf-semver {
     yang-version 1.1;
     namespace "urn:ietf:params:xml:ns:yang:ietf-semver";
     prefix semver;

     organization
       "IETF NETMOD (Network Modeling) Working Group";
     contact
       "WG Web:   <https://datatracker.ietf.org/wg/netmod/>
        WG List:  <mailto:netmod@ietf.org>

        Author:   Benoit Claise
                  <mailto:bclaise@cisco.com>

        Author:   Joe Clarke
                  <mailto:jclarke@cisco.com>

        Author:   Reshad Rahman
                  <mailto:rrahman@cisco.com>

        Author:   Robert Wilton



Claise, et al.         Expires September 12, 2019              [Page 24]


Internet-Draft           YANG Module Versioning               March 2019


                  <mailto:rwilton@cisco.com>

        Author:   Kevin D'Souza
                  <mailto:kd6913@att.com>

        Author:   Balazs Lengyel
                  <mailto:balazs.lengyel@ericsson.com>

        Author:   Jason Sterne
                  <mailto:jason.sterne@nokia.com>";
     description
       "This module contains a definition for a YANG 1.1 extension to
        express the semantic version of YANG modules.";

     revision 2019-02-27 {
       description
         "* Move YANG library augmentations into a separate module.
          * Update references.";
       reference
         "draft-verdt-netmod-yang-semver:
          YANG Semantic Versioning for Modules";
       semver:module-version "0.3.0";
     }

     revision 2018-04-05 {
       description
         "* Properly import ietf-yang-library.
          * Fix the name of module-semver => module-version.
          * Fix regular expression syntax.
          * 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.
          * Add an extension status-description to track deprecated
            and obsolete reasons.
          * Fix yang-library augments to use 7895bis.";
       reference
         "draft-clacla-netmod-yang-model-update:
          New YANG Module Update Procedure";
       semver:module-version "0.2.1";
     }
     revision 2017-12-15 {
       description
         "Initial revision.";
       reference
         "draft-clacla-netmod-yang-model-update:
          New YANG Module Update Procedure";
       semver:module-version "0.1.1";
     }



Claise, et al.         Expires September 12, 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)?';
       }
       description
         "The type used to represent a YANG semantic version number.

         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 suffix: 'm' or 'M'.

         o 'X' is the MAJOR version.  Changes in the major version
           number indicate changes that are non-backwards-compatible to
           versions with a lower major version number.

         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.

        o 'Zv' is the PATCH version and modifier.  Changes in the patch
           version number can indicate editorial, backwards-compatible,
           or non-backwards-compatible changes relative to versions with
           the same major and minor version numbers, but lower patch
           version number, depending on what form modifier 'v' takes:

           *  'M' - the change represents a non-backwards-compatible
                    change

           *  'm' - the change represents a backwards-compatible change

           * If the modifier letter is absent, the change represents an
             editorial change";

       reference
         "draft-verdt-netmod-yang-semver: YANG Semantic Versioning";
     }

     extension module-version {
       argument semver;
       description
         "The version number for the module revision it is used in.

          This format of the argument matches the type version.

          The rules for updating the module-version number are described
          in section XXX of 'YANG Semantic Versioning for Modules';



Claise, et al.         Expires September 12, 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
          features have been added to a newer revision.

          If a module contains this extension it indicates that for this
          module the updated status and update rules as this described
          in RFC XXXX are used.

          The statement MUST only be a substatement of the 'revision'
          statements.  Zero or one module-version statement is allowed
          per parent statement. No substatements are allowed.

          '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";
     }

     extension import-versions {
       argument version-clause;
       description
         "This extension specifies an acceptable set of semantic
          versions of a given module that may be imported.

          The statement MUST only be a substatement of the import
          statement.

          The statement MUST NOT be present if the import has a
          revision-date substatement.

          The statement MUST NOT be present if the imported module does
          not support semantic versioning.

          Zero or more versions statements are allowed per parent
          statement.  No substatements are allowed.

          The version-clause argument MUST follow one of the below
            patterns:
              (i)  "+' \d+\.\d+\.\d+ '+"
                Matches exact version, e.g. 3.6.1

              (ii) "+ '\d+\.\d+\.\d+\+ '+"
                Matches exact version or greater, e.g. 3.6.1+




Claise, et al.         Expires September 12, 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";

       reference
         "draft-verdt-netmod-yang-semver: Import by Semantic Version";
     }

     extension status-description {
       argument description;
       description
         "Freeform text that describes why a given node has been
          deprecated or made obsolete.  This may point to other schema
          elements that can be used in lieu of the given node.

          This statement MUST only be used as a substatement of the
          status statement

          Zero or more status-description statements are allowed per
          parent statement.  No substatements are allowed.";
       reference
         "draft-verdt-netmod-yang-semver: YANG status description
          extension";
     }
   }
   <CODE ENDS>

   YANG module with augmentations to YANG Library to support semantic
   version numbers.

   <CODE BEGINS> file "ietf-yl-semver@2019-02-07.yang"
   module ietf-yl-semver {
     yang-version 1.1;
     namespace "urn:ietf:params:xml:ns:yang:ietf-yl-semver";
     prefix yl-semver;

     import ietf-semver {
       prefix semver;
     }

     import ietf-yang-library {
       prefix yanglib;
     }

     organization
       "IETF NETMOD (Network Modeling) Working Group";
     contact
       "WG Web:   <https://datatracker.ietf.org/wg/netmod/>



Claise, et al.         Expires September 12, 2019              [Page 28]


Internet-Draft           YANG Module Versioning               March 2019


        WG List:  <mailto:netmod@ietf.org>

        Author:   Benoit Claise
                  <mailto:bclaise@cisco.com>

        Author:   Joe Clarke
                  <mailto:jclarke@cisco.com>

        Author:   Reshad Rahman
                  <mailto:rrahman@cisco.com>

        Author:   Robert Wilton
                  <mailto:rwilton@cisco.com>

        Author:   Kevin D'Souza
                  <mailto:kd6913@att.com>

        Author:   Balazs Lengyel
                  <mailto:balazs.lengyel@ericsson.com>

        Author:   Jason Sterne
                  <mailto:jason.sterne@nokia.com>";
     description
       "This module contains augmentations to YANG Library to add module
        level semantic version numbers and to provide an indication of
        how deprecated and obsolete nodes are handled by the server.";

       semver:module-version "0.1.0";

     revision 2019-02-27 {
       description
         "Moved YANG library augmentations into a separate module.";
       reference
         "draft-verdt-netmod-yang-semver:
          YANG Semantic Versioning for Modules";
       semver:module-version "0.1.0";
     }

     augment "/yanglib:yang-library/yanglib:module-set/yanglib:module" {
       description
         "Augmentation modules with a semantic version.";
       leaf version {
         type semver:version;
         description
           "The semantic version for this module.  The version MUST
            match the semver:version value in specific revision of the
            module loaded in this module-set.";
         reference



Claise, et al.         Expires September 12, 2019              [Page 29]


Internet-Draft           YANG Module Versioning               March 2019


           "draft-verdt-netmod-yang-semver: YANG Semantic Versioning";
       }
     }

     augment "/yanglib:yang-library/yanglib:schema" {
       description
         "Augmentations to the ietf-yang-library module to indicate how
          deprecated and obsoleted nodes are handled for each datastore
          schema supported by the server.";

       leaf deprecated-nodes-implemented {
         type empty;
         description
           "If present, this leaf indicates that all schema nodes with a
            status 'deprecated' child statement are implemented
            equivalently as if they had status 'current', or otherwise
            deviations MUST be used to explicitly remove 'deprecated'
            nodes from the schema.  If this leaf is absent then the
            behavior is unspecified.";
         reference
           "draft-verdt-netmod-yang-semver: Reporting how deprecated and
            obsolete nodes are handled";
       }
       leaf obsolete-nodes-absent {
         type empty;
         description
           "If present, this leaf indicates that the server does not
            implement any status 'obsolete' nodes.  If this leaf is
            absent then the behaviour is unspecified.";
         reference
           "draft-verdt-netmod-yang-semver: Reporting how deprecated and
            obsolete nodes are handled";
       }
     }
   }
   <CODE ENDS>

10.  Contributors

   This document grew out of the YANG module versioning design team that
   started after IETF 101.  The design team consists of the following
   members whom have worked on the YANG versioning project:

   o  Balazs Lengyel

   o  Benoit Claise

   o  Ebben Aries



Claise, et al.         Expires September 12, 2019              [Page 30]


Internet-Draft           YANG Module Versioning               March 2019


   o  Jason Sterne

   o  Joe Clarke

   o  Juergen Schoenwaelder

   o  Mahesh Jethanandani

   o  Michael (Wangzitao)

   o  Qin Wu

   o  Reshad Rahman

   o  Rob Wilton

   The initial revision of this document was refactored and built upon
   [I-D.clacla-netmod-yang-model-update].

   Discussons on the use of Semver for YANG versioning has been held
   with authors of the OpenConfig YANG models.  We would like thank both
   Anees Shaikh and Rob Shakir for their input into this problem space.

11.  Security Considerations

   The document does not define any new protocol or data model.  There
   are no security impacts.

12.  IANA Considerations

12.1.  YANG Module Registrations

   The following YANG module is requested to be registred in the "IANA
   Module Names" registry:

   The ietf-semver module:

      Name: ietf-semver

      XML Namespace: urn:ietf:params:xml:ns:yang:ietf-semver

      Prefix: semver

      Reference: [RFCXXXX]

   The ietf-yl-semver module:

      Name: ietf-yl-semver



Claise, et al.         Expires September 12, 2019              [Page 31]


Internet-Draft           YANG Module Versioning               March 2019


      XML Namespace: urn:ietf:params:xml:ns:yang:ietf-yl-semver

      Prefix: yl-semver

      Reference: [RFCXXXX]

13.  References

13.1.  Normative References

   [I-D.verdt-netmod-yang-versioning-reqs]
              Clarke, J., "YANG Module Versioning Requirements", draft-
              verdt-netmod-yang-versioning-reqs-02 (work in progress),
              November 2018.

   [RFC7895]  Bierman, A., Bjorklund, M., and K. Watsen, "YANG Module
              Library", RFC 7895, DOI 10.17487/RFC7895, June 2016,
              <https://www.rfc-editor.org/info/rfc7895>.

   [RFC7950]  Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language",
              RFC 7950, DOI 10.17487/RFC7950, August 2016,
              <https://www.rfc-editor.org/info/rfc7950>.

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

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

13.2.  Informative References

   [I-D.clacla-netmod-model-catalog]
              Clarke, J. and B. Claise, "YANG module for
              yangcatalog.org", draft-clacla-netmod-model-catalog-03
              (work in progress), April 2018.

   [I-D.clacla-netmod-yang-model-update]
              Claise, B., Clarke, J., Lengyel, B., and K. D'Souza, "New
              YANG Module Update Procedure", draft-clacla-netmod-yang-
              model-update-06 (work in progress), July 2018.







Claise, et al.         Expires September 12, 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-
              claise-semver-02 (work in progress), January 2018.

   [I-D.ietf-netmod-yang-instance-file-format]
              Lengyel, B. and B. Claise, "YANG Instance Data File
              Format", draft-ietf-netmod-yang-instance-file-format-02
              (work in progress), February 2019.

   [I-D.openconfig-netmod-model-catalog]
              Shaikh, A., Shakir, R., and K. D'Souza, "Catalog and
              registry for YANG models", draft-openconfig-netmod-model-
              catalog-02 (work in progress), March 2017.

   [I-D.rwilton-netmod-yang-packages]
              Wilton, R., "YANG Packages", draft-rwilton-netmod-yang-
              packages-00 (work in progress), December 2018.

   [openconfigsemver]
              "Semantic Versioning for Openconfig Models",
              <http://www.openconfig.net/docs/semver/>.

   [semver]   "Semantic Versioning 2.0.0", <https://www.semver.org>.

   [yangcatalog]
              "YANG Catalog", <https://yangcatalog.org>.

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

   [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 12, 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

   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 12, 2019              [Page 34]


Internet-Draft           YANG Module Versioning               March 2019


A.2.  Derived Semantic Version

   This temporary text is intended to be moved to a separate draft the
   describes the tool based approach for versioning YANG modules
   mentioned in Section 1.2.

A.2.1.  The Derived Semantic Version

   If an explicitly defined semantic version is not available in the
   YANG module, it is possible to algoritmically calculate a derived
   semantic version.  This can be used for modules not containing a
   definitive semantic-version as defined in this document or as a
   starting value when specifying the definitive semantic-version.  Be
   aware that this algorithm may sometimes incorrectly classify changes
   between the categories non-compatible, compatible or error-
   correction.

A.2.2.  Implementation Experience

   [yangcatalog] uses the pyang utility to calculate the derived-
   semantic-version for all of the modules contained within the catalog.
   [yangcatalog] contains many revisions of the same module in order to
   provide its derived-semantic-version for module consumers to know
   what has changed between revisions of the same module.

   Two distinct leafs in the YANG module
   [I-D.clacla-netmod-model-catalog] contain this semver notation:

   o  the semantic-version leaf contains the value embedded within a
      YANG module (if it is available).

   o  the derived-semantic-version leaf is established by examining the
      the YANG module themselves.  As such derived-semantic-version only
      takes syntax into account as opposed to the meaning of various
      elements when it computes the semantic version.

   o  The algorithm used to produce the derived-semantic-version is as
      follows:

      1.  Order all modules of the same name by revision from oldest to
          newest.  Include module revisions that are not available, but
          which are defined in the revision statements in one of the
          available module versions.

      2.  If module A, revision N+1 has failed compilation, bump its
          derived semantic MAJOR version.  For unavailable module
          versions assume non-backward compatible changes were done.,
          thus bump its derived semantic MAJOR version.



Claise, et al.         Expires September 12, 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.

      4.  If backward-incompatible changes exist, bump module A,
          revision N+1's derived MAJOR semantic version.

      5.  If no backward-incompatible changes exist, compare the pyang
          trees of module A, revision N and revision N+1.

      6.  If there are structural differences (e.g., new nodes), bump
          module A, revision N+1's derived MINOR semantic version.

      7.  If no structural differences exist, bump module A, revision
          N+1's derived PATCH semantic version.

   The pyang utility checks many of the points listed in section 11 of
   [RFC7950] for known module incompatibilities.  While this approach is
   a good way to programmatically obtain a semantic version number, it
   does not address all cases whereby a major version number might need
   to be increased.  For example, a node may have the same name and same
   type, but its meaning may change from one revision of a module to
   another.  This represents a semantic change that breaks backward
   compatibility, but the above algorithm would not find it.  Therefore,
   additional, sometimes manual, rigor must be done to ensure a proper
   version is chosen for a given module revision.

Authors' Addresses

   Benoit Claise
   Cisco Systems, Inc.
   De Kleetlaan 6a b1
   1831 Diegem
   Belgium

   Phone: +32 2 704 5622
   Email: bclaise@cisco.com


   Joe Clarke
   Cisco Systems, Inc.
   7200-12 Kit Creek Rd
   Research Triangle Park, North Carolina
   United States of America

   Phone: +1-919-392-2867
   Email: jclarke@cisco.com




Claise, et al.         Expires September 12, 2019              [Page 36]


Internet-Draft           YANG Module Versioning               March 2019


   Reshad Rahman
   Cisco Systems, Inc.

   Email: rrahman@cisco.com


   Robert Wilton (editor)
   Cisco Systems, Inc.

   Email: rwilton@cisco.com


   Balazs Lengyel
   Ericsson
   Magyar Tudosok Korutja
   1117 Budapest
   Hungary

   Phone: +36-70-330-7909
   Email: balazs.lengyel@ericsson.com


   Jason Sterne
   Nokia

   Email: jason.sterne@nokia.com


   Kevin D'Souza
   AT&T
   200 S. Laurel Ave
   Middletown, NJ
   United States of America

   Email: kd6913@att.com
















Claise, et al.         Expires September 12, 2019              [Page 37]


Html markup produced by rfcmarkup 1.129c, available from https://tools.ietf.org/tools/rfcmarkup/