< draft-clacla-netmod-yang-model-update-05.txt   draft-clacla-netmod-yang-model-update-06.txt >
Network Working Group B. Claise Network Working Group B. Claise
Internet-Draft J. Clarke Internet-Draft J. Clarke
Updates: 7950 (if approved) Cisco Systems, Inc. Updates: 7950 (if approved) Cisco Systems, Inc.
Intended status: Standards Track B. Lengyel Intended status: Standards Track B. Lengyel
Expires: November 25, 2018 Ericsson Expires: January 3, 2019 Ericsson
K. D'Souza K. D'Souza
AT&T AT&T
May 24, 2018 July 2, 2018
New YANG Module Update Procedure New YANG Module Update Procedure
draft-clacla-netmod-yang-model-update-05 draft-clacla-netmod-yang-model-update-06
Abstract Abstract
This document specifies a new YANG module update procedure in case of This document specifies a new YANG module update procedure in case of
backward-incompatible changes, as an alternative proposal to the YANG backward-incompatible changes, as an alternative proposal to the YANG
1.1 specifications. This document updates RFC 7950. 1.1 specifications. This document updates RFC 7950.
Status of This Memo Status of This Memo
This Internet-Draft is submitted in full conformance with the This Internet-Draft is submitted in full conformance with the
skipping to change at page 1, line 36 skipping to change at page 1, line 36
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/. Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on November 25, 2018. This Internet-Draft will expire on January 3, 2019.
Copyright Notice Copyright Notice
Copyright (c) 2018 IETF Trust and the persons identified as the Copyright (c) 2018 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(https://trustee.ietf.org/license-info) in effect on the date of (https://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
2. The Problems . . . . . . . . . . . . . . . . . . . . . . . . 3 2. The Solution . . . . . . . . . . . . . . . . . . . . . . . . 2
2.1. Slow Standardization . . . . . . . . . . . . . . . . . . 4 2.1. Semantic Versioning . . . . . . . . . . . . . . . . . . . 3
2.2. Some YANG Modules Are Not Backward Compatible . . . . . . 4 2.1.1. Semantic Versioning, As Set by the YANG Module
2.3. Non-Backward Compatible Errors . . . . . . . . . . . . . 4 Designer . . . . . . . . . . . . . . . . . . . . . . 3
2.4. YANG Module Transition Strategy . . . . . . . . . . . . . 4 2.1.2. The Derived Semantic Version . . . . . . . . . . . . 5
2.5. Need to Allow Non-Backward Compatible changes . . . . . . 5 2.1.3. Implementation Experience . . . . . . . . . . . . . . 5
2.6. Clear Indication of Node Support . . . . . . . . . . . . 5 2.2. Import by Semantic Version . . . . . . . . . . . . . . . 6
2.7. No way to easily decide whether a change is Backward 2.3. Updates to YANG 1.1 Module Update Rules . . . . . . . . . 9
Compatible . . . . . . . . . . . . . . . . . . . . . . . 6 2.4. Updates to ietf-yang-library . . . . . . . . . . . . . . 9
3. The Solution . . . . . . . . . . . . . . . . . . . . . . . . 7 2.5. Deprecated and Obsolete Reasons . . . . . . . . . . . . . 10
3.1. Semantic Versioning . . . . . . . . . . . . . . . . . . . 7 3. Semantic Version Extension YANG Module . . . . . . . . . . . 11
3.1.1. Semantic Versioning, As Set by the YANG Module 4. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 15
Designer . . . . . . . . . . . . . . . . . . . . . . 7 5. Security Considerations . . . . . . . . . . . . . . . . . . . 15
3.1.2. The Derived Semantic Version . . . . . . . . . . . . 10 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 15
3.1.3. Implementation Experience . . . . . . . . . . . . . . 10 6.1. YANG Module Registrations . . . . . . . . . . . . . . . . 15
3.2. Import by Semantic Version . . . . . . . . . . . . . . . 11 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 16
3.3. Updates to YANG 1.1 Module Update Rules . . . . . . . . . 14 7.1. Normative References . . . . . . . . . . . . . . . . . . 16
3.4. Updates to ietf-yang-library . . . . . . . . . . . . . . 14 7.2. Informative References . . . . . . . . . . . . . . . . . 16
3.5. Deprecated and Obsolete Reasons . . . . . . . . . . . . . 15 Appendix A. Appendix . . . . . . . . . . . . . . . . . . . . . . 16
4. Semantic Version Extension YANG Module . . . . . . . . . . . 16 A.1. Open Issues: Requirements to be Addressed . . . . . . . . 17
5. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 20 A.2. Open Issues . . . . . . . . . . . . . . . . . . . . . . . 17
6. Security Considerations . . . . . . . . . . . . . . . . . . . 20 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 18
7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 20
7.1. YANG Module Registrations . . . . . . . . . . . . . . . . 20
8. References . . . . . . . . . . . . . . . . . . . . . . . . . 20
8.1. Normative References . . . . . . . . . . . . . . . . . . 20
8.2. Informative References . . . . . . . . . . . . . . . . . 21
Appendix A. Appendix . . . . . . . . . . . . . . . . . . . . . . 21
A.1. Open Issues . . . . . . . . . . . . . . . . . . . . . . . 22
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 22
1. Introduction 1. Introduction
The YANG data modeling language [RFC7950] specifies strict rules for This document puts forth a solution to the problems described in
updating YANG modules (see section 11 "Updating a Module"). Citing a [I-D.verdt-netmod-yang-versioning-reqs] by proposing changes to
few of the relevant rules: [RFC7950] to address the various requirements that
[I-D.verdt-netmod-yang-versioning-reqs] specifies. At this time, the
1. "As experience is gained with a module, it may be desirable to solution herein addresses requirements 1.1, 1.2, 1.3, 2.1, 4.1, 4.2,
revise that module. However, changes to published modules are 4.3, 5.1, and 5.2. Current gaps are documented in Appendix A.1
not allowed if they have any potential to cause interoperability below.
problems between a client using an original specification and a
server using an updated specification."
2. "Note that definitions contained in a module are available to be
imported by any other module and are referenced in "import"
statements via the module name. Thus, a module name MUST NOT be
changed. Furthermore, the "namespace" statement MUST NOT be
changed, since all XML elements are qualified by the namespace."
3. "Otherwise, if the semantics of any previous definition are
changed (i.e., if a non-editorial change is made to any
definition other than those specifically allowed above), then
this MUST be achieved by a new definition with a new identifier."
4. "deprecated indicates an obsolete definition, but it permits new/
continued implementation in order to foster interoperability with
older/existing implementations."
What are the consequences?
1. If a YANG module is intended to update another YANG module, the
module name should not be changed as it will break existing
tooling and code by changing imports statements, service
composition at the orchestration layer, general network
management applications, etc.
2. When the same YANG module name is kept, its new revision must be
updated in a backward-compatible way.
3. While most of the non-backward compatible changes are prohibited,
a client still does not know if a changed module is backward
compatible, as a server may remove parts of a module after
marking it deprecated or obsolete.
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.
This document does not address the potential need of an automatic way
to discover that a YANG-MODULE-B obsoletes YANG-MODULE-A, so that
YANG-MODULE-A should not be given any attention. This problem is
currently solved by RFC obsolete tag as a level of indirection
between the YANG modules.
2. The Problems
This section lists a series of problems, which leads to the solution
in the next section.
2.1. Slow Standardization
The points made in the introduction lead to the logical conclusion
that the standardized YANG modules have to be perfect on day one (at
least the structure and meaning), which in turn might explain why
IETF YANG modules take so long to standardize. Shooting for
perfection is obviously a noble goal, but if the perfect standard
comes too late, it doesn't help the industry.
2.2. Some YANG Modules Are Not Backward Compatible
As we learn from our mistakes, we're going to face more and more
backward-incompatible YANG modules. An example is the YANG data
model for L3VPN service delivery [RFC8049], which, based on
implementation experience, has been updated in a backward-
incompatible way by [RFC8299].
While Standards Development Organization (SDO) YANG modules are
obviously better for the industry, we must recognize that many YANG
modules are actually generated YANG modules (for example, from
internal databases), also known as native YANG modules, or vendor
modules [RFC8199]. From time to time, the new YANG modules are not
backward-compatible.
In such cases, it would be better to indicate how backward-compatible
a given YANG module actually is.
2.3. Non-Backward Compatible Errors
Sometimes small errors force us to make non-backward compatible
updates. As an example imagine that we have a string with a complex
pattern (e.g., an IP address). Let's assume the initial pattern
incorrectly allows IP addresses to start with 355. In the next
version this is corrected to disallow addresses starting with 355.
Formally this is an non-backward compatible change as the value space
of the string is decreased. In reality an IP address and the
implementation behind it was never capable of handling an address
starting with 355. So practically this is a backward compatible
change, just like a correction of the description statement. Still
current YANG rules would force a module name change.
2.4. YANG Module Transition Strategy
Let's assume for a moment that we change the name of a YANG module
when making a backwards-incompatible change, with the specific
example of ietf-routing, which some propose to update to ietf-
routing-2. [yangcatalog] provides tooling that shows the
interdependencies of YANG modules.
Here are the over 30 modules that depend on ietf-routing
<https://www.yangcatalog.org/yang-search/
impact_analysis.php?modules[]=ietf-
routing&recurse=0&rfcs=1&show_subm=1&show_dir=dependents>.
Let's look at the difference for ietf-routing-2:
<https://www.yangcatalog.org/yang-search/
impact_analysis.php?modules[]=ietf-routing-
2&recurse=0&rfcs=1&show_subm=1&show_dir=dependents>.
Changing the module name from ietf-routing to ietf-routing-2 implies
that the we have to warn all draft authors of ietf-routing YANG
dependent modules. First, to make sure they are aware of ietf-
routing-2 (publishing a RFC8022bis mentioning in the module
description that this module is not compatible with the NMDA
architecture, and providing a pointer to ietf-routing-2 requires
manual, tedius work). And second, to ask them to change their import
(or service composition) to ietf-routing-2. Hopefully, in the ietf-
routing case, most dependent YANG modules are part of the IETF, so
the communication is a manageable. For the already existing
dependent vendor modules the problem is worse. And then there are
network management applications that may already be using ietf-
routing that would require new code to handle ietf-routing-2.
Changing the ietf-interfaces YANG module name would be a different
challenge, as it's used throughout the industry:
<https://www.yangcatalog.org/yang-search/
impact_analysis.php?modules[]=ietf-
interfaces&recurse=0&rfcs=1&show_subm=1&show_dir=dependents>
2.5. Need to Allow Non-Backward Compatible changes
As described in the previous sections, there is a need to allow non-
backward compatible changes without changing a module's name. This
would avoid many of the above problems. Allowing non-backward
compatible changes to happen without a module name change will
decrease the number of separate modules to handle and will make it a
trivial task to track these non-backward compatible changes.
2.6. Clear Indication of Node Support
The current definition of deprecated and obsolete in [RFC7950] (as
quoted below) is problematic and should be corrected.
o "deprecated" indicates an obsolete definition, but it permits new/
continued implementation in order to foster interoperability with
older/existing implementations.
o "obsolete" means that the definition is obsolete and SHOULD NOT be
implemented and/or can be removed from implementations.
YANG is considered an interface contract between the server and the
client. The current definitions of deprecated and obsolete mean that
a schema node that is either deprecated or obsolete may or may not be
implemented. The client has no way to find out which is the case
except for by trying to write or read data at the leaf in question.
This probing would need to be done for each separate data-node, which
is not a trivial thing to do. This "may or may not" is unacceptable
in a contract. In effect, this works as if there would be an if-
feature statement on each deprecated schema node where the server
does not advertise whether the feature is supported or not. Why is
it not advertised?
If a schema part is considered old/bad we need to be able to give
advance warning that it will be removed. As this is an advance
warning the part shall still be present and usable in the current
revision; however, it will be removed in one of the next revisions.
This is compounded by the fact that obsolete nodes may return bad or
incorrect data. A client might expect they work by the fact they
return something at all. There must be a clear indication from the
server whether or not deprecated and obsolete nodes are implemented
as defined.
2.7. No way to easily decide whether a change is Backward Compatible
A management system, SDN controller or any other user of a module
should be capable of easily determining the compatibility between two
module versions. Higher level logic for a network function,
something that can not be implemented in a purely model driven way,
is always dependent on a specific version of the module. If the
client finds that the module has been updated on the network node, it
has to decide if it tries to handle it as it handled the previous
version of the model or if it just stops, to avoid problems. To make
this decision the client needs to know if the module was updated in a
backward compatible way or not.
This is not possible to decide today because of the following:
o It is possible to change the semantic behavior of a data node,
action or rpc while the YANG definition does not change (with the
possible exception of the description statement). In such a case
it is impossible to determine whether the change is backward
compatible just by looking at the YANG statements. Its only the
human model designer that can decide.
o Problems with the deprecated and obsolete status statement,
Section 2.6
o Modelers might decide to violate YANG 1.1 update rules for some of
the reasons above
Finding status changes or violations of update rules need a line by
line comparision of the old and new modules, no easy task.
3. The Solution 2. The Solution
The solution is composed of five parts: The solution is composed of five parts:
1. A semantic versioning YANG extension, along with an optional 1. A semantic versioning YANG extension, along with an optional
additional check that validates the semantic versioning from a additional check that validates the semantic versioning from a
syntactic point of view, which can either assist in determining syntactic point of view, which can either assist in determining
the correct semantic versioning values, or which can help in the correct semantic versioning value, or which can help in
determining the values for YANG modules that don't support this determining the values for YANG modules that do not support this
extension. extension.
2. The import by version statement" 2. An import by semantic version statement
3. Updates to the YANG 1.1 module update rules 3. Updates to the YANG 1.1 module update rules
4. Updates to ietf-yang-library 4. Updates to ietf-yang-library
5. The deprecated and obsolotes Reason" 5. An introduction of deprecated and obsolote reason clauses
3.1. Semantic Versioning 2.1. Semantic Versioning
3.1.1. Semantic Versioning, As Set by the YANG Module Designer 2.1.1. Semantic Versioning, As Set by the YANG Module Designer
The semantic versioning solution proposed here has already been The semantic versioning solution proposed here has already been
proposed in [I-D.openconfig-netmod-model-catalog] (included here with proposed in [I-D.openconfig-netmod-model-catalog] (included here with
the authors' permission) which itself is based on [openconfigsemver]. the authors' permission) which itself is based on [openconfigsemver].
The goal is to indicate the YANG module backwards (in)compatibility, The goal is to indicate the YANG module backward (in)compatibility,
following semver.org semantic versioning [semver]: following semver.org semantic versioning [semver]:
"The SEMVER version number for the module is introduced. This is "The SEMVER version number for the module is introduced. This is
expressed as a semantic version number of the form: x.y.z expressed as a semantic version number of the form: x.y.z
o x is the MAJOR version. It is incremented when the new version of o x is the MAJOR version. It is incremented when the new version of
the specification is incompatible with previous versions. the specification is incompatible with previous versions.
o y is the MINOR version. It is incremented when new functionality o y is the MINOR version. It is incremented when new functionality
is added in a manner that is backward-compatible with previous is added in a manner that is backward-compatible with previous
versions. versions.
o z is the PATCH version. It is incremented when bug fixes are made o z is the PATCH version. It is incremented when bug fixes are made
in a backward-compatible manner." in a backward-compatible manner."
The semantic version value is set by the YANG module developer at the The semantic version value is set by the YANG module developer at the
design and implementation times. Along these lines, we propose the design and implementation times. Along these lines, we propose the
following YANG 1.1 extension for a more generic semantic version. following YANG 1.1 extension for a more generic semantic version.
The formal definition is found at the end of this document. The formal definition is found at the end of this document. This
semantic version extension and the text below address requirements
1.1, 1.2, 2.1, 5.1 and 5.2 of
[I-D.verdt-netmod-yang-versioning-reqs].
extension module-version { extension module-version {
argument semver; argument semver;
} }
The extension would typically be used this way: The extension would typically be used this way:
module yang-module-name { module yang-module-name {
namespace "name-space"; namespace "name-space";
skipping to change at page 10, line 5 skipping to change at page 5, line 5
semver:module-version "0.1.0"; semver:module-version "0.1.0";
} }
//YANG module definition starts here //YANG module definition starts here
See also "Semantic Versioning and Structure for IETF Specifications" See also "Semantic Versioning and Structure for IETF Specifications"
[I-D.claise-semver] for a mechanism to combine the semantic [I-D.claise-semver] for a mechanism to combine the semantic
versioning, the GitHub tools, and a potential change to the IETF versioning, the GitHub tools, and a potential change to the IETF
process. process.
3.1.2. The Derived Semantic Version 2.1.2. The Derived Semantic Version
If an explicitly defined semantic version is not available in the If an explicitly defined semantic version is not available in the
YANG module, it is possible to algoritmically calculate a derived YANG module, it is possible to algoritmically calculate a derived
semantic version. This can be used for modules not containing a semantic version. This can be used for modules not containing a
definitive semantic-version as defined in this document or as a definitive semantic-version as defined in this document or as a
starting value when specifying the definitive semantic-version. Be starting value when specifying the definitive semantic-version. Be
aware that this algorithm may sometimes incorrectly classify changes aware that this algorithm may sometimes incorrectly classify changes
between the categories non-compatible, compatible or error- between the categories non-compatible, compatible or error-
correction. correction.
3.1.3. Implementation Experience 2.1.3. Implementation Experience
[yangcatalog] uses the pyang utility to calculate the derived- [yangcatalog] uses the pyang utility to calculate the derived-
semantic-version for all of the modules contained within the catalog. semantic-version for all of the modules contained within the catalog.
[yangcatalog] contains many revisions of the same module in order to [yangcatalog] contains many revisions of the same module in order to
provide its derived-semantic-version for module consumers to know provide its derived-semantic-version for module consumers to know
what has changed between revisions of the same module. what has changed between revisions of the same module.
Two distinct leafs in the YANG module Two distinct leafs in the YANG module
[I-D.clacla-netmod-model-catalog] contain this semver notation: [I-D.clacla-netmod-model-catalog] contain this semver notation:
skipping to change at page 11, line 23 skipping to change at page 6, line 23
7. If no structural differences exist, bump module A, revision 7. If no structural differences exist, bump module A, revision
N+1's derived PATCH semantic version. N+1's derived PATCH semantic version.
The pyang utility checks many of the points listed in section 11 of The pyang utility checks many of the points listed in section 11 of
[RFC7950] for known module incompatibilities. While this approach is [RFC7950] for known module incompatibilities. While this approach is
a good way to programmatically obtain a semantic version number, it a good way to programmatically obtain a semantic version number, it
does not address all cases whereby a major version number might need 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 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 type, but its meaning may change from one revision of a module to
another. This represents a semantic change that breaks backwards another. This represents a semantic change that breaks backward
compatibility, but the above algorithm would not find it. Therefore, compatibility, but the above algorithm would not find it. Therefore,
additional, sometimes manual, rigor must be done to ensure a proper additional, sometimes manual, rigor must be done to ensure a proper
version is chosen for a given module revision. version is chosen for a given module revision.
3.2. Import by Semantic Version 2.2. Import by Semantic Version
If a module is imported by another one, it is usually not specified If a module is imported by another one, it is usually not specified
which revision of the imported module should be used. However, not which revision of the imported module should be used. However, not
all revisions may be acceptable. Today YANG 1.1 allows one to all revisions may be acceptable. Today YANG 1.1 allows one to
specify the revision date of the imported module, but that is too specify the revision date of the imported module, but that is too
specific, as even a small spelling correction of the imported module specific, as even a small spelling correction of the imported module
results in a change to its revision date, thus making the module results in a change to its revision date, thus making the module
revision ineligible for import. revision ineligible for import.
Using semantic versioning to indicate the acceptable imported module Using semantic versioning to indicate the acceptable imported module
skipping to change at page 12, line 7 skipping to change at page 7, line 7
o A module at a specific MAJOR.MINOR version is acceptable. All o A module at a specific MAJOR.MINOR version is acceptable. All
PATCH versions can also be imported. PATCH versions can also be imported.
o A module within a certain range of versions are acceptable. For o A module within a certain range of versions are acceptable. For
example, in this case, a module between version 1.0.0 (inclusive) example, in this case, a module between version 1.0.0 (inclusive)
and 3.0.0 (exclusive) are acceptable. and 3.0.0 (exclusive) are acceptable.
The ietf-semver module provides another extension, import-versions The ietf-semver module provides another extension, import-versions
that is a child of import and specifies the rules for an acceptable that is a child of import and specifies the rules for an acceptable
set of versions of the given module. The structure of this extension set of versions of the given module. This extension addresses
is specified as follows: 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 TODO: How to specify this? One thought is below, not fully
formalized as this should be discussed further. Note: while this formalized as this should be discussed further. Note: while this
uses a comma to separate discrete versions, we could instead allow uses a comma to separate discrete versions, we could instead allow
for this to be specified multiple times. for this to be specified multiple times.
[\[(]X[.Y[.Z]][-[X[.Y[.X]]][\])]][,...] [\[(]X[.Y[.Z]][-[X[.Y[.X]]][\])]][,...]
Where the first character MAY be a '[' or '(' to indicate at least inclusive and at least 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 exclusive (respectively). If this is omitted, a full semantic version must be specified
skipping to change at page 14, line 10 skipping to change at page 9, line 10
semver:import-versions "[1.1-2),[3.0.0"; semver:import-versions "[1.1-2),[3.0.0";
// This is equivalent to the example above, simply indicating that a partial semantic version // This is equivalent to the example above, simply indicating that a partial semantic version
// assumes all missing components are 0. // assumes all missing components are 0.
} }
The import statement SHOULD include a semver:import-versions The import statement SHOULD include a semver:import-versions
statement and MUST NOT include a revision statement. An import statement and MUST NOT include a revision statement. An import
statement MUST NOT contain both a semver:import-versions and a statement MUST NOT contain both a semver:import-versions and a
revision substatement. The use of the revision substatement for revision substatement. The use of the revision substatement for
import should be discouraged. import should be discouraged.
3.3. Updates to YANG 1.1 Module Update Rules 2.3. Updates to YANG 1.1 Module Update Rules
RFC 7950 section 11, must be updated to allow for non-backwards RFC 7950 section 11, must be updated to allow for non-backward
changes provided they follow the semantic versioning guidelines and changes provided they follow the semantic versioning guidelines and
increase the MAJOR version number when a backwards incompatible increase the MAJOR version number when a backward incompatible change
change is made. The following is proposed text for this 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 "As experience is gained with a module, it may be desirable to revise
that module. Changes to published modules are allowed, even if they that module. Changes to published modules are allowed, even if they
have some potential to cause interoperability problems, if the have some potential to cause interoperability problems, if the
module-version YANG extension is used in the revision statement to module-version YANG extension is used in the revision statement to
clearly indicate the nature of the change." clearly indicate the nature of the change."
3.4. Updates to ietf-yang-library 2.4. Updates to ietf-yang-library
The ietf-semver YANG module also specifies additional ietf-yang- The ietf-semver YANG module also specifies additional ietf-yang-
library [RFC7895] [I-D.ietf-netconf-rfc7895bis] leafs to be added at library [RFC7895] [I-D.ietf-netconf-rfc7895bis] leafs to be added at
the module and submodule levels. The first is module-version, which the module and submodule levels. The first is module-version, which
augments /yanglib:yang-library/yanglib:module-set/yanglib:module. augments /yanglib:yang-library/yanglib:module-set/yanglib:module.
This specifies the current semantic version of the associated module This specifies the current semantic version of the associated module
and revision in a given module-set. The related submodule-version and revision in a given module-set. The related submodule-version
leaf is added at /yanglib:yang-library/yanglib:module- leaf is added at /yanglib:yang-library/yanglib:module-
set/yanglib:module/yanglib:submodule to indicate the semantic version set/yanglib:module/yanglib:submodule to indicate the semantic version
of a submodule. of a submodule.
In order to satisfy the requirement that deprecated and obsolete node In order to satisfy the requirements 4.1 and 4.3 of
presence and operation are easily and clearly known to clients, ietf- [I-D.verdt-netmod-yang-versioning-reqs] that deprecated and obsolete
semver also augments the ietf-yang-library with two additional 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/ boolean leafs at /yanglib:yang-library/yanglib:module-set/
yanglib:module. A client can make one request of the ietf-yang- 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 library and know whether or a not a module that has deprecated or
obsolete has those nodes implemented by the server, as opposed to obsolete has those nodes implemented by the server, as opposed to
making multiple requests for each node in question. making multiple requests for each node in question.
deprecated-nodes-present : A boolean that indicates whether or not deprecated-nodes-present : A boolean that indicates whether or not
this server implements deprecated nodes. The value of this leaf this server implements deprecated nodes. The value of this leaf
SHOULD be true; and if so, the server MUST implement nodes within SHOULD be true; and if so, the server MUST implement nodes within
this module as they are documented. If specific deprecated nodes this module as they are documented. If specific deprecated nodes
are not implemented as document, then they MUST be listed as are not implemented as documented, then they MUST be listed as
deviations. This leaf defaults to true. deviations. This leaf defaults to true.
obsolete-nodes-present : A boolean that indicates whether or not obsolete-nodes-present : A boolean that indicates whether or not
this server implements obsolete nodes. The value of this leaf this server implements obsolete nodes. The value of this leaf
SHOULD be false; and if so, the server MUST NOT implement nodes 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 within this module. If this leaf is true, then all nodes in this
module MUST be implemented as documented in the module. Any module MUST be implemented as documented in the module. Any
variation of this MUST be listed as deviations. This leaf variation of this MUST be listed as deviations. This leaf
defaults to false. defaults to false.
If a module does not have any deprecated or obsolete nodes, the If a module does not have any deprecated or obsolete nodes, the
server SHOULD set the corresponding leaf above to true. This is server SHOULD set the corresponding leaf above to true. This is
helpful to clients, such that if the MAJOR version number has not 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 changed, and these booleans are true, then a client does not have to
check the status of any node for the module. check the status of any node for the module.
Module compatibility can be affected if values other than the default Module compatibility can be affected if values other than the default
are used for the leafs described here. For example, if a server does are used for the leafs described here. For example, if a server does
not implemennt deprecated nodes, then a given module revision may be not implemennt deprecated nodes, then a given module revision may be
incompatible with a previous revision where the nodes were not incompatible with a previous revision where the nodes were not
deprecated. When calculating backwards compatibility, the default deprecated. When calculating backward compatibility, the default
values of these leafs MUST be considered. From a client's point of 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 view, if two module revisions have the same MAJOR version but the
run-time value of deprecated-nodes-present (as read from the ietf- run-time value of deprecated-nodes-present (as read from the ietf-
yang-library) is false, then compatibility MUST NOT be assumed based yang-library) is false, then compatibility MUST NOT be assumed based
on the module-version alone. on the module-version alone.
3.5. Deprecated and Obsolete Reasons 2.5. Deprecated and Obsolete Reasons
The ietf-semver module specifies an extension, status-description, The ietf-semver module specifies an extension, status-description,
that is designed to be used as a substatement of the status statement that is designed to be used as a substatement of the status statement
when the status is deprecated or obsolete. This argument to this when the status is deprecated or obsolete. The argument to this
extension is freeform text that explains why the node was deprecated extension is freeform text that explains why the node was deprecated
or made obsolete. It may also point to other schema elements that or made obsolete. It may also point to other schema elements that
take the place of the deprecated or obsolete node. This text is take the place of the deprecated or obsolete node. This text is
designed for human consumption to aid in the migration away from designed for human consumption to aid in the migration away from
nodes that will one day no longer work. An example is shown below. 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.
leaf imperial-temperature { leaf imperial-temperature {
type int64; type int64;
units "degrees Fahrenheit"; units "degrees Fahrenheit";
status deprecated { status deprecated {
semver:status-description semver:status-description
"Imperial measurements are being phased out in favor "Imperial measurements are being phased out in favor
of their metric equivalents. Use metric-temperature of their metric equivalents. Use metric-temperature
instead."; instead.";
} }
description description
"Temperature in degrees Fahrenheit."; "Temperature in degrees Fahrenheit.";
} }
4. Semantic Version Extension YANG Module 3. Semantic Version Extension YANG Module
The extension and related ietf-yang-library changes described in this The extension and related ietf-yang-library changes described in this
module are defined in the YANG module below. module are defined in the YANG module below.
<CODE BEGINS> file "ietf-semver@2018-04-05.yang" <CODE BEGINS> file "ietf-semver@2018-04-05.yang"
module ietf-semver { module ietf-semver {
yang-version 1.1; yang-version 1.1;
namespace "urn:ietf:params:xml:ns:yang:ietf-semver"; namespace "urn:ietf:params:xml:ns:yang:ietf-semver";
prefix semver; prefix semver;
skipping to change at page 17, line 32 skipping to change at page 12, line 45
x.y.z x.y.z
where: where:
* x corresponds to the major version, * x corresponds to the major version,
* y corresponds to a minor version, * y corresponds to a minor version,
* z corresponds to a patch version. * z corresponds to a patch version.
A major version number of 0 indicates that this model is still A major version number of 0 indicates that this model is still
in development, and is potentially subject to change. in development, and is potentially subject to change.
Following a release of major version 1, all modules will Following a release of major version 1, all modules will
increment major revision number where backwards incompatible increment major revision number where backward incompatible
changes to the model are made. changes to the model are made.
The minor version is changed when features are added to the The minor version is changed when features are added to the
model that do not impact current clients use of the model. model that do not impact current clients use of the model.
When major version is stepped, the minor version is reset to 0. When major version is stepped, the minor version is reset to 0.
The patch-level version is incremented when non-feature changes The patch-level version is incremented when non-feature changes
(such as bugfixes or clarifications to human-readable (such as bugfixes or clarifications to human-readable
descriptions that do not impact model functionality) are made descriptions that do not impact model functionality) are made
that maintain backwards compatibility. that maintain backward compatibility.
When major or minor version is stepped, the patch-level is When major or minor version is stepped, the patch-level is
reset to 0. reset to 0.
By comparing the module-version between two revisions of a By comparing the module-version between two revisions of a
given module, one can know if different revisions are backwards given module, one can know if different revisions are backward
compatible or not, as well as compatible or not, as well as
whether or not new features have been added to a newer revision. whether or not new features have been added to a newer revision.
If a module contains this extension it indicates that for this If a module contains this extension it indicates that for this
module the updated status and update rules as this described in module the updated status and update rules as this described in
RFC XXXX are used. RFC XXXX are used.
The statement MUST only be a substatement of the revision statement. The statement MUST only be a substatement of the revision statement.
Zero or one module-version statement is allowed per parent Zero or one module-version statement is allowed per parent
statement. NO substatements are allowed. statement. NO substatements are allowed.
skipping to change at page 20, line 12 skipping to change at page 15, line 23
} }
description description
"The semantic version for this submodule in MAJOR.MINOR.PATCH format. This version "The semantic version for this submodule in MAJOR.MINOR.PATCH format. This version
must match the semver:module-version value in specific revision of the submodule must match the semver:module-version value in specific revision of the submodule
loaded in this module-set."; loaded in this module-set.";
} }
} }
} }
<CODE ENDS> <CODE ENDS>
5. Contributors 4. Contributors
o Anees Shaikh, Google o Anees Shaikh, Google
o Rob Shakir, Google o Rob Shakir, Google
6. Security Considerations 5. Security Considerations
The document does not define any new protocol or data model. There The document does not define any new protocol or data model. There
are no security impacts. are no security impacts.
7. IANA Considerations 6. IANA Considerations
7.1. YANG Module Registrations 6.1. YANG Module Registrations
The following YANG module is requested to be registred in the "IANA The following YANG module is requested to be registred in the "IANA
Module Names" registry: Module Names" registry:
The ietf-semver module: The ietf-semver module:
o Name: ietf-semver o Name: ietf-semver
o XML Namespace: urn:ietf:params:xml:ns:yang:ietf-semver o XML Namespace: urn:ietf:params:xml:ns:yang:ietf-semver
o Prefix: semver o Prefix: semver
o Reference: [RFCXXXX] o Reference: [RFCXXXX]
8. References 7. References
8.1. Normative References 7.1. Normative References
[I-D.verdt-netmod-yang-versioning-reqs]
Clarke, J., "YANG Module Versioning Requirements", draft-
verdt-netmod-yang-versioning-reqs-00 (work in progress),
July 2018.
[RFC7895] Bierman, A., Bjorklund, M., and K. Watsen, "YANG Module [RFC7895] Bierman, A., Bjorklund, M., and K. Watsen, "YANG Module
Library", RFC 7895, DOI 10.17487/RFC7895, June 2016, Library", RFC 7895, DOI 10.17487/RFC7895, June 2016,
<https://www.rfc-editor.org/info/rfc7895>. <https://www.rfc-editor.org/info/rfc7895>.
[RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language",
RFC 7950, DOI 10.17487/RFC7950, August 2016, RFC 7950, DOI 10.17487/RFC7950, August 2016,
<https://www.rfc-editor.org/info/rfc7950>. <https://www.rfc-editor.org/info/rfc7950>.
8.2. Informative References 7.2. Informative References
[I-D.clacla-netmod-model-catalog] [I-D.clacla-netmod-model-catalog]
Clarke, J. and B. Claise, "YANG module for Clarke, J. and B. Claise, "YANG module for
yangcatalog.org", draft-clacla-netmod-model-catalog-03 yangcatalog.org", draft-clacla-netmod-model-catalog-03
(work in progress), April 2018. (work in progress), April 2018.
[I-D.claise-semver] [I-D.claise-semver]
Claise, B., Barnes, R., and J. Clarke, "Semantic Claise, B., Barnes, R., and J. Clarke, "Semantic
Versioning and Structure for IETF Specifications", draft- Versioning and Structure for IETF Specifications", draft-
claise-semver-02 (work in progress), January 2018. claise-semver-02 (work in progress), January 2018.
skipping to change at page 21, line 31 skipping to change at page 16, line 48
[I-D.openconfig-netmod-model-catalog] [I-D.openconfig-netmod-model-catalog]
Shaikh, A., Shakir, R., and K. D'Souza, "Catalog and Shaikh, A., Shakir, R., and K. D'Souza, "Catalog and
registry for YANG models", draft-openconfig-netmod-model- registry for YANG models", draft-openconfig-netmod-model-
catalog-02 (work in progress), March 2017. catalog-02 (work in progress), March 2017.
[openconfigsemver] [openconfigsemver]
"Semantic Versioning for Openconfig Models", "Semantic Versioning for Openconfig Models",
<http://www.openconfig.net/docs/semver/>. <http://www.openconfig.net/docs/semver/>.
[RFC8049] Litkowski, S., Tomotaki, L., and K. Ogaki, "YANG Data
Model for L3VPN Service Delivery", RFC 8049,
DOI 10.17487/RFC8049, February 2017,
<https://www.rfc-editor.org/info/rfc8049>.
[RFC8199] Bogdanovic, D., Claise, B., and C. Moberg, "YANG Module
Classification", RFC 8199, DOI 10.17487/RFC8199, July
2017, <https://www.rfc-editor.org/info/rfc8199>.
[RFC8299] Wu, Q., Ed., Litkowski, S., Tomotaki, L., and K. Ogaki,
"YANG Data Model for L3VPN Service Delivery", RFC 8299,
DOI 10.17487/RFC8299, January 2018,
<https://www.rfc-editor.org/info/rfc8299>.
[semver] "Semantic Versioning 2.0.0", <https://www.semver.org>. [semver] "Semantic Versioning 2.0.0", <https://www.semver.org>.
[yangcatalog] [yangcatalog]
"YANG Catalog", <https://yangcatalog.org>. "YANG Catalog", <https://yangcatalog.org>.
Appendix A. Appendix Appendix A. Appendix
A.1. Open Issues
There are a number of open issues to be disccused. These include the A.1. Open Issues: Requirements to be Addressed
following:
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 it is believed one could work within this semver scheme to
support multiple parallel trains of development within a given
YANG module, some thought should be given to how this would work
in support of optional requirement 4.4 of
[I-D.verdt-netmod-yang-versioning-reqs].
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? o Do we need a new version of YANG?
While eventually this will fold into a new version, the belief is While eventually this will fold into a new version, the belief is
this solution can work with extensions alone with an update to the this solution can work with extensions alone with an update to the
[RFC7950] text concerning module updates. [RFC7950] text concerning module updates.
o Should IETF/IANA officially generate derived semantic versions for o Should IETF/IANA officially generate derived semantic versions for
their own modules? As they are the owner of the modules it should their own modules? As they are the owner of the modules it should
be their responsibility, but how to document it? Note that next be their responsibility, but how to document it? Note that next
round of funding for the yangcatalog.org could help develop the round of funding for the yangcatalog.org could help develop the
perfect derived-semantic-version toolset perfect derived-semantic-version toolset
o We could consider a new naming convention for module files. o We could consider a new naming convention for module files.
Today, module files are named using a module@revision.yang Today, module files are named using a module@revision.yang
notation. We could consider module%semver.yang or notation. We could consider module%semver.yang or
module#version.yang variants. Re-using the '@' for version is not module#version.yang variants. Re-using the '@' for version is not
ideal, so another separator character should be used. In this ideal, so another separator character should be used. In this
manner, both version and revision could be used. manner, both version and revision could be used.
o Taking another page from Openconfig, the notion of a module bundle
could be considered. That is, there may need to be a way to
enumerate modules that are part of a bundle and are known to
interoperate. This may not be as critical if a rich import-by-
version is defined.
While the issue is interesting, it will be not be handled in this
document.
o Similarly, the concept of a feature bundle should be considered.
Typically, operators combine and test YANG modules to build value-
add services. These bundles form releases for specific features
or services, and it is critical to ensure as the modules evolve,
the bundles can coherently evolve with them.
While the issue is interesting, it will be not be handled in this
document.
o When we'll start using this new procedure for a new YANG module
revision, will we have to update all the dependent YANG modules to
start using this new procedure, along with the new import
statement? Is this a moot point, as a new YANG module name would
suffer from the same symptoms?
We see no need for updating other dependent modules. It is a good
idea to update them, as they will benefit from using SEMVER,
however there is no specific need to update them.
Authors' Addresses Authors' Addresses
Benoit Claise Benoit Claise
Cisco Systems, Inc. Cisco Systems, Inc.
De Kleetlaan 6a b1 De Kleetlaan 6a b1
1831 Diegem 1831 Diegem
Belgium Belgium
Phone: +32 2 704 5622 Phone: +32 2 704 5622
Email: bclaise@cisco.com Email: bclaise@cisco.com
 End of changes. 44 change blocks. 
323 lines changed or deleted 117 lines changed or added

This html diff was produced by rfcdiff 1.48. The latest version is available from http://tools.ietf.org/tools/rfcdiff/