diff --git a/yang-semver/draft-verdt-netmod-yang-semver.txt b/yang-semver/draft-verdt-netmod-yang-semver.txt index 5972a77..641ca00 100644 --- a/yang-semver/draft-verdt-netmod-yang-semver.txt +++ b/yang-semver/draft-verdt-netmod-yang-semver.txt @@ -6,14 +6,14 @@ Network Working Group B. Claise Internet-Draft J. Clarke Updates: 7950 (if approved) R. Rahman Intended status: Standards Track R. Wilton, Ed. -Expires: September 8, 2019 Cisco Systems, Inc. +Expires: September 11, 2019 Cisco Systems, Inc. B. Lengyel Ericsson J. Sterne Nokia K. D'Souza AT&T - March 7, 2019 + March 10, 2019 YANG Semantic Versioning for Modules @@ -35,14 +35,14 @@ Status of This Memo Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- - Drafts is at http://datatracker.ietf.org/drafts/current/. + Drafts is at https://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." - This Internet-Draft will expire on September 8, 2019. + This Internet-Draft will expire on September 11, 2019. Copyright Notice @@ -53,14 +53,14 @@ Copyright Notice -Claise, et al. Expires September 8, 2019 [Page 1] +Claise, et al. Expires September 11, 2019 [Page 1] Internet-Draft YANG Module Versioning March 2019 This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents - (http://trustee.ietf.org/license-info) in effect on the date of + (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must @@ -71,59 +71,63 @@ Internet-Draft YANG Module Versioning March 2019 Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 - 1.1. Changes to YANG RFCs . . . . . . . . . . . . . . . . . . 4 - 1.1.1. Changes to RFC7950 . . . . . . . . . . . . . . . . . 4 - 1.1.2. Changes to RFC8525 . . . . . . . . . . . . . . . . . 4 - 1.1.3. Changes to RFC8407 . . . . . . . . . . . . . . . . . 4 + 1.1. Updates to YANG RFCs . . . . . . . . . . . . . . . . . . 4 + 1.1.1. Updates to RFC7950 . . . . . . . . . . . . . . . . . 4 + 1.1.2. Updates to RFC8525 . . . . . . . . . . . . . . . . . 4 + 1.1.3. Updates to RFC8407 . . . . . . . . . . . . . . . . . 5 1.2. Complementary solutions for the other requirements . . . 5 - 2. YANG Semantic Versioning . . . . . . . . . . . . . . . . . . 5 + 2. YANG Semantic Versioning . . . . . . . . . . . . . . . . . . 6 2.1. Classification of changes between module revisions . . . 6 - 2.2. YANG Semantic Versioning Scheme for Modules . . . . . . . 6 - 2.3. YANG Semantic Version Update Rules . . . . . . . . . . . 8 - 2.4. YANG Module Semver Extension . . . . . . . . . . . . . . 9 - 3. Import by Semantic Version . . . . . . . . . . . . . . . . . 11 - 3.1. Module import examples . . . . . . . . . . . . . . . . . 12 - 3.2. TODO . . . . . . . . . . . . . . . . . . . . . . . . . . 13 - 4. Updates to YANG 1.1 Module Update Rules . . . . . . . . . . . 13 - 5. Updates to ietf-yang-library . . . . . . . . . . . . . . . . 14 - 5.1. Resolving ambiguous module imports . . . . . . . . . . . 14 - 5.2. Reporting how deprecated and obsolete nodes are handled . 15 - 6. YANG status description extension . . . . . . . . . . . . . . 16 - 7. Semantic versioning of YANG instance data . . . . . . . . . . 16 - 8. Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . 17 - 8.1. Guidelines to YANG model authors . . . . . . . . . . . . 17 - 8.1.1. Use of semantic versioning . . . . . . . . . . . . . 17 + 2.2. YANG Semantic Versioning Scheme for Modules . . . . . . . 7 + 2.2.1. Examples for YANG semantic version numbers . . . . . 8 + 2.3. YANG Semantic Version Update Rules . . . . . . . . . . . 10 + 2.4. YANG Module Semver Extension . . . . . . . . . . . . . . 11 + 3. Import by Semantic Version . . . . . . . . . . . . . . . . . 13 + 3.1. Module import examples . . . . . . . . . . . . . . . . . 15 + 4. Classifying changes in YANG modules . . . . . . . . . . . . . 16 + 4.1. Editorial changes . . . . . . . . . . . . . . . . . . . . 16 + 4.2. Backwards-compatible changes . . . . . . . . . . . . . . 16 + 4.3. Non-backwards-compatible changes . . . . . . . . . . . . 17 + 5. Updates to ietf-yang-library . . . . . . . . . . . . . . . . 17 + 5.1. Advertising module version number . . . . . . . . . . . . 17 + 5.2. Resolving ambiguous module imports . . . . . . . . . . . 17 + 5.3. Reporting how deprecated and obsolete nodes are handled . 18 + 6. YANG status description extension . . . . . . . . . . . . . . 19 + 7. Semantic versioning of YANG instance data . . . . . . . . . . 19 + 8. Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . 20 + 8.1. Guidelines to YANG model authors . . . . . . . . . . . . 20 + 8.1.1. Use of YANG semantic versioning . . . . . . . . . . . 20 8.1.2. Making non-backwards-compatible changes to a YANG - module . . . . . . . . . . . . . . . . . . . . . . . 18 - 8.1.2.1. Removing a data node . . . . . . . . . . . . . . 20 - 8.1.2.2. Changing the type of a leaf node . . . . . . . . 20 - 8.1.2.3. Reducing the range of a leaf node . . . . . . . . 21 - 8.1.2.4. Changing the key of a list . . . . . . . . . . . 21 - 8.1.2.5. Renaming a node . . . . . . . . . . . . . . . . . 21 - 8.1.2.6. Changing a default value . . . . . . . . . . . . 21 - 8.2. Guidelines to YANG model clients . . . . . . . . . . . . 21 - 9. Semantic Version Extension YANG Module . . . . . . . . . . . 21 - 10. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 28 - 11. Security Considerations . . . . . . . . . . . . . . . . . . . 28 - 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 29 - - - -Claise, et al. Expires September 8, 2019 [Page 2] + module . . . . . . . . . . . . . . . . . . . . . . . 21 + 8.1.2.1. Removing a data node . . . . . . . . . . . . . . 22 + 8.1.2.2. Changing the type of a leaf node . . . . . . . . 23 + 8.1.2.3. Reducing the range of a leaf node . . . . . . . . 23 + 8.1.2.4. Changing the key of a list . . . . . . . . . . . 23 + 8.1.2.5. Renaming a node . . . . . . . . . . . . . . . . . 23 + 8.1.2.6. Changing a default value . . . . . . . . . . . . 23 + 8.2. Guidelines to YANG model clients . . . . . . . . . . . . 24 + + + +Claise, et al. Expires September 11, 2019 [Page 2] Internet-Draft YANG Module Versioning March 2019 - 12.1. YANG Module Registrations . . . . . . . . . . . . . . . 29 - 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 29 - 13.1. Normative References . . . . . . . . . . . . . . . . . . 29 - 13.2. Informative References . . . . . . . . . . . . . . . . . 30 - Appendix A. Appendix . . . . . . . . . . . . . . . . . . . . . . 30 - A.1. Open Issues . . . . . . . . . . . . . . . . . . . . . . . 31 - A.2. Derived Semantic Version . . . . . . . . . . . . . . . . 31 - A.2.1. The Derived Semantic Version . . . . . . . . . . . . 31 - A.2.2. Implementation Experience . . . . . . . . . . . . . . 31 - Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 32 + 9. Semantic Version Extension YANG Modules . . . . . . . . . . . 24 + 10. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 30 + 11. Security Considerations . . . . . . . . . . . . . . . . . . . 31 + 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 31 + 12.1. YANG Module Registrations . . . . . . . . . . . . . . . 31 + 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 32 + 13.1. Normative References . . . . . . . . . . . . . . . . . . 32 + 13.2. Informative References . . . . . . . . . . . . . . . . . 32 + Appendix A. Appendix . . . . . . . . . . . . . . . . . . . . . . 34 + A.1. Open Issues . . . . . . . . . . . . . . . . . . . . . . . 34 + A.2. Derived Semantic Version . . . . . . . . . . . . . . . . 35 + A.2.1. The Derived Semantic Version . . . . . . . . . . . . 35 + A.2.2. Implementation Experience . . . . . . . . . . . . . . 35 + Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 36 1. Introduction @@ -137,7 +141,7 @@ Internet-Draft YANG Module Versioning March 2019 end up breaking clients. The solution makes use of semantic version numbers to help manage the lifecycle of YANG modules. - The solution is comprised of the following six parts: + The solution is comprised of the following seven parts: A definition for the YANG semantic versioning scheme for modules, and an explanation of how the semver extension can be used to @@ -149,8 +153,7 @@ Internet-Draft YANG Module Versioning March 2019 definitions. Updates to the YANG 1.1 module update rules to accommodate the - semantic versioning scheme and to provide more consistent handling - of changes to the YANG "status" statement. + semantic versioning scheme. Updates and augmentations to ietf-yang-library to include the YANG semantic version number in the module descriptions, to report how @@ -158,35 +161,39 @@ Internet-Draft YANG Module Versioning March 2019 clarify how module imports are resolved when multiple versions could otherwise be chosen. - A YANG extension to add a 'description' statement to the YANG - 'status' statement to allow additional documentation as to why a - node is being deprecated, and what alternatives may be available. -Claise, et al. Expires September 8, 2019 [Page 3] +Claise, et al. Expires September 11, 2019 [Page 3] Internet-Draft YANG Module Versioning March 2019 + A YANG extension to add a 'description' statement to the YANG + 'status' statement to allow additional documentation as to why a + node is being deprecated, and what alternatives may be available. + + A description of how YANG semantic versioning applies to YANG + instance data. + Guidelines to YANG module authors on how the YANG semantic versioning rules should be used, along with examples. - Open issues are listed at Appendix A.1, and also tracked at - https://github.com/netmod-wg/yang-ver-dt/issues + Open issues are listed at Appendix A.1, and tracked at + . -1.1. Changes to YANG RFCs +1.1. Updates to YANG RFCs -1.1.1. Changes to RFC7950 +1.1.1. Updates to RFC7950 This document proposes updates to [RFC7950] to address some of the requirements. It should be noted that there is also active WG discussion on the next steps towards an updated version of YANG, and potentially some of the functionality described here could be folded - into an updated revision of [RFC7950], although that it might - adversely impact when (parts of) a standards based YANG module - versioning solution is available for use. + into an updated revision of [RFC7950], although that might adversely + impact when (parts of) a standards based YANG module versioning + solution is available. The sections listed below provide updates to [RFC7950]. The design team does not believe any of the changes require a new version of the @@ -202,30 +209,30 @@ Internet-Draft YANG Module Versioning March 2019 o Section 6 defines an extension that adds a description child element to the YANG "status" statement. -1.1.2. Changes to RFC8525 +1.1.2. Updates to RFC8525 This document updates [RFC8525]. Section 5 defines how a reader of a YANG library datastore schema chooses which version of an import-only module is used to resolve a module import when the definition is otherwise ambiguous. -1.1.3. Changes to RFC8407 - Section 8 updates [RFC8407] to provide guidelines on how the YANG - module semantic versioning can be used to manage the lifecycle of - YANG modules when using strict RFC 7950 chapter 11 backwards - compatibility rules are not pragmatic. - - -Claise, et al. Expires September 8, 2019 [Page 4] +Claise, et al. Expires September 11, 2019 [Page 4] Internet-Draft YANG Module Versioning March 2019 +1.1.3. Updates to RFC8407 + + Section 8 updates [RFC8407] to provide guidelines on how the YANG + module semantic versioning can be used to manage the lifecycle of + YANG modules when using strict RFC 7950 chapter 11 backwards + compatibility rules are not pragmatic. + 1.2. Complementary solutions for the other requirements This section is to aid the WG understand how the full set of YANG @@ -267,28 +274,27 @@ Internet-Draft YANG Module Versioning March 2019 particular YANG datastore schema from the set of datastore schema that are supported by the server. -2. YANG Semantic Versioning - - The chapter defines YANG Semantic Versioning, explains how it is used - with YANG modules, and the rules associated with changing a module's - semantic version number when the module definitions are updated. - - -Claise, et al. Expires September 8, 2019 [Page 5] +Claise, et al. Expires September 11, 2019 [Page 5] Internet-Draft YANG Module Versioning March 2019 +2. YANG Semantic Versioning + + The chapter defines YANG Semantic Versioning, explains how it is used + with YANG modules, and the rules associated with changing a module's + semantic version number when the module definitions are updated. + The YANG semantic versioning scheme applies only to YANG modules. YANG submodules are not independently versioned by the YANG semantic versioning scheme. Instead, if a versioned module includes one or more submodules then those submodules are implicitly versioned as - part of the module's 'semver:version' statements, and all 'include' - statements MUST specify the revision-date for each of the included - submodules. + part of the module's 'semver:version' statements, and all the + module's 'include' statements MUST specify the revision-date for each + of the included submodules. 2.1. Classification of changes between module revisions @@ -300,8 +306,9 @@ Internet-Draft YANG Module Versioning March 2019 The semantic version change between any two arbitrary revisions of a YANG module can be classified into one of four categories: 'unchanged', 'editorial, 'backwards-compatible' or 'non-backwards- - compatible'. The classification is performed by use of the following - rules: + compatible'. A summary of the classification is given below, with + the specific rules as they apply to YANG statements provided in + Section 4. The semantic version change between two module revisions is defined as 'unchanged' if, after excluding 'revision' and @@ -309,35 +316,37 @@ Internet-Draft YANG Module Versioning March 2019 remaining changes are insignificant white space changes. An 'editorial' module semantic version change is where there are - changes in the module's statements, or statement ordering, between - the two module revisions, but those changes do not affect the - syntax or semantic meaning of the module in any way. An example - of an editorial change would be a fix to a spelling mistake in a - description statement. + changes in the module's statements, between the two module + revisions, but those changes do not affect the syntax or semantic + meaning of the module in any way. An example of an editorial + change would be a fix to a spelling mistake in a description + statement. A 'backwards-compatible' module semantic version change is where some syntax or semantic changes exists between the two module revisions, but all changes follow the rules specified in - Section 4. + Section 4.2. A 'non-backwards-compatible' module semantic version change is where some syntax or semantic changes exists between the two - module revisions, and those changes do not follow the rules - specified in Section 4. - -2.2. YANG Semantic Versioning Scheme for Modules - This document defines the YANG semantic versioning scheme that is - used for YANG modules. The versioning scheme has the following - properties: -Claise, et al. Expires September 8, 2019 [Page 6] +Claise, et al. Expires September 11, 2019 [Page 6] Internet-Draft YANG Module Versioning March 2019 + module revisions, and those changes do not follow the rules for a + 'backwards-compatible' version change. + +2.2. YANG Semantic Versioning Scheme for Modules + + This document defines the YANG semantic versioning scheme that is + used for YANG modules. The versioning scheme has the following + properties: + The YANG semantic versioning scheme is extended from version 2.0.0 of the semantic versioning scheme defined at semver.org [semver] to cover the additional requirements for the management of YANG @@ -358,7 +367,7 @@ Internet-Draft YANG Module Versioning March 2019 semantic versioning scheme are exactly the same as those defined by the semver.org 2.0.0 versioning scheme. - Every YANG module versioned using a YANG semantic versioning scheme + Every YANG module versioned using the YANG semantic versioning scheme specifies the module's semantic version number by including the 'semver:module-version' statement according to the following rules: @@ -376,6 +385,15 @@ Internet-Draft YANG Module Versioning March 2019 version' sub-statement if they have an associated YANG semantic version. + + + + +Claise, et al. Expires September 11, 2019 [Page 7] + +Internet-Draft YANG Module Versioning March 2019 + + "The YANG semver version number is expressed as a string of the form: 'X.Y.Zv'; where X, Y, and Z each represent non-negative integers smaller than 32768, and v represents an optional single character @@ -385,20 +403,10 @@ Internet-Draft YANG Module Versioning March 2019 indicate changes that are non-backwards-compatible to versions with a lower major version number. - - - - -Claise, et al. Expires September 8, 2019 [Page 7] - -Internet-Draft YANG Module Versioning March 2019 - - o 'Y' is the MINOR version. Changes in the minor version number indicate changes that are backwards-compatible to versions with - the same major version number, but a lower minor version number, - unless either version has a patch version with an 'm' or 'M' - modifier. + the same major version number, but a lower minor version number + and no patch 'm' or 'M' modifier. o 'Zv' is the PATCH version and modifier. Changes in the patch version number can indicate editorial, backwards-compatible, or @@ -413,18 +421,117 @@ Internet-Draft YANG Module Versioning March 2019 * 'M' - the change represents a non-backwards-compatible change - YANG requires that if two modules have the same revision date then - they MUST have the same semantic content. A similar constraint - applies for YANG semantic version numbers, i.e. two revisions of a - module that have the same semantic version numbers MUST have the same - semantic content. + The YANG module name and YANG semantic version number uniquely + identifies a revision of a module, with an associated revision date. + There MUST NOT be multiple instances of a YANG module definition with + the same module name and YANG semantic version number but different + content or revision date. + + There MUST NOT be multiple versions of a YANG module that have the + same MAJOR, MINOR and PATCH version numbers, but different patch + modifier letter. E.g., module version "1.2.3M" MUST NOT be defined + if module version "1.2.3" has already been defined. + +2.2.1. Examples for YANG semantic version numbers + + The following diagram and explanation illustrates how YANG semantic + version numbers work. + + + + + + + - A module MUST NOT have multiple revision where the version string has - the same MAJOR, MINOR and PATCH version numbers, but different PATCH - modifier letter. E.g., module version "1.2.3M" is not allowed if - module version "1.2.3" has already been defined. Neither can there - be two different revisions of a YANG module with different content - but the same + +Claise, et al. Expires September 11, 2019 [Page 8] + +Internet-Draft YANG Module Versioning March 2019 + + + Example YANG semantic version numbers for an example module: + + 0.1.0 + | + 0.2.0 + | + 1.0.0 + | \ + | 1.1.0 -> 1.1.1m -> 1.1.2M + | | + | 1.2.0 -> 1.2.1M -> 1.2.2M + | | + | 1.3.0 -> 1.3.1 + | + 2.0.0 + | + 3.0.0 + \ + 3.1.0 + + The tree diagram above illustrates how an example modules version + history might evolve. For example, the tree might represent the + following changes, listed in chronological order from oldest revision + to newest: + + 0.1.0 - first beta module version + + 0.2.0 - second beta module version (with NBC changes) + + 1.0.0 - first release (may have NBC changes from 0.2.0) + + 1.1.0 - added new functionality, leaf "foo" (BC) + + 1.2.0 - added new functionality, leaf "baz" (BC) + + 1.3.0 - improve existing functionality, added leaf "foo-64" (BC) + + 1.3.1 - improve description wording for "foo-64" (Editorial) + + 1.1.1m - backport "foo-64" leaf to 1.1.x to avoid implementing + "baz" from 1.2.0 (BC) + + 2.0.0 - change existing model for performance reasons, e.g. re-key + list (NBC) + + 1.1.2M - NBC point bug fix, not required in 2.0.0 due to model + changes (NBC) + + + + +Claise, et al. Expires September 11, 2019 [Page 9] + +Internet-Draft YANG Module Versioning March 2019 + + + 3.0.0 - NBC bugfix, rename "baz" to "bar"; also add new BC leaf + "wibble"; (NBC) + + 1.2.1M - backport NBC fix, changing "baz" to "bar" + + 1.2.2M - backport "wibble". This is a BC change but "M" modifier + is sticky. + + 3.1.0 - introduce new leaf "wobble" (BC) + + The partial ordering relationships based on the semantic versioning + numbers can be defined as follows: + + 1.0.0 < 1.1.0 < 1.2.0 < 1.3.0 < 2.0.0 < 3.0.0 < 3.1.0 + + 1.0.0 < 1.1.0 < 1.1.1m < 1.1.2M + + 1.0.0 < 1.1.0 < 1.2.0 < 1.2.1M < 1.2.2M + + There is no ordering relationship between 1.1.1M and either 1.2.0 or + 1.2.1M, except that they share the common ancestor of 1.1.0. + + Looking at the version number alone, the module definition in 2.0.0 + does not necessarily contain the contents of 1.3.0. However, the + module revision history in 2.0.0 would likely indicate that it was + edited from module version 1.3.0. 2.3. YANG Semantic Version Update Rules @@ -437,79 +544,80 @@ Internet-Draft YANG Module Versioning March 2019 The first step is to classify the module change as 'editorial', 'backwards-compatible', or 'non-backwards-compatible version' using - the rules defined in Section 2.1. + the rules defined in Section 2.1 and Section 4. The second step is to calculate the value of the 'semver:version' field for the new module revision, based on the value of the + 'semver:version' field in the base module, any how the module changes + have been classified. + + The following rules define how the value for the 'semver:version' + argument in the new module revision is calculated: -Claise, et al. Expires September 8, 2019 [Page 8] +Claise, et al. Expires September 11, 2019 [Page 10] Internet-Draft YANG Module Versioning March 2019 - 'semver:version' field in the base module, any how the module changes - have been classified. + 1. If a module is being updated in a non-backwards-compatible way, + then the module version "X.Y.Z[m|M]" MUST be updated to "X+1.0.0" + unless that module version has already been defined with + different content, in which case the module version "X.Y.Z+1M + MUST be used instead. - The following rules define how the value for the 'semver:version' - argument in the new module revision is calculated: - - If a module is being updated in a non-backwards-compatible way, - then the module version "X.Y.Z[m|M]" MUST be updated to "X+1.0.0" - unless that module version has already been defined with different - content, in which case the module version "X.Y.Z+1M MUST be used - instead. + 2. If a module is being updated in a backwards-compatible way, then + the next version number depends on the format of the current + version number: - If a module is being updated in a backwards-compatible way, then - the next version number depends on the format of the current - version number: + i "X.Y.Z" - the module version MUST be updated to "X.Y+1.0", + unless that module version has already been defined with + different content, when the module version MUST be updated + to "X.Y.Z+1m instead". - "X.Y.Z" - the module version MUST be updated to "X.Y+1.0", - unless that module version has already been defined with - different content, when the module version MUST be updated to - "X.Y.Z+1m instead". + ii "X.Y.Zm" - the module version MUST be updated to + "X.Y.Z+1m". - "X.Y.Zm" - the module version MUST be updated to "X.Y.Z+1m". + iii "X.Y.ZM" - the module version MUST be updated to + "X.Y.Z+1M". - "X.Y.ZM" - the module version MUST be updated to "X.Y.Z+1M". + 3. If a module is being updated in an editorial way, then the next + version number depends on the format of the current version + number: - If a module is being updated in an editorial way, then the next - version number depends on the format of the current version - number: + i "X.Y.Z" - the module version MUST be updated to "X.Y.Z+1" - "X.Y.Z" - the module version MUST be updated to "X.Y.Z+1" + ii "X.Y.Zm" - the module version MUST be updated to + "X.Y.Z+1m". - "X.Y.Zm" - the module version MUST be updated to "X.Y.Z+1m". + iii "X.Y.ZM" - the module version MUST be updated to + "X.Y.Z+1M". - "X.Y.ZM" - the module version MUST be updated to "X.Y.Z+1M". - - YANG module semantic version numbers beginning with 0, i.e "0.X.Y" - are regarded as beta definitions and need not follow the rules - above. Either the MINOR or PATCH version numbers may be updated, - regardless of whether the changes are non-backwards-compatible, - backwards-compatible, or editorial. + 4. YANG module semantic version numbers beginning with 0, i.e + "0.X.Y" are regarded as beta definitions and need not follow the + rules above. Either the MINOR or PATCH version numbers may be + updated, regardless of whether the changes are non-backwards- + compatible, backwards-compatible, or editorial. 2.4. YANG Module Semver Extension This document defines a YANG extension to add the YANG module semantic version to a Module. The complete definition of this YANG - module is in section XXX. - + module is in Section 9. + extension module-version { + argument semver; + } -Claise, et al. Expires September 8, 2019 [Page 9] +Claise, et al. Expires September 11, 2019 [Page 11] Internet-Draft YANG Module Versioning March 2019 - extension module-version { - argument semver; - } - The extension would typically be used this way: module yang-module-name { @@ -522,46 +630,66 @@ Internet-Draft YANG Module Versioning March 2019 description "to be completed"; + revision 2018-02-28 { + description "Added leaf 'wobble'"; + semver:module-version "3.1.0"; + } + + revision 2017-12-31 { + description "Rename 'baz' to 'bar', added leaf 'wibble'"; + semver:module-version "3.0.0"; + } + revision 2017-10-30 { - description - "Change the module structure"; + description "Change the module structure"; semver:module-version "2.0.0"; } + revision 2017-08-30 { + description "Clarified description of 'foo-64' leaf"; + semver:module-version "1.3.1"; + } + revision 2017-07-30 { - description - "Added new feature XXX"; + description "Added leaf foo-64"; + semver:module-version "1.3.0"; + } + + revision 2017-04-20 { + description "Add new functionality, leaf 'baz'"; semver:module-version "1.2.0"; } revision 2017-04-03 { - description - "Update copyright notice."; - semver:module-version "1.0.1"; + description "Add new functionality, leaf 'foo'"; + semver:module-version "1.1.0"; } revision 2017-04-03 { - description - "First release version."; + + + +Claise, et al. Expires September 11, 2019 [Page 12] + +Internet-Draft YANG Module Versioning March 2019 + + + description "First release version."; semver:module-version "1.0.0"; } + revision 2017-01-30 { + description "NBC changes to initial revision"; + semver:module-version "0.2.0"; + } + revision 2017-01-26 { - description - "Initial module for inet types"; + description "Initial module version"; semver:module-version "0.1.0"; } //YANG module definition starts here - - - -Claise, et al. Expires September 8, 2019 [Page 10] - -Internet-Draft YANG Module Versioning March 2019 - - See also "Semantic Versioning and Structure for IETF Specifications" [I-D.claise-semver] for a mechanism to combine the semantic versioning, the GitHub tools, and a potential change to the IETF @@ -592,11 +720,22 @@ Internet-Draft YANG Module Versioning March 2019 imports if it is augmented by another module. The ietf-semver module defines the 'version' extension, a - substatement to the YANG 'import' statement. An 'import' statement - may contain 'version' statements or a 'revision-date' statement, but - not both. The 'version' statement may be specified multiple times, - requiring that the imported module version conforms to at least one - of the 'version' statements. + substatement to the YANG 'import' statement. + + + + +Claise, et al. Expires September 11, 2019 [Page 13] + +Internet-Draft YANG Module Versioning March 2019 + + + An 'import' statement MAY contain 'version' statements or a + 'revision-date' statement, but not both. + + The 'version' statement MAY be specified multiple times, requiring + that the imported module version conforms to at least one of the + 'version' statements. The argument to the 'version' statement takes one of three valid forms: @@ -611,13 +750,6 @@ Internet-Draft YANG Module Versioning March 2019 "X.Y.Z". The word "MAX" can be used for 'Y' or 'Z' to represent the numerical value 32,767. - - -Claise, et al. Expires September 8, 2019 [Page 11] - -Internet-Draft YANG Module Versioning March 2019 - - The rules for comparing module version numbers are as follows: 1. Version "R.S.T" matches version "A.B.C", only if @@ -640,15 +772,26 @@ Internet-Draft YANG Module Versioning March 2019 R < X - The patch modifier letter is not included as part of module 'version' - argument, and is entirely ignored for import statement module version - number comparisons. + The patch modifier letter is not included as part of the + 'semver:version' argument, and is entirely ignored for import + statement module version number comparisons. + + + + + + +Claise, et al. Expires September 11, 2019 [Page 14] + +Internet-Draft YANG Module Versioning March 2019 + 3.1. Module import examples Consider an example module "example-module" that is hypothetically - available in the following versions: 0.1.0, 1.0.0, 1.1.0, 1.1.1m, - 1.1.2M, 1.1.3M, 1.2.0, 2.0.0, 3.0.0. + available in the following versions: 0.1.0, 0.2.0, 1.0.0, 1.1.0, + 1.1.1m, 1.1.2M, 1.2.0, 1.2.1M, 1.2.2M, 1.3.0, 1.3.1, 2.0.0, 3.0.0, + and 3.1.0. E.g. matching the versions illustrated in Section 2.2.1. The first example selects the specific version 1.1.2M. A specific version import might be used if 1.1.2M contained changes that are @@ -659,36 +802,30 @@ Internet-Draft YANG Module Versioning March 2019 } The next example selects module versions that match, or are greater - than, version 1.1.0. This form may be used if there is a dependency - on a data node introduced in version 1.1.0. This is expected to be + than, version 1.2.0. This form may be used if there is a dependency + on a data node introduced in version 1.2.0. This is expected to be the most commonly used form of 'import by version'. - Includes versions: 1.1.0, 1.1.1m, 1.1.2M, 1.1.3M, 1.2.0, 2.0.0 and - 3.0.0. - - - - -Claise, et al. Expires September 8, 2019 [Page 12] - -Internet-Draft YANG Module Versioning March 2019 - + Includes versions: 1.2.0, 1.2.1M, 1.2.2M, 1.3.0, 1.3.1, 2.0.0, 3.0.0 + and 3.1.0. import example-module { - semver:version 1.1.0+; + semver:version 1.2.0+; } The next example selects module versions that match, or are greater - than 1.1.0, but excluding the 1.1.2M and 1.1.3M versions. This form - may be needed if structural non backwards compatible changes are + than 1.1.0, but excluding all 1.1.x and 1.2.x 'M' versions. This + form may be needed if structural non backwards compatible changes are introduced in a patch 'M' version. Generally, it is advisable to avoid making such changes. - Includes versions: 1.0.0, 1.1.0, 1.1.1m, 1.2.0, 2.0.0 and 3.0.0. + Includes versions: 1.1.0, 1.1.1m, 1.2.0, 1.3.0, 1.3.1, 2.0.0, 3.0.0, + and 3.1.0. import example-module { - semver:version 1.0.0-1.1.1; - semver:version 1.2.0+; + semver:version 1.1.0-1.1.1; + semver:version 1.2.0; + semver:version 1.3.0+; } The last example selects all module versions with a major version @@ -696,71 +833,111 @@ Internet-Draft YANG Module Versioning March 2019 compatible changes have been introduced in version 2.0.0 that break import backwards compatibility. - Includes versions: 1.0.0, 1.1.0, 1.1.1m, 1.1.2M, 1.1.3M, 1.2.0. + + + + +Claise, et al. Expires September 11, 2019 [Page 15] + +Internet-Draft YANG Module Versioning March 2019 + + + Includes versions: 1.0.0, 1.1.0, 1.1.1m, 1.1.2M, 1.2.0, 1.2.1M, + 1.2.2M, 1.3.0 and 1.3.1. import example-module { semver:version 1.0.0-1.MAX.MAX; } -3.2. TODO +4. Classifying changes in YANG modules + + [RFC7950] chapter 11 defines the rules for what constitutes a + backwards compatible change in YANG 1.1. However, the YANG semantic + versioning scheme defined in this document uses a slightly modified + version of this scheme, and also provides rules to classify changes + as editorial, backwards-compatible, or non-backwards-compatible. + +4.1. Editorial changes + + Any changes that do not change the ordering or meaning of the YANG + module in any way are classified as 'editorial'. The following rules + define 'editorial': - TODO - Add text like this to the guidelines. The import statement - SHOULD include a semver:import-versions statement and MUST NOT - include a revision statement. An import statement MUST NOT contain - both a semver:import-versions and a revision substatement. The use - of the revision substatement for import should be discouraged. + o Changing any 'description' statement if it does not change the + semantic meaning of the statement is relates to. E.g., fixing + spelling or grammar, or changing layout, are all allowed. - TODO - Perhaps guidance text should also warn about making nbc - changes that could break imports. E.g. this could be an example of - where making something obsolete might be better than removing it. + o Adding or updating 'reference' statements. -4. Updates to YANG 1.1 Module Update Rules + o Adding or updating the 'organization' statement. - TODO - This section should just specify what the rules are + o Adding a new 'revision' or 'semver:module-version' statement, or + correcting a previous 'revision' or 'semver:module-version' + statement. - RFC 7950 section 11, must be updated to allow for non-backward - changes provided they follow the semantic versioning guidelines and - increase the MAJOR version number when a backward incompatible change - is made. This change is in the spirit of requirement 5.1 from + o A module may be split into a set of submodules or a submodule may + be removed, provided the definitions in the module do not change + except in the ways described above. +4.2. Backwards-compatible changes + [RFC7950] chapter 11 defines the rules for what constitutes a + backwards-compatible change in YANG 1.1. The document update these + rules in the following ways: -Claise, et al. Expires September 8, 2019 [Page 13] + o Adding or changing a 'status' node to 'obsolete' is not a + backwards-compatible change. Other changes/additions of status + elements are backwards-compatible, as per [RFC7950]. + + + + + +Claise, et al. Expires September 11, 2019 [Page 16] Internet-Draft YANG Module Versioning March 2019 - [I-D.verdt-netmod-yang-versioning-reqs]. The following is proposed - text for this change. + o Changing the ordering of statements is allowed if it does not + chanage the ordering of an rpc's 'input' substatements. + +4.3. Non-backwards-compatible changes + + All other changes to YANG modules that are not classified as + 'editorial' or 'backwards-compatible' are defined as being non- + backwards-compatible. + + Examples of non-backwards-compatible changes include: + + o Deleting a data node, or changing it to status obsolete. - "As experience is gained with a module, it may be desirable to revise - that module. Changes to published modules are allowed, even if they - have some potential to cause interoperability problems, if the - module-version YANG extension is used in the revision statement to - clearly indicate the nature of the change." + o Changing the name, type, or units of a data node. - TODO - Specify that changing status to "deprecated" is an BC change, - and changing status to "obsolete" is an NBC change". + o Modifying the description in a way that changes the semantic + meaning of the data node. - A 'backwards-compatible' module semantic version change is where some - syntax or semantic changes exists between the two module revisions, - but all changes follow the rules specified in Section 4 of "Updating - a Module" of [RFC7950], except that no elements have been changed to - status 'obsolete', and re-ordering of statements is allowed. + o Any changes that change or reduce the allowed value set of the + data node, either through changes in the type definition, or the + addition or changes to 'must' statements, or changes in the + description. - Q: Should revision-date history and semantic version be excluded from - the comparison? RW: I've assumed yes. + o Adding or modifying 'when' statements that reduce when the data + node is available in the schema. + + o Making the statement conditional on if-feature. 5. Updates to ietf-yang-library YANG library [RFC7895] [RFC8525] is modified to support semantic versioning in three ways. +5.1. Advertising module version number + The ietf-semver YANG module augments the 'module' list in ietf-yang- library with a 'version' leaf to optionally declare the YANG semantic version of each module. -5.1. Resolving ambiguous module imports +5.2. Resolving ambiguous module imports A YANG datastore schema, defined in [RFC8525], can specify multiple revisions of a YANG module in the schema using the 'import-only' @@ -769,6 +946,14 @@ Internet-Draft YANG Module Versioning March 2019 If a YANG module import statement does not specify a specific version or revision within the datastore schema then it could be ambigous as + + + +Claise, et al. Expires September 11, 2019 [Page 17] + +Internet-Draft YANG Module Versioning March 2019 + + to which module revision the import statement should resolve to. Hence, a datastore schema constructed by a client using the information contained in YANG library may not exactly match the @@ -778,14 +963,6 @@ Internet-Draft YANG Module Versioning March 2019 If a module import statement could resolve to more than one module revision defined in the datastore schema, and one of those revisions - - - -Claise, et al. Expires September 8, 2019 [Page 14] - -Internet-Draft YANG Module Versioning March 2019 - - is implemented (i.e., not an 'import-only' module), then the import statement MUST resolve to the revision of the module that is defined as being implemented by the datastore schema. @@ -794,15 +971,16 @@ Internet-Draft YANG Module Versioning March 2019 revision defined in the datastore schema, and none of those revisions are implemented, but one of more modules revisions specify a YANG semantic version, then the import MUST resolve to the module with the - greatest version number, according to the rules in Section 3. + greatest version number, according to the version comparison rules in + Section 3. If a module import statement could resolve to more than one module revision defined in the datastore schema, none of those revisions are implemented, and none of the modules revisions have a YANG semantic version number, then the import MUST resolve to the module that has - the most recent revision-date. + the most recent revision date. -5.2. Reporting how deprecated and obsolete nodes are handled +5.3. Reporting how deprecated and obsolete nodes are handled The ietf-semver YANG module augments YANG library with two leaves to allow a server to report how it handles status 'deprecated' and @@ -821,10 +999,17 @@ Internet-Draft YANG Module Versioning March 2019 Implementations that implement the YANG semantic versioning scheme defined in this document MUST set the 'deprecated-nodes-implemented' - leaf because the refined module update rules in Section 4 assume that - this is how servers handle 'deprecated' and 'obsolete' nodes to + leaf because the refined module update rules in Section 4 require + that this is how servers handle 'deprecated' and 'obsolete' nodes to comply with YANG module semantic versioning. + + +Claise, et al. Expires September 11, 2019 [Page 18] + +Internet-Draft YANG Module Versioning March 2019 + + If a server does not set the 'deprecated-nodes-implemented' leaf, then clients MUST NOT rely solely on the YANG module semantic version number to determine whether two module versions are backwards @@ -832,16 +1017,6 @@ Internet-Draft YANG Module Versioning March 2019 has changed to 'deprecated' and whether those nodes are implemented by the server. - - - - - -Claise, et al. Expires September 8, 2019 [Page 15] - -Internet-Draft YANG Module Versioning March 2019 - - 6. YANG status description extension The ietf-semver module specifies the YANG extension 'status- @@ -871,10 +1046,10 @@ Internet-Draft YANG Module Versioning March 2019 have an associated YANG semantic version, as compatibility for instance data is undefined. - However, Instance data may reference an associated YANG schema, and + However, instance data may reference an associated YANG schema, and that schema could make use of semantic version numbers, both for the individual YANG modules that comprise the schema, and potentially for - the entire schema itself (e.g. [I-D.rwilton-netmod-yang-packages]). + the entire schema itself (e.g., [I-D.rwilton-netmod-yang-packages]). In this way, the versioning of a schema associated with an instance data set, may allow a client to determine whether the instance data @@ -883,29 +1058,27 @@ Internet-Draft YANG Module Versioning March 2019 One common scenario, where instance data may have to cope with changes to the schema is for the datastore when a server is - restarted with a different YANG schema (e.g. due to a software - upgrade or downgrade). How a server restores the configuration from - during such upgrades or downgrades is outside the scope of - this specification. - - - -Claise, et al. Expires September 8, 2019 [Page 16] +Claise, et al. Expires September 11, 2019 [Page 19] Internet-Draft YANG Module Versioning March 2019 + restarted with a different YANG schema (e.g. due to a software + upgrade or downgrade). How a server restores the configuration from + during such upgrades or downgrades is outside the scope of + this specification. + 8. Guidelines 8.1. Guidelines to YANG model authors - NBC changes to YANG models cause problems to the clients, who are the - consumers of the YANG models, and SHOULD be avoided. However, there - are cases where NBC changes are required, e.g. to fix an incorrect - YANG model. + NBC changes to YANG models may cause problems to clients, who are + consumers of YANG models, and SHOULD be avoided. However, there are + cases where NBC changes are required, e.g. to fix an incorrect YANG + model. YANG model authors are recommended to minimize NBC changes and keep changes BC whenever possible. @@ -917,74 +1090,53 @@ Internet-Draft YANG Module Versioning March 2019 impact on clients and YANG model authors SHOULD try to mitigate that impact. - Updates SHOULD be applied to the latest revision of YANG modules. +8.1.1. Use of YANG semantic versioning -8.1.1. Use of semantic versioning + Module authors should use the following guidance when applying the + module version update rules specified in Section 2.3. - The scheme from semver.org 2.0.0 SHOULD be used if modifications are - always made to the latest revision of the YANG modules. + Updates to modules SHOULD be applied to the latest version of YANG + modules, avoiding the use the 'm|M' patch modifier. When used in + this way, the YANG semantic version numbers are compatible with the + versioning scheme defined by the semver.org 2.0.0 rules. - The YANG semantic versioning scheme SHOULD be used only if it is - needed to do updates to older revisions of the YANG modules. Once a - modifier is added, it is sticky for that "stream". For example if - version 3.4.1M is modified in a BC way, the next version is 3.4.2M. - This is to indicate that 3.4.2M is not BC with 3.4.0, however it - comes at the cost of not being to indicate the type of change between - 3.4.1M and 3.4.2M. + Changes to older versions of published YANG modules SHOULD be + minimized, since there may be a greater impact on clients, and + comparing between version numbers becomes more limited if the 'm|M' + modifiers are used. However, if it necessary to make such changes + then the following guidelines apply: - Reuse of an already used module-version MUST be avoided. For example - for the YANG versioning scheme, when updating 3.4.0 in a NBC manner - the module author must verify whether version 4.0.0 is available for - use and if that version was already used, the updated module must use - the version 3.4.1M. + Any changes SHOULD also be made to a latest version of the YANG + module, if appropriate. - From a published revision N of a module, the next published revision - N+1 of the module SHOULD have one of: + Where possible, changes SHOULD be restricted to backwards- + compatible changes only. - 1. MAJOR version incremented by 1, MINOR and PATCH versions set to - 0. This indicates that in revision N+1: - * There have been one or more non-backwards-compatible changes -Claise, et al. Expires September 8, 2019 [Page 17] +Claise, et al. Expires September 11, 2019 [Page 20] Internet-Draft YANG Module Versioning March 2019 - * There may also be new functionality which have been added in a - backwards-compatible manner - - * There may also be bug fixes which have been made in a - backwards-compatible manner - - 2. MAJOR version unchanged, MINOR version incremented by 1 and PATCH - version set to 0. This indicates that in revision N+1: - - * There are no non-backwards-compatible changes - - * There have been one or more new functionality which have been - added in a backwards compatible-manner - - * There may also be bug fixes which have been made in a - backwards-compatible manner - - 3. MAJOR and MINOR versions unchanged, PATCH version incremented by - 1. This indicates that in revision N+1: - - * There are no non-backwards-compatible changes - - * There is no new functionality which has been added in a - backwards compatible-manner + NBC changes MAY be made, subject to the constraints defined in + Section 2.3. The impact to clients SHOULD be carefully considered + and minimized if possible. - * There are no more bug fixes which have been made in a - backwards-compatible manner + The version numbers associated with a module MUST never be reused. + E.g., when updating module version 3.4.0 in a NBC manner the module + author must verify whether version 4.0.0 is available for use and if + that version was already used, the updated module must use version + 3.4.1M instead. - * There may be editorial changes such a change to a desctiption - statement which does not change the semantics of the data node - in any way. + Patch modifier letters (i.e. 'm' or 'M') are sticky. For example if + version 3.4.1M is modified in a BC way, the next version is 3.4.2M. + This is to indicate that 3.4.2M is not BC with 3.4.0, however it + comes at the cost of not being to indicate the type of change between + 3.4.1M and 3.4.2M. As explained in Appendix A.2.2, while programatically determining a semantic version is possible using tools (e.g. the pyang utility), @@ -999,17 +1151,8 @@ Internet-Draft YANG Module Versioning March 2019 ways in which this can be done: o If the server can support NBC versions of the YANG module - simultaneously AND the clients support version selection, then the - NBC changes MAY be done immediately. The clients would select the - - - - -Claise, et al. Expires September 8, 2019 [Page 18] - -Internet-Draft YANG Module Versioning March 2019 - - + simultaneously using version selection, then the NBC changes MAY + be done immediately. Clients would be required to select the version which they support and the NBC change would have no impact on them. @@ -1028,6 +1171,13 @@ Internet-Draft YANG Module Versioning March 2019 the model but this has the risk of breaking modules which import the modified module. + + +Claise, et al. Expires September 11, 2019 [Page 21] + +Internet-Draft YANG Module Versioning March 2019 + + 2. For A node with status "deprecated" MUST be supported for the solution described here to function properly. @@ -1058,27 +1208,31 @@ Internet-Draft YANG Module Versioning March 2019 The following sections have examples on how non-backwards-compatible changes can be made. +8.1.2.1. Removing a data node + + Removing a leaf or container from the data tree, e.g. because support + for the corresponding feature is being removed: + + 1. The node's status SHOULD be changed to "deprecated" and it MUST + be supported for at least one year. This is a backwards- + compatible change. + + 2. When the node is not available anymore, its status MUST be + changed to "obsolete" and the "status-description" updated, this + is a non-backwards-compatible change. The "status-description" + SHOULD be used to explain why the node is not available anymore. -Claise, et al. Expires September 8, 2019 [Page 19] - -Internet-Draft YANG Module Versioning March 2019 -8.1.2.1. Removing a data node - Removing a leaf or container from the data tree, e.g. because support - for the corresponding feature is being removed: - 1. The node's status SHOULD be changed to "deprecated" and it MUST - be supported for at least one year. This is a backwards- - compatible change. - 2. When the node is not available anymore, its status MUST be - changed to "obsolete" and the "status-description" updated, this - is a non-backwards-compatible change. The "status-description" - SHOULD be used to explain why the node is not available anymore. +Claise, et al. Expires September 11, 2019 [Page 22] + +Internet-Draft YANG Module Versioning March 2019 + 8.1.2.2. Changing the type of a leaf node @@ -1113,15 +1267,6 @@ Internet-Draft YANG Module Versioning March 2019 id". However, if the value can not be mapped, we need a way of returning "unsupported" TBD. - - - - -Claise, et al. Expires September 8, 2019 [Page 20] - -Internet-Draft YANG Module Versioning March 2019 - - 4. When node "vpn-id" is not available anymore, its status MUST be changed to "obsolete" and the "status-description" is updated. This is a non-backwards-compatible change. @@ -1134,17 +1279,31 @@ Internet-Draft YANG Module Versioning March 2019 8.1.2.6. Changing a default value + + + + + + +Claise, et al. Expires September 11, 2019 [Page 23] + +Internet-Draft YANG Module Versioning March 2019 + + 8.2. Guidelines to YANG model clients - Here are some guidelines for YANG model clients: + Guidelines for clients of modules using YANG semantic versioning: o Clients SHOULD be liberal when processing data received from a server. For example, the server may have increased the range of an operational node causing the client to receive a value whch is outside the range of the YANG model revision it was coded against - o Clients SHOULD look for status changes in new revisions of YANG - models they support. + o Clients SHOULD monitor changes to published YANG modules through + their version numbers, and use appropriate tooling to understand + the specific changes between module versions. In particular, + clients SHOULD NOT migrate to NBC versions of a module without + first understanding the specifics of the NBC changes. o Clients SHOULD plan to make changes to match published status changes. When a node's status changes from "current" to @@ -1152,32 +1311,14 @@ Internet-Draft YANG Module Versioning March 2019 timely fashion. When a node's status changes to "obsolete", clients MUST stop using that node. - o A client SHOULD not use unknown NBC versions automatically +9. Semantic Version Extension YANG Modules -9. Semantic Version Extension YANG Module - - The extension and related ietf-yang-library changes described in this - module are defined in the YANG module below. - - TODO - Define a separate type (in a ietf-semver-types.yang) file for - the YANG semver field definition. It would be useful for the YANG - library augmentation, and possibly in the packages definition if that - work progresses. - - TODO - Update the semantic version text to update the main definition - in this document + YANG module with extensions for defining a module's YANG semantic + version number, and importing by version. file "ietf-semver@2019-02-07.yang" module ietf-semver { yang-version 1.1; - - - -Claise, et al. Expires September 8, 2019 [Page 21] - -Internet-Draft YANG Module Versioning March 2019 - - namespace "urn:ietf:params:xml:ns:yang:ietf-semver"; prefix semver; @@ -1197,6 +1338,14 @@ Internet-Draft YANG Module Versioning March 2019 Author: Robert Wilton + + + +Claise, et al. Expires September 11, 2019 [Page 24] + +Internet-Draft YANG Module Versioning March 2019 + + Author: Kevin D'Souza @@ -1226,14 +1375,6 @@ Internet-Draft YANG Module Versioning March 2019 "* Properly import ietf-yang-library. * Fix the name of module-semver => module-version. * Fix regular expression syntax. - - - -Claise, et al. Expires September 8, 2019 [Page 22] - -Internet-Draft YANG Module Versioning March 2019 - - * Augment yang-library with booleans as to whether or not deprecated and obsolete nodes are present. * Add an extension to enable import by semantic version. @@ -1254,6 +1395,13 @@ Internet-Draft YANG Module Versioning March 2019 semver:module-version "0.1.1"; } + + +Claise, et al. Expires September 11, 2019 [Page 25] + +Internet-Draft YANG Module Versioning March 2019 + + typedef version { type string { pattern '[0-9]{1,5}\.[0-9]{1,5}\.[0-9]{1,5}(m|M)?'; @@ -1282,14 +1430,6 @@ Internet-Draft YANG Module Versioning March 2019 version number, depending on what form modifier 'v' takes: * 'M' - the change represents a non-backwards-compatible - - - -Claise, et al. Expires September 8, 2019 [Page 23] - -Internet-Draft YANG Module Versioning March 2019 - - change * 'm' - the change represents a backwards-compatible change @@ -1311,6 +1451,13 @@ Internet-Draft YANG Module Versioning March 2019 The rules for updating the module-version number are described in section XXX of 'YANG Semantic Versioning for Modules'; + + +Claise, et al. Expires September 11, 2019 [Page 26] + +Internet-Draft YANG Module Versioning March 2019 + + By comparing the module-version between two revisions of a given module, one can determine if different revisions are backwards compatible or not, as well as whether or not new @@ -1324,9 +1471,10 @@ Internet-Draft YANG Module Versioning March 2019 statements. Zero or one module-version statement is allowed per parent statement. No substatements are allowed. - 'revision' statements in submodule MAY contain a - 'module-version' statement for documentation purposes, but it - has no effect on the including module's semantic version."; + 'revision' statements in submodules MAY contain a + 'module-version' statement for documentation purposes, but + its meaning is undefined, and has no effect on the including + module's semantic version."; reference "draft-verdt-netmod-yang-semver: YANG Semantic Versioning for Modules"; @@ -1338,14 +1486,6 @@ Internet-Draft YANG Module Versioning March 2019 "This extension specifies an acceptable set of semantic versions of a given module that may be imported. - - - -Claise, et al. Expires September 8, 2019 [Page 24] - -Internet-Draft YANG Module Versioning March 2019 - - The statement MUST only be a substatement of the import statement. @@ -1366,6 +1506,14 @@ Internet-Draft YANG Module Versioning March 2019 (ii) "+ '\d+\.\d+\.\d+\+ '+" Matches exact version or greater, e.g. 3.6.1+ + + + +Claise, et al. Expires September 11, 2019 [Page 27] + +Internet-Draft YANG Module Versioning March 2019 + + (iii) "+' \d+\.\d+.\d+-\d+\.(\d+|MAX).(\d|MAX)+ '+" Matches inclusive range, e.g. 3.6.1-7.8.4, or 3.2.1-3.MAX.MAX"; @@ -1393,15 +1541,10 @@ Internet-Draft YANG Module Versioning March 2019 } - file "ietf-yl-semver@2019-02-07.yang" - - - -Claise, et al. Expires September 8, 2019 [Page 25] - -Internet-Draft YANG Module Versioning March 2019 - + YANG module with augmentations to YANG Library to support semantic + version numbers. + file "ietf-yl-semver@2019-02-07.yang" module ietf-yl-semver { yang-version 1.1; namespace "urn:ietf:params:xml:ns:yang:ietf-yl-semver"; @@ -1419,6 +1562,14 @@ Internet-Draft YANG Module Versioning March 2019 "IETF NETMOD (Network Modeling) Working Group"; contact "WG Web: + + + +Claise, et al. Expires September 11, 2019 [Page 28] + +Internet-Draft YANG Module Versioning March 2019 + + WG List: Author: Benoit Claise @@ -1450,14 +1601,6 @@ Internet-Draft YANG Module Versioning March 2019 revision 2019-02-27 { description - - - -Claise, et al. Expires September 8, 2019 [Page 26] - -Internet-Draft YANG Module Versioning March 2019 - - "Moved YANG library augmentations into a separate module."; reference "draft-verdt-netmod-yang-semver: @@ -1475,6 +1618,14 @@ Internet-Draft YANG Module Versioning March 2019 match the semver:version value in specific revision of the module loaded in this module-set."; reference + + + +Claise, et al. Expires September 11, 2019 [Page 29] + +Internet-Draft YANG Module Versioning March 2019 + + "draft-verdt-netmod-yang-semver: YANG Semantic Versioning"; } } @@ -1506,14 +1657,6 @@ Internet-Draft YANG Module Versioning March 2019 absent then the behaviour is unspecified."; reference "draft-verdt-netmod-yang-semver: Reporting how deprecated and - - - -Claise, et al. Expires September 8, 2019 [Page 27] - -Internet-Draft YANG Module Versioning March 2019 - - obsolete nodes are handled"; } } @@ -1532,6 +1675,13 @@ Internet-Draft YANG Module Versioning March 2019 o Ebben Aries + + +Claise, et al. Expires September 11, 2019 [Page 30] + +Internet-Draft YANG Module Versioning March 2019 + + o Jason Sterne o Joe Clarke @@ -1560,16 +1710,6 @@ Internet-Draft YANG Module Versioning March 2019 The document does not define any new protocol or data model. There are no security impacts. - - - - - -Claise, et al. Expires September 8, 2019 [Page 28] - -Internet-Draft YANG Module Versioning March 2019 - - 12. IANA Considerations 12.1. YANG Module Registrations @@ -1591,6 +1731,13 @@ Internet-Draft YANG Module Versioning March 2019 Name: ietf-yl-semver + + +Claise, et al. Expires September 11, 2019 [Page 31] + +Internet-Draft YANG Module Versioning March 2019 + + XML Namespace: urn:ietf:params:xml:ns:yang:ietf-yl-semver Prefix: yl-semver @@ -1616,20 +1763,13 @@ Internet-Draft YANG Module Versioning March 2019 [RFC8407] Bierman, A., "Guidelines for Authors and Reviewers of Documents Containing YANG Data Models", BCP 216, RFC 8407, - DOI 10.17487/RFC8407, October 2018, . - - - -Claise, et al. Expires September 8, 2019 [Page 29] - -Internet-Draft YANG Module Versioning March 2019 - + DOI 10.17487/RFC8407, October 2018, + . [RFC8525] Bierman, A., Bjorklund, M., Schoenwaelder, J., Watsen, K., and R. Wilton, "YANG Library", RFC 8525, - DOI 10.17487/RFC8525, March 2019, . + DOI 10.17487/RFC8525, March 2019, + . 13.2. Informative References @@ -1643,6 +1783,17 @@ Internet-Draft YANG Module Versioning March 2019 YANG Module Update Procedure", draft-clacla-netmod-yang- model-update-06 (work in progress), July 2018. + + + + + + +Claise, et al. Expires September 11, 2019 [Page 32] + +Internet-Draft YANG Module Versioning March 2019 + + [I-D.claise-semver] Claise, B., Barnes, R., and J. Clarke, "Semantic Versioning and Structure for IETF Specifications", draft- @@ -1671,30 +1822,89 @@ Internet-Draft YANG Module Versioning March 2019 [yangcatalog] "YANG Catalog", . -Appendix A. Appendix +13.3. URIs + + [1] https://github.com/netmod-wg/yang-ver-dt/issues/14 + [2] https://github.com/netmod-wg/yang-ver-dt/issues/11 + [3] https://github.com/netmod-wg/yang-ver-dt/issues/13 + [4] https://github.com/netmod-wg/yang-ver-dt/issues/12 + [5] https://github.com/netmod-wg/yang-ver-dt/issues/10 -Claise, et al. Expires September 8, 2019 [Page 30] + [6] https://github.com/netmod-wg/yang-ver-dt/issues/9 + + [7] https://github.com/netmod-wg/yang-ver-dt/issues/8 + + [8] https://github.com/netmod-wg/yang-ver-dt/issues/7 + + [9] https://github.com/netmod-wg/yang-ver-dt/issues/6 + + + + +Claise, et al. Expires September 11, 2019 [Page 33] Internet-Draft YANG Module Versioning March 2019 + [10] https://github.com/netmod-wg/yang-ver-dt/issues/5 + + [11] https://github.com/netmod-wg/yang-ver-dt/issues/4 + + [12] https://github.com/netmod-wg/yang-ver-dt/issues/15 + + [13] https://github.com/netmod-wg/yang-ver-dt/issues/2 + +Appendix A. Appendix + A.1. Open Issues - o Do we need a new version of YANG? - While eventually this will fold into a new version, the belief is - this solution can work with extensions alone with an update to the - [RFC7950] text concerning module updates. + Open issues are being tracked at . Currently open issues are: + + o Do we need a new version of YANG? #14 [1] + + o Add guidance text about warning NBC changes might break imports + #11 [2] + + o Add a naming convention for versioned YANG file#13 [3] + + o Define editorial, bc, nbc impact of adding, changing, removing + extension stmts#12 [4] + + o How to version modules in IETF drafts (after they have been + published at 1.0.0 or later#10 [5] + + o The solution does not strictly support semver 2.0.0#9 [6] + + o Are whitespace changes allow between two module instances with the + same version (or revision)?#8 [7] + + o Do we assume that a module has an implicit semver if none as been + specified?#7 [8] + + o Is changing the ordering of nodes an NBC change?#6 [9] + + o Should version statement be at top level or under revision + statement?#5 [10] + + o Figure out whether changing the imports constitute a BC or NBC + change#4 [11] + + o Does BC or NBC depend on whether the node is config true/false?#15 + [12] + + o Status obsolete nodes#2 [13] + + + +Claise, et al. Expires September 11, 2019 [Page 34] + +Internet-Draft YANG Module Versioning March 2019 - o We could consider a new naming convention for module files. - Today, module files are named using a module@revision.yang - notation. We could consider module%semver.yang or - module#version.yang variants. Re-using the '@' for version is not - ideal, so another separator character should be used. In this - manner, both version and revision could be used. A.2. Derived Semantic Version @@ -1729,15 +1939,6 @@ A.2.2. Implementation Experience o the derived-semantic-version leaf is established by examining the the YANG module themselves. As such derived-semantic-version only - - - - -Claise, et al. Expires September 8, 2019 [Page 31] - -Internet-Draft YANG Module Versioning March 2019 - - takes syntax into account as opposed to the meaning of various elements when it computes the semantic version. @@ -1754,6 +1955,13 @@ Internet-Draft YANG Module Versioning March 2019 versions assume non-backward compatible changes were done., thus bump its derived semantic MAJOR version. + + +Claise, et al. Expires September 11, 2019 [Page 35] + +Internet-Draft YANG Module Versioning March 2019 + + 3. Else, run "pyang --check-update-from" on module A, revision N and revision N+1 to see if backward-incompatible changes exist. @@ -1783,17 +1991,6 @@ Internet-Draft YANG Module Versioning March 2019 Authors' Addresses - - - - - - -Claise, et al. Expires September 8, 2019 [Page 32] - -Internet-Draft YANG Module Versioning March 2019 - - Benoit Claise Cisco Systems, Inc. De Kleetlaan 6a b1 @@ -1814,6 +2011,13 @@ Internet-Draft YANG Module Versioning March 2019 Email: jclarke@cisco.com + + +Claise, et al. Expires September 11, 2019 [Page 36] + +Internet-Draft YANG Module Versioning March 2019 + + Reshad Rahman Cisco Systems, Inc. @@ -1842,14 +2046,6 @@ Internet-Draft YANG Module Versioning March 2019 Email: jason.sterne@nokia.com - - - -Claise, et al. Expires September 8, 2019 [Page 33] - -Internet-Draft YANG Module Versioning March 2019 - - Kevin D'Souza AT&T 200 S. Laurel Ave @@ -1873,32 +2069,4 @@ Internet-Draft YANG Module Versioning March 2019 - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Claise, et al. Expires September 8, 2019 [Page 34] +Claise, et al. Expires September 11, 2019 [Page 37] diff --git a/yang-semver/draft-verdt-netmod-yang-semver.xml b/yang-semver/draft-verdt-netmod-yang-semver.xml index 0ff171f..75a72c5 100755 --- a/yang-semver/draft-verdt-netmod-yang-semver.xml +++ b/yang-semver/draft-verdt-netmod-yang-semver.xml @@ -132,7 +132,7 @@ version numbers to help manage the lifecycle of YANG modules. - The solution is comprised of the following six parts: + The solution is comprised of the following seven parts: A definition for the YANG semantic versioning scheme for modules, and an explanation of how the semver extension can be @@ -143,8 +143,7 @@ inter-module version dependencies to be captured within YANG module definitions. Updates to the YANG 1.1 module update rules to accommodate the - semantic versioning scheme and to provide more consistent - handling of changes to the YANG "status" statement. + semantic versioning scheme. Updates and augmentations to ietf-yang-library to include the YANG semantic version number in the module descriptions, to report how 'deprecated' and 'obsolete' nodes are handled by a @@ -154,24 +153,26 @@ 'status' statement to allow additional documentation as to why a node is being deprecated, and what alternatives may be available. + A description of how YANG semantic versioning applies to YANG + instance data. Guidelines to YANG module authors on how the YANG semantic - versioning rules should be used, along with examples. + versioning rules should be used, along with examples. - Open issues are listed at , and also - tracked at https://github.com/netmod-wg/yang-ver-dt/issues + Open issues are listed at , and + tracked at . -
-
+
+
This document proposes updates to to address some of the requirements. It should be noted that there is also active WG discussion on the next steps towards an updated version of YANG, and potentially some of the functionality described here could be folded into an updated revision of , although that it might adversely impact when + target="RFC7950"/>, although that might adversely impact when (parts of) a standards based YANG module versioning solution is - available for use. + available. The sections listed below provide updates to . The design team does not believe any of the @@ -191,14 +192,14 @@
-
+
This document updates . defines how a reader of a YANG library datastore schema chooses which version of an import-only module is used to resolve a module import when the definition is otherwise ambiguous.
-
+
updates to provide guidelines on how the YANG module semantic versioning can be used to manage the lifecycle of YANG modules when using strict RFC @@ -255,9 +256,9 @@ YANG submodules are not independently versioned by the YANG semantic versioning scheme. Instead, if a versioned module includes one or more submodules then those submodules are implicitly versioned as part - of the module's 'semver:version' statements, and all 'include' - statements MUST specify the revision-date for each of the included - submodules. + of the module's 'semver:version' statements, and all the module's + 'include' statements MUST specify the revision-date for each of the + included submodules.
@@ -269,8 +270,9 @@ The semantic version change between any two arbitrary revisions of a YANG module can be classified into one of four categories: 'unchanged', 'editorial, 'backwards-compatible' or - 'non-backwards-compatible'. The classification is performed by - use of the following rules: + 'non-backwards-compatible'. A summary of the classification is + given below, with the specific rules as they apply to YANG + statements provided in . The semantic version change between two module revisions is defined as 'unchanged' if, after excluding 'revision' and @@ -278,21 +280,21 @@ remaining changes are insignificant white space changes. An 'editorial' module semantic version change is where there - are changes in the module's statements, or statement ordering, - between the two module revisions, but those changes do not affect - the syntax or semantic meaning of the module in any way. An - example of an editorial change would be a fix to a spelling - mistake in a description statement. + are changes in the module's statements, between the two module + revisions, but those changes do not affect the syntax or semantic + meaning of the module in any way. An example of an editorial + change would be a fix to a spelling mistake in a description + statement. A 'backwards-compatible' module semantic version change is where some syntax or semantic changes exists between the two module revisions, but all changes follow the rules specified in - . + . A 'non-backwards-compatible' module semantic version change is where some syntax or semantic changes exists between the two - module revisions, and those changes do not follow the rules - specified in . + module revisions, and those changes do not follow the rules for a + 'backwards-compatible' version change.
@@ -312,7 +314,7 @@ semantic versioning scheme supports limited updates to older versions of YANG modules, to allow for bug fixes and enhancements to module versions that are not the latest. - + Module definitions that follow the semver.org 2.0.0 versioning scheme are fully compatible with implementations that understand the YANG semantic versioning scheme. @@ -323,7 +325,7 @@ by the semver.org 2.0.0 versioning scheme. - Every YANG module versioned using a YANG semantic versioning + Every YANG module versioned using the YANG semantic versioning scheme specifies the module's semantic version number by including the 'semver:module-version' statement according to the following rules: @@ -354,9 +356,8 @@ 'Y' is the MINOR version. Changes in the minor version number indicate changes that are backwards-compatible to versions with - the same major version number, but a lower minor version number, - unless either version has a patch version with an 'm' or 'M' - modifier. + the same major version number, but a lower minor version number + and no patch 'm' or 'M' modifier. 'Zv' is the PATCH version and modifier. Changes in the patch version number can indicate editorial, backwards-compatible, or @@ -372,17 +373,74 @@ - YANG requires that if two modules have the same revision date - then they MUST have the same semantic content. A similar constraint - applies for YANG semantic version numbers, i.e. two revisions of a - module that have the same semantic version numbers MUST have the - same semantic content. - A module MUST NOT have multiple revision where the version string - has the same MAJOR, MINOR and PATCH version numbers, but different - PATCH modifier letter. E.g., module version "1.2.3M" is not allowed - if module version "1.2.3" has already been defined. Neither can - there be two different revisions of a YANG module with different - content but the same + The YANG module name and YANG semantic version number uniquely + identifies a revision of a module, with an associated revision date. + There MUST NOT be multiple instances of a YANG module definition + with the same module name and YANG semantic version number but + different content or revision date. + There MUST NOT be multiple versions of a YANG module that have + the same MAJOR, MINOR and PATCH version numbers, but different patch + modifier letter. E.g., module version "1.2.3M" MUST NOT be defined + if module version "1.2.3" has already been defined. +
+ The following diagram and explanation illustrates how YANG semantic version numbers work. +
+ Example YANG semantic version numbers for an example module: + + 0.1.0 + | + 0.2.0 + | + 1.0.0 + | \ + | 1.1.0 -> 1.1.1m -> 1.1.2M + | | + | 1.2.0 -> 1.2.1M -> 1.2.2M + | | + | 1.3.0 -> 1.3.1 + | + 2.0.0 + | + 3.0.0 + \ + 3.1.0 + +
+ The tree diagram above illustrates how an example modules version + history might evolve. For example, the tree might represent the + following changes, listed in chronological order from oldest + revision to newest: + + 0.1.0 - first beta module version + 0.2.0 - second beta module version (with NBC changes) + 1.0.0 - first release (may have NBC changes from 0.2.0) + 1.1.0 - added new functionality, leaf "foo" (BC) + 1.2.0 - added new functionality, leaf "baz" (BC) + 1.3.0 - improve existing functionality, added leaf "foo-64" (BC) + 1.3.1 - improve description wording for "foo-64" (Editorial) + 1.1.1m - backport "foo-64" leaf to 1.1.x to avoid implementing "baz" from 1.2.0 (BC) + 2.0.0 - change existing model for performance reasons, e.g. re-key list (NBC) + 1.1.2M - NBC point bug fix, not required in 2.0.0 due to model changes (NBC) + 3.0.0 - NBC bugfix, rename "baz" to "bar"; also add new BC leaf "wibble"; (NBC) + 1.2.1M - backport NBC fix, changing "baz" to "bar" + 1.2.2M - backport "wibble". This is a BC change but "M" modifier is sticky. + 3.1.0 - introduce new leaf "wobble" (BC) + + + The partial ordering relationships based on the semantic versioning numbers can be defined as follows: + + 1.0.0 < 1.1.0 < 1.2.0 < 1.3.0 < 2.0.0 < 3.0.0 < 3.1.0 + 1.0.0 < 1.1.0 < 1.1.1m < 1.1.2M + 1.0.0 < 1.1.0 < 1.2.0 < 1.2.1M < 1.2.2M + + + There is no ordering relationship between 1.1.1M and either 1.2.0 or + 1.2.1M, except that they share the common ancestor of 1.1.0. + Looking at the version number alone, the module definition in + 2.0.0 does not necessarily contain the contents of 1.3.0. However, + the module revision history in 2.0.0 would likely indicate that it + was edited from module version 1.3.0. +
@@ -395,7 +453,8 @@ The first step is to classify the module change as 'editorial', 'backwards-compatible', or 'non-backwards-compatible version' using - the rules defined in . + the rules defined in and + . The second step is to calculate the value of the 'semver:version' field for the new module revision, based on the value of the @@ -404,7 +463,7 @@ The following rules define how the value for the 'semver:version' argument in the new module revision is calculated: - + If a module is being updated in a non-backwards-compatible way, then the module version "X.Y.Z[m|M]" MUST be updated to "X+1.0.0" unless that module version has already been defined with @@ -414,7 +473,7 @@ If a module is being updated in a backwards-compatible way, then the next version number depends on the format of the current version number: - + "X.Y.Z" - the module version MUST be updated to "X.Y+1.0", unless that module version has already been defined with different content, when the module version MUST be updated to @@ -429,7 +488,7 @@ If a module is being updated in an editorial way, then the next version number depends on the format of the current version number: - + "X.Y.Z" - the module version MUST be updated to "X.Y.Z+1" "X.Y.Zm" - the module version MUST be updated to "X.Y.Z+1m". @@ -449,21 +508,20 @@
This document defines a YANG extension to add the YANG module semantic version to a Module. The complete definition of this YANG - module is in section XXX. + module is in .
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 { namespace "name-space"; @@ -474,43 +532,63 @@ description "to be completed"; + revision 2018-02-28 { + description "Added leaf 'wobble'"; + semver:module-version "3.1.0"; + } + + revision 2017-12-31 { + description "Rename 'baz' to 'bar', added leaf 'wibble'"; + semver:module-version "3.0.0"; + } + revision 2017-10-30 { - description - "Change the module structure"; + description "Change the module structure"; semver:module-version "2.0.0"; } + revision 2017-08-30 { + description "Clarified description of 'foo-64' leaf"; + semver:module-version "1.3.1"; + } + revision 2017-07-30 { - description - "Added new feature XXX"; + description "Added leaf foo-64"; + semver:module-version "1.3.0"; + } + + revision 2017-04-20 { + description "Add new functionality, leaf 'baz'"; semver:module-version "1.2.0"; } revision 2017-04-03 { - description - "Update copyright notice."; - semver:module-version "1.0.1"; + description "Add new functionality, leaf 'foo'"; + semver:module-version "1.1.0"; } revision 2017-04-03 { - description - "First release version."; + description "First release version."; semver:module-version "1.0.0"; } + revision 2017-01-30 { + description "NBC changes to initial revision"; + semver:module-version "0.2.0"; + } + revision 2017-01-26 { - description - "Initial module for inet types"; + description "Initial module version"; semver:module-version "0.1.0"; } //YANG module definition starts here - +
- - - See also "Semantic Versioning and Structure for IETF Specifications" for a mechanism - to combine the semantic versioning, the GitHub tools, and a potential change to the IETF process. + See also "Semantic Versioning and Structure for IETF + Specifications" for a mechanism to + combine the semantic versioning, the GitHub tools, and a potential + change to the IETF process.
@@ -539,11 +617,15 @@ imports if it is augmented by another module. The ietf-semver module defines the 'version' extension, a - substatement to the YANG 'import' statement. An 'import' statement - may contain 'version' statements or a 'revision-date' statement, but - not both. The 'version' statement may be specified multiple times, - requiring that the imported module version conforms to at least one of - the 'version' statements. + substatement to the YANG 'import' statement. + + An 'import' statement MAY contain 'version' statements or a + 'revision-date' statement, but not both. + The 'version' statement MAY be specified multiple times, + requiring that the imported module version conforms to at least one + of the 'version' statements. + + The argument to the 'version' statement takes one of three valid forms: @@ -579,14 +661,16 @@ - The patch modifier letter is not included as part of module 'version' - argument, and is entirely ignored for import statement module version - number comparisons. + The patch modifier letter is not included as part of the + 'semver:version' argument, and is entirely ignored for import + statement module version number comparisons.
Consider an example module "example-module" that is - hypothetically available in the following versions: 0.1.0, 1.0.0, - 1.1.0, 1.1.1m, 1.1.2M, 1.1.3M, 1.2.0, 2.0.0, 3.0.0. + hypothetically available in the following versions: 0.1.0, 0.2.0, + 1.0.0, 1.1.0, 1.1.1m, 1.1.2M, 1.2.0, 1.2.1M, 1.2.2M, 1.3.0, 1.3.1, + 2.0.0, 3.0.0, and 3.1.0. E.g. matching the versions illustrated + in . The first example selects the specific version 1.1.2M. A specific version import might be used if 1.1.2M contained changes @@ -600,31 +684,32 @@ import example-module { The next example selects module versions that match, or are - greater than, version 1.1.0. This form may be used if there is a - dependency on a data node introduced in version 1.1.0. This is + greater than, version 1.2.0. This form may be used if there is a + dependency on a data node introduced in version 1.2.0. This is expected to be the most commonly used form of 'import by version'. - Includes versions: 1.1.0, 1.1.1m, 1.1.2M, 1.1.3M, - 1.2.0, 2.0.0 and 3.0.0. + Includes versions: 1.2.0, 1.2.1M, 1.2.2M, 1.3.0, 1.3.1, 2.0.0, + 3.0.0 and 3.1.0.
import example-module { - semver:version 1.1.0+; + semver:version 1.2.0+; }
The next example selects module versions that match, or are - greater than 1.1.0, but excluding the 1.1.2M and 1.1.3M versions. - This form may be needed if structural non backwards compatible - changes are introduced in a patch 'M' version. Generally, it is - advisable to avoid making such changes. - Includes versions: 1.0.0, 1.1.0, 1.1.1m, 1.2.0, 2.0.0 and - 3.0.0. + greater than 1.1.0, but excluding all 1.1.x and 1.2.x 'M' + versions. This form may be needed if structural non backwards + compatible changes are introduced in a patch 'M' version. + Generally, it is advisable to avoid making such changes. + Includes versions: 1.1.0, 1.1.1m, 1.2.0, 1.3.0, 1.3.1, 2.0.0, + 3.0.0, and 3.1.0.
import example-module { - semver:version 1.0.0-1.1.1; - semver:version 1.2.0+; + semver:version 1.1.0-1.1.1; + semver:version 1.2.0; + semver:version 1.3.0+; }
@@ -633,8 +718,8 @@ import example-module { version number of 1. This form may be useful if significant non backwards compatible changes have been introduced in version 2.0.0 that break import backwards compatibility. - Includes versions: 1.0.0, 1.1.0, 1.1.1m, 1.1.2M, 1.1.3M, - 1.2.0. + Includes versions: 1.0.0, 1.1.0, 1.1.1m, 1.1.2M, 1.2.0, 1.2.1M, + 1.2.2M, 1.3.0 and 1.3.1.
import example-module { @@ -643,56 +728,76 @@ import example-module {
-
- - TODO - Add text like this to the guidelines. The import - statement SHOULD include a semver:import-versions statement and - MUST NOT include a revision statement. An import statement MUST - NOT contain both a semver:import-versions and a revision - substatement. The use of the revision substatement for import - should be discouraged. - - TODO - Perhaps guidance text should also warn about making nbc - changes that could break imports. E.g. this could be an example of - where making something obsolete might be better than removing - it. -
-
-TODO - This section should just specify what the rules are - - RFC 7950 section 11, must be updated to allow for non-backward changes provided they follow the - semantic versioning guidelines and increase the MAJOR version number when a backward incompatible - change is made. This change is in the spirit of requirement 5.1 from . - The following is proposed text for this change. - - - "As experience is gained with a module, it may be desirable to revise that module. - Changes to published modules are allowed, even if they have some potential to cause interoperability - problems, if the module-version YANG extension is used in the revision statement to clearly indicate the nature of the change." - - TODO - Specify that changing status to "deprecated" is an BC change, and changing status to "obsolete" is an NBC change". - A 'backwards-compatible' module semantic version change is - where some syntax or semantic changes exists between the two - module revisions, but all changes follow the rules specified in - of "Updating a - Module" of [RFC7950], except that no elements have been changed to - status 'obsolete', and re-ordering of statements is allowed. - - Q: Should revision-date history and semantic version be excluded - from the comparison? RW: I've assumed yes. - +
+ chapter 11 defines the rules for what + constitutes a backwards compatible change in YANG 1.1. However, the + YANG semantic versioning scheme defined in this document uses a + slightly modified version of this scheme, and also provides rules to + classify changes as editorial, backwards-compatible, or + non-backwards-compatible. +
+ Any changes that do not change the ordering or meaning of the + YANG module in any way are classified as 'editorial'. The following + rules define 'editorial': + + Changing any 'description' statement if it does not change the + semantic meaning of the statement is relates to. E.g., fixing + spelling or grammar, or changing layout, are all allowed. + Adding or updating 'reference' statements. + Adding or updating the 'organization' statement. + Adding a new 'revision' or 'semver:module-version' + statement, or correcting a previous 'revision' or + 'semver:module-version' statement. + A module may be split into a set of submodules or a submodule + may be removed, provided the definitions in the module do not + change except in the ways described above. +
+
+ chapter 11 defines the rules for what + constitutes a backwards-compatible change in YANG 1.1. The document + update these rules in the following ways: + + Adding or changing a 'status' node to 'obsolete' is not a + backwards-compatible change. Other changes/additions of status + elements are backwards-compatible, as per . + Changing the ordering of statements is allowed if it does not + chanage the ordering of an rpc's 'input' substatements. + +
+
+ All other changes to YANG modules that are not classified as + 'editorial' or 'backwards-compatible' are defined as being + non-backwards-compatible. + Examples of non-backwards-compatible changes include: + + Deleting a data node, or changing it to status obsolete. + Changing the name, type, or units of a data node. + Modifying the description in a way that changes the semantic + meaning of the data node. + Any changes that change or reduce the allowed value set of the + data node, either through changes in the type definition, or the + addition or changes to 'must' statements, or changes in the + description. + Adding or modifying 'when' statements that reduce when the data + node is available in the schema. + Making the statement conditional on if-feature. + +
+
-
+
YANG library is modified to support semantic versioning in three ways. +
The ietf-semver YANG module augments the 'module' list in ietf-yang-library with a 'version' leaf to optionally declare the YANG semantic version of each module. - +
A YANG datastore schema, defined in , can specify multiple @@ -716,12 +821,12 @@ import example-module { revisions are implemented, but one of more modules revisions specify a YANG semantic version, then the import MUST resolve to the module with the greatest version number, according to the - rules in . + version comparison rules in . If a module import statement could resolve to more than one module revision defined in the datastore schema, none of those revisions are implemented, and none of the modules revisions have a YANG semantic version number, then the import MUST resolve to - the module that has the most recent revision-date. + the module that has the most recent revision date.
The ietf-semver YANG module augments YANG library with two @@ -743,7 +848,7 @@ import example-module { Implementations that implement the YANG semantic versioning scheme defined in this document MUST set the 'deprecated-nodes-implemented' leaf because the refined module - update rules in assume that this is + update rules in require that this is how servers handle 'deprecated' and 'obsolete' nodes to comply with YANG module semantic versioning. If a server does not set the 'deprecated-nodes-implemented' @@ -789,10 +894,10 @@ target="I-D.ietf-netmod-yang-instance-file-format"/> do not have an associated YANG semantic version, as compatibility for instance data is undefined. -However, Instance data may reference an associated YANG schema, and +However, instance data may reference an associated YANG schema, and that schema could make use of semantic version numbers, both for the individual YANG modules that comprise the schema, and potentially for -the entire schema itself (e.g. ). In this way, the versioning of a schema associated with an instance @@ -810,48 +915,35 @@ of this specification.
- NBC changes to YANG models cause problems to the clients, who are the consumers of the YANG models, and SHOULD be - avoided. However, there are cases where NBC changes are required, e.g. to fix an incorrect YANG model. + NBC changes to YANG models may cause problems to clients, who are consumers of YANG models, and SHOULD be + avoided. However, there are cases where NBC changes are required, e.g. to fix an incorrect YANG model. YANG model authors are recommended to minimize NBC changes and keep changes BC whenever possible. The use of status "deprecated" with the status-description statement allows clients to plan a migration to alternative data nodes. When NBC changes are introduced, consideration should be given to the impact on clients and YANG model authors SHOULD try to mitigate that impact. - Updates SHOULD be applied to the latest revision of YANG modules. -
- The scheme from semver.org 2.0.0 SHOULD be used if modifications are always made to the latest revision of the YANG - modules. - The YANG semantic versioning scheme SHOULD be used only if it is needed to do updates to older revisions of the YANG - modules. Once a modifier is added, it is sticky for that "stream". For example if version 3.4.1M is modified in a BC way, the next +
+ Module authors should use the following guidance when applying the module version update rules specified in . + Updates to modules SHOULD be applied to the latest version of + YANG modules, avoiding the use the 'm|M' patch modifier. When + used in this way, the YANG semantic version numbers are + compatible with the versioning scheme defined by the semver.org + 2.0.0 rules. + Changes to older versions of published YANG modules SHOULD be + minimized, since there may be a greater impact on clients, and + comparing between version numbers becomes more limited if the + 'm|M' modifiers are used. However, if it necessary to make such + changes then the following guidelines apply: + + Any changes SHOULD also be made to a latest version of the YANG module, if appropriate. + Where possible, changes SHOULD be restricted to backwards-compatible changes only. + NBC changes MAY be made, subject to the constraints defined in . The impact to clients SHOULD be carefully considered and minimized if possible. + + + The version numbers associated with a module MUST never be reused. E.g., when updating module version 3.4.0 in a NBC manner the module author must verify whether version 4.0.0 is available for use and if that version was already used, the updated module must use version 3.4.1M instead. + Patch modifier letters (i.e. 'm' or 'M') are sticky. For example if version 3.4.1M is modified in a BC way, the next version is 3.4.2M. This is to indicate that 3.4.2M is not BC with 3.4.0, however it comes at the cost of not being to indicate the type of change between 3.4.1M and 3.4.2M. - Reuse of an already used module-version MUST be avoided. For example for the YANG versioning scheme, when updating 3.4.0 in a NBC manner the module author must verify whether version 4.0.0 is available for use and if that version was already used, the updated module must use the version 3.4.1M. - From a published revision N of a module, the next published revision N+1 of the module SHOULD - have one of: - - MAJOR version incremented by 1, MINOR and PATCH versions set to 0. This indicates that in revision N+1: - - There have been one or more non-backwards-compatible changes - There may also be new functionality which have been added in a backwards-compatible manner - There may also be bug fixes which have been made in a backwards-compatible manner - - MAJOR version unchanged, MINOR version incremented by 1 and PATCH version set to 0. This indicates that - in revision N+1: - - There are no non-backwards-compatible changes - There have been one or more new functionality which have been added in a backwards compatible-manner - There may also be bug fixes which have been made in a backwards-compatible manner - - MAJOR and MINOR versions unchanged, PATCH version incremented by 1. This indicates that in revision N+1: - - There are no non-backwards-compatible changes - There is no new functionality which has been added in a backwards compatible-manner - There are no more bug fixes which have been made in a backwards-compatible manner - There may be editorial changes such a change to a desctiption statement which does not change the semantics - of the data node in any way. - - - As explained in , while programatically determining a semantic version is possible using tools (e.g. the pyang utility), human overisght is highly recommended because of some special cases which can not be detected by tools. Therefore, a model author SHOULD use both means to determine a model's semantic version. @@ -859,7 +951,7 @@ of this specification.
There are various valid situations where a YANG module has to be modified in a non-backwards-compatible way. Here are the different ways in which this can be done: - If the server can support NBC versions of the YANG module simultaneously AND the clients support version selection, then the NBC changes MAY be done immediately. The clients would select the version which they support and the NBC change would have no impact on them. + If the server can support NBC versions of the YANG module simultaneously using version selection, then the NBC changes MAY be done immediately. Clients would be required to select the version which they support and the NBC change would have no impact on them. When possible, NBC changes are done incrementally to provide clients time to adapt to NBC changes. @@ -916,29 +1008,21 @@ of this specification.
- Here are some guidelines for YANG model clients: + Guidelines for clients of modules using YANG semantic versioning: Clients SHOULD be liberal when processing data received from a server. For example, the server may have increased the range of an operational node causing the client to receive a value whch is outside the range of the YANG model revision it was coded against - Clients SHOULD look for status changes in new revisions of YANG models they support. + Clients SHOULD monitor changes to published YANG modules through their version numbers, and use appropriate tooling to understand the specific changes between module versions. In particular, clients SHOULD NOT migrate to NBC versions of a module without first understanding the specifics of the NBC changes. Clients SHOULD plan to make changes to match published status changes. When a node's status changes from "current" to "deprecated", clients SHOULD plan to stop using that node in a timely fashion. When a node's status changes to "obsolete", clients MUST stop using that node. - A client SHOULD not use unknown NBC versions automatically
-
- - The extension and related ietf-yang-library changes described in this module are - defined in the YANG module below. - - TODO - Define a separate type (in a ietf-semver-types.yang) file - for the YANG semver field definition. It would be useful for the YANG - library augmentation, and possibly in the packages definition if that - work progresses. - TODO - Update the semantic version text to update the main definition in this document +
+ YANG module with extensions for defining a module's + YANG semantic version number, and importing by version. file "ietf-semver@2019-02-07.yang" module ietf-semver { @@ -1073,9 +1157,10 @@ module ietf-semver { statements. Zero or one module-version statement is allowed per parent statement. No substatements are allowed. - 'revision' statements in submodule MAY contain a - 'module-version' statement for documentation purposes, but it - has no effect on the including module's semantic version."; + 'revision' statements in submodules MAY contain a + 'module-version' statement for documentation purposes, but + its meaning is undefined, and has no effect on the including + module's semantic version."; reference "draft-verdt-netmod-yang-semver: YANG Semantic Versioning for Modules"; @@ -1135,7 +1220,9 @@ module ietf-semver { ]]>
-
+
+ YANG module with augmentations to YANG Library to support + semantic version numbers. file "ietf-yl-semver@2019-02-07.yang" module ietf-yl-semver { @@ -1342,19 +1429,22 @@ module ietf-yl-semver {
- + Open issues are being tracked at . Currently open issues are: + - Do we need a new version of YANG? - - While eventually this will fold into a new version, the belief is this solution can - work with extensions alone with an update to the text concerning - module updates. - We could consider a new naming convention for module files. Today, module files - are named using a module@revision.yang notation. We could consider module%semver.yang - or module#version.yang variants. - Re-using the '@' for version is not ideal, so another separator character should be used. - In this manner, both version and revision could be used. - + Do we need a new version of YANG? #14 + Add guidance text about warning NBC changes might break imports #11 + Add a naming convention for versioned YANG file#13 + Define editorial, bc, nbc impact of adding, changing, removing extension stmts#12 + How to version modules in IETF drafts (after they have been published at 1.0.0 or later#10 + The solution does not strictly support semver 2.0.0#9 + Are whitespace changes allow between two module instances with the same version (or revision)?#8 + Do we assume that a module has an implicit semver if none as been specified?#7 + Is changing the ordering of nodes an NBC change?#6 + Should version statement be at top level or under revision statement?#5 + Figure out whether changing the imports constitute a BC or NBC change#4 + Does BC or NBC depend on whether the node is config true/false?#15 + Status obsolete nodes#2
diff --git a/yang-semver/ietf-semver.yang b/yang-semver/ietf-semver.yang index 6efd5e8..4842004 100644 --- a/yang-semver/ietf-semver.yang +++ b/yang-semver/ietf-semver.yang @@ -130,9 +130,10 @@ module ietf-semver { statements. Zero or one module-version statement is allowed per parent statement. No substatements are allowed. - 'revision' statements in submodule MAY contain a - 'module-version' statement for documentation purposes, but it - has no effect on the including module's semantic version."; + 'revision' statements in submodules MAY contain a + 'module-version' statement for documentation purposes, but + its meaning is undefined, and has no effect on the including + module's semantic version."; reference "draft-verdt-netmod-yang-semver: YANG Semantic Versioning for Modules";