< draft-verdt-netmod-yang-solutions-00.txt   draft-verdt-netmod-yang-solutions-01.txt >
Network Working Group R. Wilton Network Working Group R. Wilton, Ed.
Internet-Draft Cisco Systems, Inc. Internet-Draft Cisco Systems, Inc.
Intended status: Informational October 22, 2018 Intended status: Informational July 3, 2019
Expires: April 25, 2019 Expires: January 4, 2020
YANG Versioning Potential Solutions YANG Versioning Solution Overview
draft-verdt-netmod-yang-solutions-00 draft-verdt-netmod-yang-solutions-01
Abstract Abstract
This 'work in progress' document describes and evaluates potential This temporary document gives a brief overview of the different
solutions to the requirements stated in section 5 of the YANG drafts that comprise a full solution to the YANG versioning
versioning requirements draft. The aim of this draft is to only requirements draft. The purpose of this draft is to help readers
provide a progress update to the Netmod WG concerning the YANG understand how the discrete parts of the YANG versioning solution fit
versioning design team discussions on potential solutions, and to together during working group development of the solution drafts.
hopefully provide minimally sufficient information to allow the wider
Netmod community to provide input into the direction of the YANG
versioning design team.
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
provisions of BCP 78 and BCP 79. provisions of BCP 78 and BCP 79.
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 April 25, 2019. This Internet-Draft will expire on January 4, 2020.
Copyright Notice Copyright Notice
Copyright (c) 2018 IETF Trust and the persons identified as the Copyright (c) 2019 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. Terminology and Conventions . . . . . . . . . . . . . . . . . 2 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Summary of requirements . . . . . . . . . . . . . . . . . . . 2
3. Background . . . . . . . . . . . . . . . . . . . . . . . . . 3 3. Solution Drafts . . . . . . . . . . . . . . . . . . . . . . . 4
4. Summary of requirements . . . . . . . . . . . . . . . . . . . 4 3.1. Updated YANG Module Revision Handling . . . . . . . . . . 4
5. Potential solutions to core YANG versioning requirements . . 5 3.2. Module semantic version number scheme . . . . . . . . . . 5
5.1. Module level 'major.minor.patch' semantic versioning . . 6 3.3. Versioned YANG packages . . . . . . . . . . . . . . . . . 5
5.2. Module level 'major.minor.patch(x)' modified semantic 3.4. Protocol operations for package version selection . . . . 6
versioning . . . . . . . . . . . . . . . . . . . . . . . 7 3.5. YANG schema comparison tooling . . . . . . . . . . . . . 6
5.3. Module level 'release.major.minor.patch' partial semantic 4. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 7
versioning . . . . . . . . . . . . . . . . . . . . . . . 9 5. Security Considerations . . . . . . . . . . . . . . . . . . . 7
5.4. A tool based approach comparing YANG schema modules/trees 10 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8
5.5. Follow existing RFC 7950 rules . . . . . . . . . . . . . 11 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 8
6. Solutions to related YANG versioning issues . . . . . . . . . 12 7.1. Normative References . . . . . . . . . . . . . . . . . . 8
7. Open Questions . . . . . . . . . . . . . . . . . . . . . . . 12 7.2. Informative References . . . . . . . . . . . . . . . . . 8
7.1. Is YANG module revision date preserved? . . . . . . . . . 13 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 9
7.2. Do YANG update rules allow for bug fixes? . . . . . . . . 13
7.3. Does one size fit all? . . . . . . . . . . . . . . . . . 13
7.4. Should vendors we allowed to version YANG modules as part
of a release train? . . . . . . . . . . . . . . . . . . . 13
7.5. How should versioning apply to submodules? . . . . . . . 14
7.6. Is having a patch version number useful for YANG modules? 14
8. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 14
9. Security Considerations . . . . . . . . . . . . . . . . . . . 15
10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 15
11. References . . . . . . . . . . . . . . . . . . . . . . . . . 15
11.1. Normative References . . . . . . . . . . . . . . . . . . 15
11.2. Informative References . . . . . . . . . . . . . . . . . 15
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 15
1. Terminology and Conventions
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in [RFC2119].
This document also makes use of the terminology introduced in the
YANG versioning requirements draft (REF REQUIRED). In addition, this
document introduces the following terminology:
o bc: Used as an abbreviation for a backwards-compatible change.
o nbc: Used as an abbreviation for a non-backwards-compatible
change.
o editorial change: A backwards-compatible change that does not
change the YANG module semantics in any way.
2. Introduction 1. Introduction
This draft represents transient work in progress, and should be read [I-D.ietf-netmod-yang-versioning-reqs] documents the requirements for
as such. In particular, the descriptions of the solutions are not any solution to the YANG versioning problem. Chapter 5 lists the
intended to be complete, nor necessarily consider all scenarios, but formal requirements that a complete solution requires.
instead are intended to explore the broad approach and key aspects of
the particular solution. The solution descriptions do not address
all requirements at this time, instead they focus on the requirements
that have the most significance on the final direction of the
solution. Nor does this draft recommend any particular solution or
solutions at this time. It is anticipated that once a final solution
approach has been decided upon, that a separate draft shall be
produced that will supersede this temporary draft.
The remainder of this document is split into the following sections: The aim of this draft is to help readers understand how the different
solution drafts fit together, and also which drafts contribute
solutions to particular individual requirements. The overall
solution comprises five individual drafts:
Chapter Section 4 provides a condensed summary of the requirements, 1. [I-D.verdt-netmod-yang-module-versioning]
taken from [I-D.verdt-netmod-yang-versioning-reqs]. This section
also lists where in the document these requirements are considered,
if at all.
A significant part of this document is aimed at discussing the 2. Module semantic version number scheme (not yet published)
potential 'core' solutions, which are focussed on solving
requirements: R1.1, R1.2, R1.4, R2.1, R2.2 and R4.4, and described in
chapter Section 5.
Possible solutions for some of the secondary requirements, such as 3. [I-D.rwilton-netmod-yang-packages]
datanode lifecycle management, are considered in chapter Section 6.
In particular, possible solutions for requirements R1.3, R4.1, R4.2
and R4.3 are considered.
Finally, chapter Section 7 lists some of the open issues that the 4. [I-D.wilton-netmod-yang-ver-selection]
YANG versioning design team are considering and working through. For
some questions, a tentative design team direction of the answer is
also given.
3. Background 5. YANG schema comparison tooling (not yet published)
Some members of the design team are authors of a potential solution Open issues, across all of the solution drafts are tracked at
draft to the YANG versioning requirements. The purpose of this <https://github.com/netmod-wg/yang-ver-dt/issues>.
document is to ensure that all reasonable solutions to the YANG
versioning problem have been properly considered before converging on
a single chosen solution.
4. Summary of requirements 2. Summary of requirements
The requirement themselves are documented in section 5 of XXX. A The requirements are formally documented in section 5 of
shortened, non normative, summary of each of the requirements (using [I-D.ietf-netmod-yang-versioning-reqs]. A shortened, non normative,
the same requirement numbers) is provided below to aid evaluation of summary of each of the requirements (using the same requirement
the potential solutions. numbers) is provided below to help understand how the solutions
drafts address the particular requirements.
Req 1.1 - MUST support nbc updates without breaking imports. Req 1.1 - MUST allow nbc updates to a module without breaking
imports.
Req 1.2 - MUST support nbc updates without breaking existing Req 1.2 - MUST allow nbc updates to a module without affecting
client code. existing client code using only unchanged data nodes.
Req 1.3 - MUST support import stmt restricted to only some Req 1.3 - MUST support import statement restricted to only some
revisions. revisions.
Req 1.4 - MUST support modules to be versioned by software Req 1.4 - MUST allow for fixes to non-latest published modules.
release.
Req 2.1 - MUST be able to determine if two arbitrary versions of Req 2.1 - MUST be able to determine if two arbitrary versions of
any MODULE are unchanged, bc, or nbc. any module are backwards-compatible.
Req 2.2 - SHOULD be able to determine if two arbitrary versions of Req 2.2 - SHOULD be able to determine if two arbitrary versions of
any DATA NODE are unchanged, bc, or nbc. any data node are backwards-compatible.
Req 3.1 - MUST allow servers to support existing clients. Req 3.1 - MUST allow servers to support existing clients.
Req 3.2 - MUST allow for simultaneously support of clients using Req 3.2 - MUST allow simultaneously support of clients using
different (perhaps restricted) revisions. different (perhaps restricted) revisions.
Req 4.1 - MUST provide way to indicate if deprecated nodes are Req 3.3 - MAY assume clients can handle unexpected instance data
implemented. gracefully.
Req 4.2 - MUST be able to document reason for lifecycle changes, Req 4.1 - MUST provide a way to indicate if deprecated nodes are
and possible alternative data nodes. implemented.
Req 4.3 - MUST be able to forewarn of future lifecycle changes. Req 4.2 - MUST be able to document the reason for data node
lifecycle changes, and possible alternative data nodes.
Req 4.4 - SHOULD allow fixes to older revision of a module. Req 4.3 - MUST be able to forewarn of future data node lifecycle
changes.
Req 5.1 - MUST provide guidance on how to use the new scheme. Req 5.1 - MUST provide guidance on how to use the new scheme.
Req 5.2 - MUST provide, and document, an upgrade path from Req 5.2 - MUST provide, and document, an upgrade path from
existing YANG/protocols. existing YANG/protocols.
Req 5.3 - MUST consider versioning impact on instance data. Req 5.3 - MUST consider the impact of versioning on instance data.
The following list indicates where solutions for particular
requirements are considered in this draft.
Req 1.1 - Section 5, core solutions
Req 1.2 - Section 5, core solutions
Req 1.3 - Section 6, extra solutions
Req 1.4 - Section 5, core solutions
Req 2.1 - Section 5, core solutions
Req 2.2 - Section 5, core solutions
Req 3.1 - Deferred until main solution direction is chosen.
Req 3.2 - Deferred until main solution direction is chosen.
Req 4.1 - Section 6, extra solutions
Req 4.2 - Section 6, extra solutions
Req 4.3 - Section 6, extra solutions
Req 4.4 - Section 5, core solutions
Req 5.1 - Deferred until main solution direction is chosen.
Req 5.2 - Deferred untli main solution direction is chosen.
Req 5.3 - Deferred until main solution direction is chosen.
5. Potential solutions to core YANG versioning requirements
This section considers solutions that are aimed at solving the main
YANG versioning requirements. In particular, the solutions described
here are aimed at solving the following requirements: R1.1, R1.2,
R1.4, R2.1, R2.2 and R4.4.
The solutions being considered are:
1. Module level 'major.minor.patch' semantic versioning
2. Module level 'major.minor.patch(x)' modified semantic versioning
3. Module level 'release.major.minor.patch' versioning
4. A tool based approach comparing YANG schema modules/trees
5. Follow existing RFC 7950 rules
5.1. Module level 'major.minor.patch' semantic versioning
This solution introduces a module level version number that adopts a
subset of the semantic versioning rules published at semver.org.
The key part of this solution is a version number that comprises
three fields, 'major.minor.patch':
1. major - updated only when a non-backwards-compatible change is
made
2. minor - updated only when a backwards-compatible change is made
3. patch - updated only for 'editorial' changes that do not change
the API semantics in any way
When a field in the version number is incremented, all following
fields are reset back to 0. Major version number 0 indicates that
the module is not yet stable and allows non-backwards-compatible
changes without requiring the major version number to be incremented
(e.g., this could be used in IETF drafts before they become RFCs).
If this solution is adopted, it is assumed that vendors would need to
manage versioning of vendor YANG models independently of software
release trains, and even then they would be limited in the scope of
what changes are possible in an already shipped release, which is
anticipated to not meet the business requirements of some vendors.
Solution advantages:
1. Follows widely known semantic versioning rules.
2. Version number alone indicates whether 2 module revisions are
backwards-compatible.
3. Sufficient for most (but not necessarily all) YANG models
developed by SDOs.
4. Matches the scheme being used by OpenConfig YANG models.
Solution disadvantages:
1. Does not fully support long lived vendor software release trains.
In particular:
Does not necessarily allow for backwards-compatible changes
(enhancements or fixes) in older releases.
Does not allow for non-backwards-compatible changes
(enhancements or fixes) in older releases.
2. The 'patch' field is not as useful for YANG modules (which act
like an API), since 'editorial' changes are likely to be less
common that backwards-compatible enhancements and fixes.
5.2. Module level 'major.minor.patch(x)' modified semantic versioning
This solution modifies the semantic versioning solution described
previously, with the principal aim of allow fixes to released code.
The change to the semantic versioning solution is a modification to
how the 'patch' field is used. In addition to 'editorial' changes
that do not change the YANG module semantics, the patch field can
also be used in a limited way to indicate major and minor version
changes as well. If the patch field is incremented for a minor
version change that it is appended with the suffix '(m)', if the
patch field is incremented for a major version change then it is
appended with the suffix '(M)', replacing '(m)', if present. Once a
given 'major.minor' version has a patch field value with '(m)' or
'(M)' then all subsequent patch revisions on the same 'major.minor'
version retain the letter '(m)' or '(M)' regardless of whether the
subsequent changes are backwards-compatible, non-backwards-
compatible, or editorial changes.
The updated semantic versioning rules for updating the
'major.minor.patch' version number is as follows:
1. if a non-backwards-compatible change is made then either the
major version number MUST be updated (resetting the minor and
patch version numbers to 0) or only the patch version number MUST
be updated and appended with '(M)', replacing '(m)' if present.
2. if a backwards-compatible change is made then either the minor
version number MUST be updated (resetting the patch version
numbers to 0) or only the patch version number MUST be updated
and appended with '(m)' unless the previous patch version number
already had '(M)' appended, in which case the '(M)' suffix is
retained for the new patch version.
3. if an editorial change is made then the patch version number MUST
be updated. If the previous patch version number already had
either an '(m') or '(M)' suffix then it is retained for the new
patch version.
When a field in the version number is incremented, all following
fields are reset back to 0. Major version number 0 indicates that
the module is not yet stable and allows non-backwards-compatible
changes without requiring the major version number to be incremented
(e.g., this could be used in IETF drafts before they become RFCs).
If this solution is adopted, it is assumed that vendors would need to
manage versioning of vendor YANG models independently of software
release trains, but that they are able to release fixes to bugs in
YANG module versions that are present in long lived software
releases.
Where possible, the version number should be updated using the 3. Solution Drafts
standard semantic versioning rules, relying on the '(m)' and '(M)'
suffixes only used where strictly necessary.
Solution advantages: The complete solution to the YANG versioning requirements comprises
five solution drafts, that are summarized below.
1. Allows fixes to released YANG modules, whilst still preserving 3.1. Updated YANG Module Revision Handling
semver like semantics.
2. Aims to be sufficient for SDO and vendor YANG modules. In summary, [I-D.verdt-netmod-yang-module-versioning] specifies
minimal extensions and updates to the YANG language, YANG Library,
and YANG author guidelines to provide more flexible YANG module
revision handling. The intent is that these changes and extensions
could be folded into future revisions of the updated specifications.
The draft provides a solution for all requirements except Req 2.2,
Req 3.1 and Req 3.2.
3. Modules can choose to just use semver rules if they wish. E.g. The extensions and changes in the draft can be summarized thus:
the scheme is compatible with the scheme being used by OpenConfig
YANG models.
Solution disadvantages: o It defines a YANG extension statement to indicate where non-
backwards-compatible changes have occurred in a module's revision
history.
1. Slightly more complex than standard semver.org rules. The (m|M) o It relaxes the rules for the module revision history to allow for
suffix may be confusing, and their significance misinterpreted. a non-linear module revision history. I.e., any given module
revision may have multiple revisions directly derived from it.
2. Within a 'major.minor' version branch it is not possible to o It defines a new import extension statement that restricts the
determine whether a specific change is backwards-compatible or allowed module revisions that satisfy the import to only those
not. derived from a specified module revision.
3. If on a version with the (m) suffix, e.g. 'A.B.C(m)', it is not o It defines a revision label extension statement to allow an
possible to determine whether an update to 'A.D.E', where D > B informative name to be associated with a particular revision date,
is a backwards-compatible change. and to be used in import statements, YANG module filenames, and is
available in YANG library. One example of how the revision label
could be used is to associate a semantic versioning scheme to YANG
module revisions.
Variants: o It updates the YANG rules for changes between module revisions
that are allowed to be classified as backwards-compatible. In
particular, marking a node as obsolete is no longer classified as
a backwards compatible change.
Rather than using '(m)' or '(M)', it could instead use separate o It provides updated guidance on how servers handle deprecated and
counters for bc and nbc changes, facilitating meaningful semantic obsolete YANG nodes and augments YANG library with additional
versioning comparison between different patch versions on leaves to report the server's behavior to clients.
'major.minor' branch.
Rather than overloading the patch version number, separate o It provides an extension statement to allow a description
semantic version numbers could be used on branches. E.g. if a bc statement to be associated with a YANG status statement, providing
fix was required to version '1.2.3' this could be presented as more information about why the status has changed.
'1.2.3/1.1.0', if there was a further nbc fix then the next branch
version would be '1.2.3/2.0.0'.
5.3. Module level 'release.major.minor.patch' partial semantic o It defines how versioning relates to YANG instance data.
versioning
This solution extends the semver 'major.minor.patch' version number o It refines the guidelines for updating modules, taking into
scheme, by prefixing it with an explicit software release positive consideration that non-backwards-compatible changes are sometimes
integer field. necessary for various pragmatic reasons.
The key part of this solution is a version number comprising four 3.2. Module semantic version number scheme
fields (release.major.minor.patch):
1. release - may be updated at any time (e.g. for a new major [TODO - Insert draft ref] defines a semantic versioning scheme
software release) derived from the semver.org 2.0.0 specification that can be used in
conjunction with the revision label extension statement defined in
Section 3.1 to allow semantic version numbers to be used to manage
the revision lifecycle of YANG modules. This draft provides an
enhanced solution for Req 2.1, but organizations authoring modules
are not obliged to use this specific versioning scheme, and could
choose a different overlaid versioning scheme, or none at all and
rely solely on revision dates.
2. major - updated only when a non-backwards-compatible change is The aims of the YANG semantic versioning scheme are:
made
3. minor - updated only when a backwards-compatible change is made To generally allow clients to determine whether NBC changes have
occurred between two revisions from the version number alone,
without having to check the full revision history.
4. patch - updated only only for changes that do not change the API To give a more informative identifier for a branched revision
semantics in any way history over revision dates alone.
When a field in the version number is incremented, all following To allow revision branches that contain fixes for published non-
fields are reset back to 0, except for major that resets to 1. latest releases.
Release version number 0 indicates that the version is not yet stable
and non-backwards-compatible changes are allowed without incrementing
the major version number.
The assumption for this scheme is that the release number is always 3.3. Versioned YANG packages
incremented for every major release, i.e. at any point where nbc
changes may potentially be required in an older release.
Solution advantages: The two previous drafts address version and revision management of
individual modules. [I-D.rwilton-netmod-yang-packages] provides a
mechanism to group a set of related YANG modules revisions together,
into a construct called a YANG package, and to apply a version scheme
to the group.
1. Supports long lived vendor software release trains. The core part of this draft are YANG module definitions that define a
YANG package, that are used as an augmentation to YANG library, and
also in YANG instance data documents for offline access.
2. Completely allows bc and nbc changes (enhancements or fixes) in The principle aims of the packages draft are:
older independent releases.
3. Probably sufficient for YANG models developed by both vendors and To provide an alternative simpler mechanism to manage conformance
SDOs. of modules. Rather than checking conformance against a set of
individual YANG module revisions, it should be easier to check for
conformance against a much smaller set of YANG package versions.
Solution disadvantages: To provide an easier mechanism for clients to check conformance
with a server. Rather that downloading and comparing all
individual module revisions, the client can just check whether the
package version is compatible. The package definition could be
retrieved and cached from multiple sources.
1. Release version field must be incremented regardless of changes. The YANG packages draft does not address any of the versioning
requirements directly, but provides the foundation building blocks
for the version selection solution, described in Section 3.4, that
addresses Reqs 3.1 and 3.2.
2. Version number is no longer an indicator of changes between 2 This draft requires updates to accommodate the split between revision
module revisions. I.e. the main benefit of semantic versioning management in [I-D.verdt-netmod-yang-module-versioning] and the
is lost. semantic versioning scheme.
3. Differs from the scheme used by OpenConfig YANG model. 3.4. Protocol operations for package version selection
Similar variants: [I-D.wilton-netmod-yang-ver-selection] specifies a solution for
requirements 3.1 and 3.2 is via the use of
[I-D.rwilton-netmod-yang-packages] and a protocol based version
selection scheme that can be used by clients to choose a particular
YANG datastore schema from the set of datastore schema that are
supported by the server.
The 'release' field could be regarded as optional, and if omitted, The version selection optionally allows:
the version interpreted in exactly the same way as the module
level 'major.minor.patch' semantic versioning solution.
5.4. A tool based approach comparing YANG schema modules/trees Servers to support a single, selectable YANG package at a
particular version, that is used for all NETCONF/RESTCONF
interactions.
This solution relies on using tooling to compare either two YANG Servers to support multiple selectable YANG packages and package
modules, or two YANG schema trees to identify any changes between the versions, with different clients able to concurrently access
two modules that do not conform to RFC 7950 section 11 backwards- different packages and different package versions.
compatibility rules.
Not all differences between two YANG statements in different module 3.5. YANG schema comparison tooling
versions can easily be identified as backwards-compatible or not (for
example changes in description, pattern statements, must or when
statements may be hard to check). If a tool is unable to check then
it would have to flag the change as potentially being non-backwards-
compatible, potentially reporting many false positives.
To mitigate this, it is proposed that this solution also introduces a A tooling based solution is proposed for Req 2.2, that allows two
new YANG extension statement to indicate that a change is backwards- YANG schema versions to be algorithmically compared, with the
compatible. algorithm reporting the list of differences between the two YANG
schema and whether each change is regarded as being backwards-
compatible, or non-backwards-compatible. Annotations to the YANG
modules, via the use of extension statements, may help improve the
accuracy of the comparison algorithm, particularly for statements
that are very hard to algorithmically classify the scope of any
differences (e.g., a change in the semantic behaviour of a data node
defined via modifications to the associated YANG description
statement). Given that Req 2.2 is a softer requirement, and
practical experience with the tooling is required, it is proposed
that this work is deferred at this time.
When comparing a module schema, a tool would also be able to take When comparing a module schema, a tool would also be able to take
into account enabled features, deviations, and the subset of the into account enabled features, deviations, and the subset of the
schema being used by the client. This would allow a tooling based schema being used by the client. This would allow a tooling based
approach to give a more accurate answer as to whether a client would approach to give a more accurate answer as to whether a client would
be affected when upgrading between two software versions. be affected when upgrading between two software versions, than
looking at the revision history, or comparing semantic version
Solution advantages: numbers.
1. Gives the most accurate answer that works in all cases.
Solution disadvantages:
1. Cannot easily check whether two modules are compatible just by
looking at them. Probably needs to be used in conjunction with a
module level versioning scheme.
2. Differs from the scheme used by OpenConfig YANG models.
5.5. Follow existing RFC 7950 rules
The final choice is to decide that the existing mechanism described
in RFC 7950, that disallows any non-backwards-compatible changes in a
given model, is the best way forward. Instead of making a nbc
chagne, the modeller can introduce new parallel nodes, and deprecate
the existing nodes within the same module. Alternatively an entirely
new module, with a separate name and namespace can be introduced.
As a solution, this cannot meet all of the requirements stated in the
requirements draft.
If this solution was sufficient, then the YANG versioning design team
would not have been formed. However, some vendors are pragmatically
ignoring the strict YANG module update rules (e.g. for vendor
modules).
Solution advantages:
1. No significant change in YANG language semantics required.
Changes, or perhaps extensions, could be made to the YANG
language to address some of other requirements that have
independent solutions.
Solution disadvantages:
1. If an nbc has to be made (even for a minor feature) then there is
a high impact to all clients using the module, servers
implementing the module, and other YANG modules that import from
the module. This impact would be particularly acute for a core
YANG module that is being updated in an nbc way, that is imported
by many other YANG modules. Hence, choosing this solution really
means that there can be no nbc changes to a module unless the
module is being restructured in a major way when a separate name
for the module makes sense regardless.
2. Seems to make standardization slow because participants are
seemingly try harder to get the perfect model first because the
cost of having to change it seems so high.
3. Old, dead definitions can potentially never be removed from a
module.
4. Does not work well for vendor generated YANG models, since they
cannot easily have the level or control and stability required
for it to never change.
5. Does not solve the problem where deviations are used to introduce
nbc changes.
6. Introduces a problem where a single underlying property is
represented by two (or more) independent data nodes in the same
schema. There does not appear to be a clean solution on how to
manage the relationship between these two nodes (e.g. if both an
old and new client are interacting with a server). Other
solutions have the potential of handling this better.
Variants:
One variant of this solution is to agree on the rules for making
fixes to published YANG modules, and determine whether that
requires any changes to the section 11 text in RFC 950.
6. Solutions to related YANG versioning issues
These partial solutions address particular point requirements. The
partial solutions are:
1. Deprecated flag - Add a flag to YANG library to indicate whether
deprecated nodes are implemented or not. This is a potential
solution to Req 4.1.
2. Redefine deprecated stmt - Change the definition of the YANG
deprecated statement to indicate that deprecated data nodes must
be implemented, or otherwise deviated. This is a potential
solution to Req 4.1.
3. Status description - Allow the "description" statement under the
YANG "status" statement to document data node lifecycle, and
allow for forward guidance. This is a potential solution to Reqs
4.2 and 4.3.
4. Alternative node path - Introduce a new YANG statement to provide
an alternative path for a deprecated, or obsolete, data node.
This is a potential additional solution to Req 4.2 and perhaps
also Req 4.3.
7. Open Questions
This section lists some of the open questions that the design team is
still grappling with.
7.1. Is YANG module revision date preserved?
With the introduction of the new versioning scheme, should every YANG
module still have a revision statement, or is that entirely
superseded by a new version statement? Is it required that YANG
modules revision dates MUST be unique for different versions of a
module?
The position that the DT is tending towards is:
All revision dates for YANG modules must be unique. The slight
complexity of requiring this should minimize the impact to
existing tooling.
it is acceptable to break the existing monotonically increasing
property of the current module revision date, but within a given
'stream' of YANG modules the monotonically increasing property
should be preserved.
7.2. Do YANG update rules allow for bug fixes?
Does YANG (RFC 7950) section 11 allow nbc fixes to existing models,
and if so, are there any limits as to what form those fixes can take,
or are these strictly prohibited by the module update rules?
7.3. Does one size fit all?
Potentially different types of YANG modules may want to follow
different versioning semantics.
E.g. it may be right that standardized YANG modules are very slow
changing and conservative in their backwards compatibility
Conversely, it is potentially more pragmatic that vendor YANG modules
need to change in more significant ways mirroring changes in
underlying implementations or hardware.
7.4. Should vendors we allowed to version YANG modules as part of a
release train?
Some of the solutions described in this document probably require
vendors to version vendor YANG modules outside of release trains,
which is likely to be different to how some vendors are managing this
today. Is it a reasonable constraint to put on vendors that they
MUST version YANG modules outside of a release train to provide a
cleaner version history?
7.5. How should versioning apply to submodules?
Submodules can have different revision dates from the including
parent module. Does this mean that submodules should be versioned
independently of their parent module? Or should the version number
apply only at the module level?
Need to consider the upgrade rules allow definitions to be moved
between submodules.
7.6. Is having a patch version number useful for YANG modules?
The semantic versioning solution on semver.org is designed to version
both APIs and implementations. In this scenario, the patch level
versioning number is particularly useful to indicate a fix in the
implementation, where the API has not changed. The versioning for
YANG modules is primarily concerned with the API semantics rather
than implementation, and hence the patch level version number is not
so directly useful, where its purpose is limited to changes that do
not affect semantics of the YANG module (e.g. fixes to typos for
example).
8. Contributors 4. Contributors
This document grew out of the YANG module versioning design team that This document grew out of the YANG module versioning design team that
started after IETF 101. The following people are members of that started after IETF 101. The following individuals are (or have been)
design team and have contributed to defining the problem and members of that design team and have contributed to defining the
specifying the requirements: problem and specifying the requirements:
o Balazs Lengyel o Balazs Lengyel
o Benoit Claise o Benoit Claise
o Ebben Aries o Ebben Aries
o Jason Sterne o Jason Sterne
o Joe Clarke o Joe Clarke
skipping to change at page 15, line 4 skipping to change at page 7, line 41
o Juergen Schoenwaelder o Juergen Schoenwaelder
o Mahesh Jethanandani o Mahesh Jethanandani
o Michael (Wangzitao) o Michael (Wangzitao)
o Qin Wu o Qin Wu
o Reshad Rahman o Reshad Rahman
o Rob Wilton o Rob Wilton
o Susan Hares o Susan Hares
9. 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
is no security impact. is no security impact.
10. IANA Considerations 6. IANA Considerations
None None
11. References 7. References
11.1. Normative References 7.1. Normative References
[I-D.verdt-netmod-yang-versioning-reqs] [I-D.ietf-netmod-yang-versioning-reqs]
Clarke, J., "YANG Module Versioning Requirements", draft- Clarke, J., "YANG Module Versioning Requirements", draft-
verdt-netmod-yang-versioning-reqs-01 (work in progress), ietf-netmod-yang-versioning-reqs-00 (work in progress),
October 2018. March 2019.
[I-D.rwilton-netmod-yang-packages]
Wilton, R., "YANG Packages", draft-rwilton-netmod-yang-
packages-01 (work in progress), March 2019.
[I-D.verdt-netmod-yang-module-versioning]
Claise, B., Clarke, J., Rahman, R., Wilton, R., Lengyel,
B., Sterne, J., and K. D'Souza, "Updated YANG Module
Revision Handling", draft-verdt-netmod-yang-module-
versioning-00 (work in progress), July 2019.
[I-D.wilton-netmod-yang-ver-selection]
Wilton, R. and R. Rahman, "YANG Schema Version Selection",
draft-wilton-netmod-yang-ver-selection-00 (work in
progress), March 2019.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997, DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>. <https://www.rfc-editor.org/info/rfc2119>.
[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>.
11.2. Informative References 7.2. Informative References
[RFC8049] Litkowski, S., Tomotaki, L., and K. Ogaki, "YANG Data [RFC8049] Litkowski, S., Tomotaki, L., and K. Ogaki, "YANG Data
Model for L3VPN Service Delivery", RFC 8049, Model for L3VPN Service Delivery", RFC 8049,
DOI 10.17487/RFC8049, February 2017, DOI 10.17487/RFC8049, February 2017,
<https://www.rfc-editor.org/info/rfc8049>. <https://www.rfc-editor.org/info/rfc8049>.
[RFC8199] Bogdanovic, D., Claise, B., and C. Moberg, "YANG Module [RFC8199] Bogdanovic, D., Claise, B., and C. Moberg, "YANG Module
Classification", RFC 8199, DOI 10.17487/RFC8199, July Classification", RFC 8199, DOI 10.17487/RFC8199, July
2017, <https://www.rfc-editor.org/info/rfc8199>. 2017, <https://www.rfc-editor.org/info/rfc8199>.
[RFC8299] Wu, Q., Ed., Litkowski, S., Tomotaki, L., and K. Ogaki, [RFC8299] Wu, Q., Ed., Litkowski, S., Tomotaki, L., and K. Ogaki,
"YANG Data Model for L3VPN Service Delivery", RFC 8299, "YANG Data Model for L3VPN Service Delivery", RFC 8299,
DOI 10.17487/RFC8299, January 2018, DOI 10.17487/RFC8299, January 2018,
<https://www.rfc-editor.org/info/rfc8299>. <https://www.rfc-editor.org/info/rfc8299>.
Author's Address Author's Address
Robert Wilton
Robert Wilton (editor)
Cisco Systems, Inc. Cisco Systems, Inc.
Email: rwilton@cisco.com
 End of changes. 78 change blocks. 
542 lines changed or deleted 212 lines changed or added

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