Re: [Netmod-ver-dt] YANG Module Semver doc updates

[Ebben Aries <[e-mail]>]

Turns out I have an overlap during the meeting tomorrow and won't be
able to dial-in.  Will revert back on (d) in the next few days

On Jan 14 15:02 PM, Robert Wilton wrote:
> Hi,
> 
> Heads up that I have pushed an updated version of
> draft-verdt-netmod-yang-semver-00.  Primarily, this contains my initial
> updates to section 3 on YANG semantic versioning.  Adding some
> examples/diagrams may help this section greatly, but otherwise comments are
> welcome.
> 
> From the meeting on Thursday, I think that the following updates were
> agreed:
> 
> a) Restructure the intro sections -  Joe[but I know you have already had a
> first pass at this]
> b) Define YANG semver rules - Rob
> c) Update/simplify "imports by revision" - was this Joe or Balazs?
> d) 5. Updates to YANG 1.1 Module Update Rules, 6. Updates to
> ietf-yang-library, 7. Deprecated and Obsolete Reasons - Ebben was going to
> take a look a these.
> e) Guidelines 8.1. Guidelines to YANG model authors 8.2. Guidelines to YANG
> model clients - Reshad
> 
> Thanks,
> Rob
> 
> [A copy of the doc after my updates is attached]
> 

> 
> 
> 
> 
> Network Working Group                                          B. Claise
> Internet-Draft                                                 J. Clarke
> Updates: 7950 (if approved)                          Cisco Systems, Inc.
> Intended status: Standards Track                              B. Lengyel
> Expires: July 18, 2019                                          Ericsson
>                                                               K. D'Souza
>                                                                     AT&T
>                                                         January 14, 2019
> 
> 
>                     New YANG Module Update Procedure
>                    draft-verdt-netmod-yang-semver-00
> 
> Abstract
> 
>    This document specifies a new YANG module update procedure in case of
>    backward-incompatible changes, as an alternative proposal to the YANG
>    1.1 specifications.  This document updates RFC 7950.
> 
> 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 July 18, 2019.
> 
> Copyright Notice
> 
>    Copyright (c) 2019 IETF Trust and the persons identified as the
>    document authors.  All rights reserved.
> 
>    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
> 
> 
> 
> Claise, et al.            Expires July 18, 2019                 [Page 1]
> 
> Internet-Draft                YANG Catalog                  January 2019
> 
> 
>    the Trust Legal Provisions and are provided without warranty as
>    described in the Simplified BSD License.
> 
> Table of Contents
> 
>    1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   2
>    2.  The Solution  . . . . . . . . . . . . . . . . . . . . . . . .   3
>    3.  YANG Semantic Versioning  . . . . . . . . . . . . . . . . . .   3
>      3.1.  Classification of changes between module revisions  . . .   3
>      3.2.  YANG Semantic Versioning Scheme for Modules . . . . . . .   4
>      3.3.  YANG Semantic Version Update Rules  . . . . . . . . . . .   6
>      3.4.  YANG Module Semver Extension  . . . . . . . . . . . . . .   7
>    4.  Import by Semantic Version  . . . . . . . . . . . . . . . . .   9
>    5.  Updates to YANG 1.1 Module Update Rules . . . . . . . . . . .  12
>    6.  Updates to ietf-yang-library  . . . . . . . . . . . . . . . .  12
>    7.  Deprecated and Obsolete Reasons . . . . . . . . . . . . . . .  13
>    8.  Guidelines  . . . . . . . . . . . . . . . . . . . . . . . . .  14
>      8.1.  Guidelines to YANG model authors  . . . . . . . . . . . .  14
>      8.2.  Guidelines to YANG model clients  . . . . . . . . . . . .  15
>    9.  Semantic Version Extension YANG Module  . . . . . . . . . . .  15
>    10. Contributors  . . . . . . . . . . . . . . . . . . . . . . . .  19
>    11. Security Considerations . . . . . . . . . . . . . . . . . . .  19
>    12. IANA Considerations . . . . . . . . . . . . . . . . . . . . .  19
>      12.1.  YANG Module Registrations  . . . . . . . . . . . . . . .  19
>    13. References  . . . . . . . . . . . . . . . . . . . . . . . . .  20
>      13.1.  Normative References . . . . . . . . . . . . . . . . . .  20
>      13.2.  Informative References . . . . . . . . . . . . . . . . .  20
>    Appendix A.  Appendix . . . . . . . . . . . . . . . . . . . . . .  20
>      A.1.  Open Issues: Requirements to be Addressed . . . . . . . .  21
>      A.2.  Open Issues . . . . . . . . . . . . . . . . . . . . . . .  21
>      A.3.  Derived Semantic Version  . . . . . . . . . . . . . . . .  22
>        A.3.1.  The Derived Semantic Version  . . . . . . . . . . . .  22
>        A.3.2.  Implementation Experience . . . . . . . . . . . . . .  22
>    Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .  23
> 
> 1.  Introduction
> 
>    This document puts forth a solution to the problems described in
>    [I-D.verdt-netmod-yang-versioning-reqs] by proposing changes to
>    [RFC7950] to address the various requirements that
>    [I-D.verdt-netmod-yang-versioning-reqs] specifies.  At this time, the
>    solution herein addresses requirements 1.1, 1.2, 1.3, 2.1, 4.1, 4.2,
>    4.3, 5.1, and 5.2.  Current gaps are documented in Appendix A.1
>    below.
> 
> 
> 
> 
> 
> 
> 
> Claise, et al.            Expires July 18, 2019                 [Page 2]
> 
> Internet-Draft                YANG Catalog                  January 2019
> 
> 
> 2.  The Solution
> 
>    The solution is composed of five parts:
> 
>    1.  A semantic versioning YANG extension, along with an optional
>        additional check that validates the semantic versioning from a
>        syntactic point of view, which can either assist in determining
>        the correct semantic versioning value, or which can help in
>        determining the values for YANG modules that do not support this
>        extension.
> 
>    2.  An import by semantic version statement
> 
>    3.  Updates to the YANG 1.1 module update rules
> 
>    4.  Updates to ietf-yang-library
> 
>    5.  An introduction of deprecated and obsolote reason clauses
> 
> 3.  YANG Semantic Versioning
> 
>    The first part of the solution introduces and 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.
> 
>    This part of the solution addresses requirements 1.1, 1.2, and 2.1 of
>    [I-D.verdt-netmod-yang-versioning-reqs].
> 
>    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' statement, and all 'include'
>    statements MUST specify the revision-date for each of the included
>    submodules.
> 
> 3.1.  Classification of changes between module revisions
> 
>    The principle aim of YANG semantic versioning is to allow a reader of
>    a 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 artibrary revisions of a
>    YANG module can be classified into one of four categories:
>    'unchanged', 'editorial, 'backwards-compatible' or 'non-backwards-
> 
> 
> 
> 
> Claise, et al.            Expires July 18, 2019                 [Page 3]
> 
> Internet-Draft                YANG Catalog                  January 2019
> 
> 
>    compatible'.  The classification is performed by use of the following
>    rules:
> 
>       The semantic version change between two modules 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, or statement ordering, between
>       the two module revisions, but thoses 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 of "Updating a Module"
>       of [RFC7950], except that no elements have been changed to status
>       'obsolete', and re-ordering of statements is allowed.
> 
>       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 of
>       "Updating a Module", or one or more schema nodes have been changed
>       to status 'obsolete'.
> 
>    Q: Should revision-date history and semantic version be excluded from
>    the comparision?  RW: I've assumed yes.
> 
>    Q.  Does statement ordering need to be considered as part of the
>    comparision?  RW: I think the answer should be no.
> 
> 3.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
> 
> 
> 
> 
> Claise, et al.            Expires July 18, 2019                 [Page 4]
> 
> Internet-Draft                YANG Catalog                  January 2019
> 
> 
>       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 SHOULD include a top-level 'semver:version'
>    statement that specifies the YANG semantic version number for each
>    revision of the module.
> 
>    All 'revision' statements in YANG modules SHOULD include a
>    'semver:version' substatement that specifies the YANG semantic
>    version number associated with that particular revision of the
>    module.
> 
>    "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
> 
> 
> 
> 
> 
> Claise, et al.            Expires July 18, 2019                 [Page 5]
> 
> Internet-Draft                YANG Catalog                  January 2019
> 
> 
> 3.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 3.1.
> 
>    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:
> 
>       If the module is being updated in a non-backwards-compatible way,
>       then the module version "X.Y.Z[m|M]" SHOULD 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.
> 
>       If the module is being updated in a backwards-compatible way, then
>       the module version "X.Y.Z[m|M]" SHOULD be updated to "X.Y+1.0"
>       unless that module version has already been defined with different
>       content, in which case if the current module version is "X.Y.ZM"
>       then it MUST be updated to "X.Y.Z+1M", or otherwise "X.Y.Z+1m".
> 
>       If the module is being updated in an editorial way, then the
>       module version "X.Y.Z[m|M]" MUST be updated to "X.Y.Z+1[m|M],
>       retaining the 'm|M' character if it is already present in the
>       previous version.".
> 
>       YANG module semantic version numbers begining with 0, i.e "0.X.Y"
>       are regarded as beta definitions and need not follow the nbc rules
>       above, and the minor version number can be incremented instead.
> 
>       In all cases, the 3 numeric fields that comprise a YANG module
>       semantic version number associated with a YANG module MUST
>       uniquely identify the contents of that YANG module.  E.g., module
>       version "1.2.3M" is not allowed if module version "1.2.3" has
>       already been defined.
> 
> 
> 
> 
> Claise, et al.            Expires July 18, 2019                 [Page 6]
> 
> Internet-Draft                YANG Catalog                  January 2019
> 
> 
> 3.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.
> 
>            extension module-version {
>                argument semver;
>            }
> 
>    The extension would typically be used this way:
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> Claise, et al.            Expires July 18, 2019                 [Page 7]
> 
> Internet-Draft                YANG Catalog                  January 2019
> 
> 
>        module yang-module-name {
> 
>          namespace "name-space";
>          prefix "prefix-name";
> 
>          import ietf-semver { prefix "semver"; }
> 
>          description
>            "to be completed";
> 
>          semver:module-version "2.0.0";
> 
>          revision 2017-10-30 {
>            description
>              "Change the module structure";
>            semver:module-version "2.0.0";
>          }
> 
>          revision 2017-07-30 {
>            description
>              "Added new feature XXX";
>            semver:module-version "1.2.0";
>          }
> 
>          revision 2017-04-03 {
>            description
>              "Update copyright notice.";
>            semver:module-version "1.0.1";
>          }
> 
>          revision 2017-04-03 {
>            description
>              "First release version.";
>            semver:module-version "1.0.0";
>          }
> 
>          revision 2017-01-26 {
>            description
>              "Initial module for inet types";
>            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.
> 
> 
> 
> Claise, et al.            Expires July 18, 2019                 [Page 8]
> 
> Internet-Draft                YANG Catalog                  January 2019
> 
> 
> 4.  Import by Semantic Version
> 
>    If a module is imported by another one, it is usually not specified
>    which revision of the imported module should be used.  However, not
>    all revisions may be acceptable.  Today YANG 1.1 allows one to
>    specify the revision date of the imported module, but that is too
>    specific, as even a small spelling correction of the imported module
>    results in a change to its revision date, thus making the module
>    revision ineligible for import.
> 
>    Using semantic versioning to indicate the acceptable imported module
>    versions is much more flexible.  For example:
> 
>    o  Only a module of a specific MAJOR version is acceptable.  All
>       MINOR and PATCH versions can also be imported.
> 
>    o  A module at a specific MAJOR version or higher is acceptable.
> 
>    o  A module at a specific MAJOR.MINOR version is acceptable.  All
>       PATCH versions can also be imported.
> 
>    o  A module within a certain range of versions are acceptable.  For
>       example, in this case, a module between version 1.0.0 (inclusive)
>       and 3.0.0 (exclusive) are acceptable.
> 
>    The ietf-semver module provides another extension, import-versions
>    that is a child of import and specifies the rules for an acceptable
>    set of versions of the given module.  This extension addresses
>    requirement 1.3 of [I-D.verdt-netmod-yang-versioning-reqs].  The
>    structure of this extension is specified as follows:
> 
>    TODO: How to specify this?  One thought is below, not fully
>    formalized as this should be discussed further.  Note: while this
>    uses a comma to separate discrete versions, we could instead allow
>    for this to be specified multiple times.
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> Claise, et al.            Expires July 18, 2019                 [Page 9]
> 
> Internet-Draft                YANG Catalog                  January 2019
> 
> 
> [\[(]X[.Y[.Z]][-[X[.Y[.X]]][\])]][,...]
> 
> Where the first character MAY be a '[' or '(' to indicate at least inclusive and at least
>  exclusive (respectively).  If this is omitted, a full semantic version must be specified
>  and the import will only support this one version.
> 
> The following version, if specified with a '[' or '(' indicates the lower bound.  This can
>  be a full semantic version or a MAJOR only or MAJOR.MINOR only.
> 
> The '-', if specified, is a literal hyphen indicating a range will be specified.  If the second portion
>  of the import-versions clause is omitted, then there is no upper bound on what will be considered
>  an acceptable imported version.
> 
> After the '-' the upper bound semantic version (or part thereof) follows.
> 
> After the upper bound version, one of ']' or ')' MUST follow to indicate whether this limit is inclusive
>  or exclusive of the upper bound respectively.
> 
> Finally, a literal comma (',') MAY be specified with additional ranges.  Each range is taken as a logical
>  OR.
> 
> 
>    For example:
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> Claise, et al.            Expires July 18, 2019                [Page 10]
> 
> Internet-Draft                YANG Catalog                  January 2019
> 
> 
> import example-module {
>   semver:import-versions "[1.0.0-3.0.0)";
>   // All versions between 1.0.0 (inclusive) and 3.0.0 (exclusive) are acceptable.
> }
> 
> import example-module {
>   semver:import-versions "[2-5]";
>   // All versions between 2.0.0 (inclusive) and 5.y.z (inclusive) where y and z are
>   // any value for MINOR and PATCH versions.
> }
> 
> import example-module {
>   semver:import-versions "[1.5-2.0.0),[2.5";
>   // All versions between 1.5.0 (inclusive) and 2.0.0 (exclusive) as well as all versions
>   // greater than 2.5 (inclusive).  In this manner, if 2.0 was branched from 1.4, and a
>   // new feature was added into 1.5, all versions of 1.x.x starting at 1.5 are allowed,
>   // but the feature was not merged into 2.y.z until 2.5.0.
> }
> 
> import example-module {
>   semver:import-versions "[1";
>   // All versions greater than MAJOR version 1 are acceptable.  This includes any
>   // MINOR or PATCH versions.
> }
> 
> import example-module {
>   semver:import-versions "1.0.0";
>   // Only version 1.0.0 is acceptable (this mimics what exists with import by revision).
> }
> 
> import example-module {
>   semver:import-versions "[1.1-2)"";
>   // All versions greater than 1.1 (inclusive, and including all PATCH versions off of 1.1)
>   // up to MAJOR version 2 (exclusive) are acceptable.
> }
> 
> import example-module {
>   semver:import-versions "[1.1-2),[3";
>   // All versions greater than 1.1 (inclusive, and including all PATCH versions off of 1.1)
>   // up to MAJOR version 2 (exclusive), as well as all versions greater than MAJOR version 3
>   // (inclusive) are acceptable.
> }
> 
> import example-module {
>   semver:import-versions "[1.1-2),[3.0.0";
>   // This is equivalent to the example above, simply indicating that a partial semantic version
>   // assumes all missing components are 0.
> }
> 
> 
> 
> Claise, et al.            Expires July 18, 2019                [Page 11]
> 
> Internet-Draft                YANG Catalog                  January 2019
> 
> 
>    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.
> 
> 5.  Updates to YANG 1.1 Module Update Rules
> 
>    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
>    [I-D.verdt-netmod-yang-versioning-reqs].  The following is proposed
>    text for this change.
> 
>    "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."
> 
> 6.  Updates to ietf-yang-library
> 
>    The ietf-semver YANG module also specifies additional ietf-yang-
>    library [RFC7895] [I-D.ietf-netconf-rfc7895bis] leafs to be added at
>    the module and submodule levels.  The first is module-version, which
>    augments /yanglib:yang-library/yanglib:module-set/yanglib:module.
>    This specifies the current semantic version of the associated module
>    and revision in a given module-set.  The related submodule-version
>    leaf is added at /yanglib:yang-library/yanglib:module-
>    set/yanglib:module/yanglib:submodule to indicate the semantic version
>    of a submodule.
> 
>    In order to satisfy the requirements 4.1 and 4.3 of
>    [I-D.verdt-netmod-yang-versioning-reqs] that deprecated and obsolete
>    node presence and operation are easily and clearly known to clients,
>    ietf-semver also augments the ietf-yang-library with two additional
>    boolean leafs at /yanglib:yang-library/yanglib:module-set/
>    yanglib:module.  A client can make one request of the ietf-yang-
>    library and know whether or a not a module that has deprecated or
>    obsolete has those nodes implemented by the server, as opposed to
>    making multiple requests for each node in question.
> 
>    deprecated-nodes-present :  A boolean that indicates whether or not
>       this server implements deprecated nodes.  The value of this leaf
>       SHOULD be true; and if so, the server MUST implement nodes within
>       this module as they are documented.  If specific deprecated nodes
> 
> 
> 
> 
> Claise, et al.            Expires July 18, 2019                [Page 12]
> 
> Internet-Draft                YANG Catalog                  January 2019
> 
> 
>       are not implemented as documented, then they MUST be listed as
>       deviations.  This leaf defaults to true.
> 
>    obsolete-nodes-present :  A boolean that indicates whether or not
>       this server implements obsolete nodes.  The value of this leaf
>       SHOULD be false; and if so, the server MUST NOT implement nodes
>       within this module.  If this leaf is true, then all nodes in this
>       module MUST be implemented as documented in the module.  Any
>       variation of this MUST be listed as deviations.  This leaf
>       defaults to false.
> 
>    If a module does not have any deprecated or obsolete nodes, the
>    server SHOULD set the corresponding leaf above to true.  This is
>    helpful to clients, such that if the MAJOR version number has not
>    changed, and these booleans are true, then a client does not have to
>    check the status of any node for the module.
> 
>    Module compatibility can be affected if values other than the default
>    are used for the leafs described here.  For example, if a server does
>    not implemennt deprecated nodes, then a given module revision may be
>    incompatible with a previous revision where the nodes were not
>    deprecated.  When calculating backward compatibility, the default
>    values of these leafs MUST be considered.  From a client's point of
>    view, if two module revisions have the same MAJOR version but the
>    run-time value of deprecated-nodes-present (as read from the ietf-
>    yang-library) is false, then compatibility MUST NOT be assumed based
>    on the module-version alone.
> 
> 7.  Deprecated and Obsolete Reasons
> 
>    The ietf-semver module specifies an extension, status-description,
>    that is designed to be used as a substatement of the status statement
>    when the status is deprecated or obsolete.  The argument to this
>    extension is freeform text that explains why the node was deprecated
>    or made obsolete.  It may also point to other schema elements that
>    take the place of the deprecated or obsolete node.  This text is
>    designed for human consumption to aid in the migration away from
>    nodes that will one day no longer work.  These extensions address
>    requirement 4.2 of [I-D.verdt-netmod-yang-versioning-reqs].  An
>    example is shown below.
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> Claise, et al.            Expires July 18, 2019                [Page 13]
> 
> Internet-Draft                YANG Catalog                  January 2019
> 
> 
>    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.";
>    }
> 
> 8.  Guidelines
> 
> 8.1.  Guidelines to YANG model authors
> 
>    From a published revision N of a module, the next published revision
>    N+1 of the module SHOULD have one of:
> 
>    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
> 
>        *  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
> 
> 
> 
> 
> 
> Claise, et al.            Expires July 18, 2019                [Page 14]
> 
> Internet-Draft                YANG Catalog                  January 2019
> 
> 
>        *  There is no new functionality which has been added in a
>           backwards compatible-manner
> 
>        *  Ther are 1 or more bug fixes which have been made in a
>           backwards-compatible manner
> 
>    As explained in Appendix A.3.2, while programatically determining a
>    semantic version is possible using the pyang utility, human overisght
>    is highly recommended because of some special cases which can not be
>    detected by pyang.  Therefore, a model author SHOULD use both means
>    to determine a model's semantic version.
> 
> 8.2.  Guidelines to YANG model clients
> 
> 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
> 
> <CODE BEGINS> file "[e-mail]"
>   module ietf-semver {
>     yang-version 1.1;
>     namespace "urn:ietf:params:xml:ns:yang: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/>
>        WG List:  <mailto:[e-mail]>
> 
>        Author:   Benoit Claise
>                  <mailto:[e-mail]>
> 
>        Author:   Joe Clarke
>                  <mailto:[e-mail]>
> 
> 
> 
> Claise, et al.            Expires July 18, 2019                [Page 15]
> 
> Internet-Draft                YANG Catalog                  January 2019
> 
> 
>        Author:   Kevin D'Souza
>                  <mailto:[e-mail]>
> 
>        Author:   Balazs Lengyel
>                  <mailto:[e-mail]>";
>     description
>       "This module contains a definition for a YANG 1.1 extension to
>        express the semantic version of YANG modules.";
> 
>     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";
>     }
> 
>     extension module-version {
>       argument semver;
>       description
>         "The version number for the module revision it is used in.
>          This is expressed as a semantic version string in the form:
>           x.y.z
>          where:
>           * x corresponds to the major version,
>           * y corresponds to a minor version,
>           * z corresponds to a patch version.
> 
>          A major version number of 0 indicates that this model is still
>          in development, and is potentially subject to change.
> 
> 
> 
> 
> Claise, et al.            Expires July 18, 2019                [Page 16]
> 
> Internet-Draft                YANG Catalog                  January 2019
> 
> 
>          Following a release of major version 1, all modules will
>          increment major revision number where backward incompatible
>          changes to the model are made.
> 
>          The minor version is changed when features are added to the
>          model that do not impact current clients use of the model.
>          When major version is stepped, the minor version is reset to 0.
> 
>          The patch-level version is incremented when non-feature changes
>          (such as bugfixes or clarifications to human-readable
>          descriptions that do not impact model functionality) are made
>          that maintain backward compatibility.
>          When major or minor version is stepped, the patch-level is
>          reset to 0.
> 
>          By comparing the module-version between two revisions of a
>          given module, one can know if different revisions are backward
>          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 statement.
>          Zero or one module-version statement is allowed per parent
>          statement. NO substatements are allowed.
>         ";
>       reference "I-D.clacla-netmod-yang-model-update : YANG Semantic Version";
>     }
> 
>     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 version-clause argument is specified in the following
>          format
> 
>          [\\[(]X[.Y[.Z]][-[X[.Y[.X]]][\\])]][,...]
> 
>          Where the first character MAY be a '[' or '(' to indicate at least inclusive and at least
>           exclusive (respectively).  If this is omitted, a full semantic version must be specified
>           and the import will only support this one version.
> 
>          The following version, if specified with a '[' or '(' indicates the lower bound.  This can
>           be a full semantic version or a MAJOR only or MAJOR.MINOR only.
> 
>          The '-', if specified, is a literal hyphen indicating a range will be specified.  If the second portion
> 
> 
> 
> Claise, et al.            Expires July 18, 2019                [Page 17]
> 
> Internet-Draft                YANG Catalog                  January 2019
> 
> 
>           of the import-versions clause is omitted, then there is no upper bound on what will be considered
>           an acceptable imported version.
> 
>          After the '-' the upper bound semantic version (or part thereof) follows.
>          After the upper bound version, one of ']' or ')' MUST follow to indicate whether this limit is inclusive
>           or exclusive of the upper bound respectively.
> 
>          Finally, a literal comma (',') MAY be specified with additional ranges.  Each range is taken as a logical
>           OR.
> 
>          The statement MUST only be a substatement of the import statement.  Zero or one
>          import-versions statement is allowed per import statement.  NO substatements are allowed.";
>       reference "I-D.clacla-netmod-yang-model-update : 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, and MUST
>          only be used when the status is deprecated or obsolete.  Zero or more status-description
>          statements are allowed per parent statement.  NO substatements are allowed.";
>       reference "I-D.clacla-netmod-yang-model-update : Deprecated and Obsolete Reasons";
>     }
> 
>     augment "/yanglib:yang-library/yanglib:module-set/yanglib:module" {
>       description
>         "Augmentations for the ietf-yang-library module to support semantic versioning.";
>       leaf module-version {
>         type string {
>           pattern '[0-9]+\.[0-9]+\.[0-9]+';
>         }
>         description
>           "The semantic version for this module in MAJOR.MINOR.PATCH format.  This version
>            must match the semver:module-version value in specific revision of the module
>            loaded in this module-set.";
>       }
>       leaf deprecated-nodes-present {
>         type boolean;
>         default "true";
>         description
>           "A boolean that indicates whether or not this server implements deprecated nodes.
>            The value of this leaf SHOULD be true; and if so, the server MUST implement nodes
>            within this module as they are documented.  If specific deprecated nodes are not
>            implemented as document, then they MUST be listed as deviations.  If a module does
>            not currently contain any deprecated nodes, then this leaf SHOULD be set to true.";
> 
> 
> 
> Claise, et al.            Expires July 18, 2019                [Page 18]
> 
> Internet-Draft                YANG Catalog                  January 2019
> 
> 
>       }
>       leaf obsolete-nodes-present {
>         type boolean;
>         default "false";
>         description
>           "A boolean that indicates whether or not this server implements obsolete nodes.
>            The value of this leaf SHOULD be false; and if so, the server MUST NOT implement
>            nodes within this module. If this leaf is true, then all nodes in this module MUST
>            be implemented as documented in the module.  Any variation of this MUST be listed as
>            deviations.  If a module does not currently contain any obsolete nodes, then this
>            leaf SHOULD be set to true.";
>       }
>     }
>   }
> <CODE ENDS>
> 
> 10.  Contributors
> 
>    o  Anees Shaikh, Google
> 
>    o  Rob Shakir, Google
> 
> 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:
> 
>    o  Name: ietf-semver
> 
>    o  XML Namespace: urn:ietf:params:xml:ns:yang:ietf-semver
> 
>    o  Prefix: semver
> 
>    o  Reference: [RFCXXXX]
> 
> 
> 
> 
> 
> 
> 
> 
> Claise, et al.            Expires July 18, 2019                [Page 19]
> 
> Internet-Draft                YANG Catalog                  January 2019
> 
> 
> 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>.
> 
> 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.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-netconf-rfc7895bis]
>               Bierman, A., Bjorklund, M., Schoenwaelder, J., Watsen, K.,
>               and R. Wilton, "YANG Library", draft-ietf-netconf-
>               rfc7895bis-07 (work in progress), October 2018.
> 
>    [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.
> 
>    [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>.
> 
> 
> 
> 
> Claise, et al.            Expires July 18, 2019                [Page 20]
> 
> Internet-Draft                YANG Catalog                  January 2019
> 
> 
> Appendix A.  Appendix
> 
> A.1.  Open Issues: Requirements to be Addressed
> 
>    There are a few requirements of
>    [I-D.verdt-netmod-yang-versioning-reqs] still to be addressed.  These
>    include the following:
> 
>    o  A solution is required for client compatibility to address
>       requirements 3.1 and 3.2 from
>       [I-D.verdt-netmod-yang-versioning-reqs].  This could include
>       adding "module sets" support to ietf-yang-library where the client
>       can choose one set with which to use.
> 
>    o  A solution for instance data to satisfy requirement 5.3 of
>       [I-D.verdt-netmod-yang-versioning-reqs] is also required.
> 
>    o  While not mandatory, requirement 2.2 of
>       [I-D.verdt-netmod-yang-versioning-reqs] looks to provide a way to
>       determine, at the node level, whether or not changes have occurred
>       between revisions of a given YANG module.  This may require
>       application of semver at the node level.
> 
> A.2.  Open Issues
> 
>    Additionally, there are a few open issues to be discussed and
>    settled.  These include the following:
> 
>    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.
> 
>    o  Should IETF/IANA officially generate derived semantic versions for
>       their own modules?  As they are the owner of the modules it should
>       be their responsibility, but how to document it?  Note that next
>       round of funding for the yangcatalog.org could help develop the
>       perfect derived-semantic-version toolset
> 
>    o  We could consider a new naming convention for module files.
>       Today, module files are named using a [e-mail]
>       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.
> 
> 
> 
> 
> 
> 
> Claise, et al.            Expires July 18, 2019                [Page 21]
> 
> Internet-Draft                YANG Catalog                  January 2019
> 
> 
> A.3.  Derived Semantic Version
> 
>    TODO - Ideally this text would move to a separate schema comparison
>    tool draft, but keep the text here until that draft has been started.
> 
> A.3.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.3.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 July 18, 2019                [Page 22]
> 
> Internet-Draft                YANG Catalog                  January 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: [phone]
>    Email: [e-mail]
> 
> 
>    Joe Clarke
>    Cisco Systems, Inc.
>    7200-12 Kit Creek Rd
>    Research Triangle Park, North Carolina
>    United States of America
> 
>    Phone: [phone]
>    Email: [e-mail]
> 
> 
> 
> 
> Claise, et al.            Expires July 18, 2019                [Page 23]
> 
> Internet-Draft                YANG Catalog                  January 2019
> 
> 
>    Balazs Lengyel
>    Ericsson
>    Magyar Tudosok Korutja
>    1117 Budapest
>    Hungary
> 
>    Phone: [phone]
>    Email: [e-mail]
> 
> 
>    Kevin D'Souza
>    AT&T
>    200 S. Laurel Ave
>    Middletown, NJ
>    United States of America
> 
>    Email: [e-mail]
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> Claise, et al.            Expires July 18, 2019                [Page 24]

> _______________________________________________
> Netmod-ver-dt mailing list
> [e-mail]
> https://urldefense.proofpoint.com/v2/url?u=https-3A__www.ietf.org_mailman_listinfo_netmod-2Dver-2Ddt&d=DwICAg&c=HAkYuh63rsuhr6Scbfh0UjBXeMK-ndb3voDTXcWzoCI&r=GIehbDpQlo31lSi6WbnEkA&m=U0k8OMx4cXKyTrHyJJJV5RxgE_semcHYBiYiszhHIbc&s=vO22FMOeYoRUoWlFFD3kFz8T9RGeR9n20Vo3_pr5GbQ&e=