idnits 2.17.1 draft-verdt-netmod-yang-semver-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 249: '...lude' statements MUST specify the revi...' RFC 2119 keyword, line 318: '... The module MUST include at least...' RFC 2119 keyword, line 320: '...dule revision statement MUST include a...' RFC 2119 keyword, line 324: '...vision statement SHOULD also include a...' RFC 2119 keyword, line 328: '...ision statements MAY include a 'semver...' (73 more instances...) -- The abstract seems to indicate that this document updates RFC8407, but the header doesn't have an 'Updates:' line to match this. -- The abstract seems to indicate that this document updates RFC8525, but the header doesn't have an 'Updates:' line to match this. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (March 11, 2019) is 1872 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: 'RFCXXXX' is mentioned on line 1471, but not defined -- Looks like a reference, but probably isn't: '1' on line 1575 -- Looks like a reference, but probably isn't: '2' on line 1578 -- Looks like a reference, but probably isn't: '3' on line 1580 -- Looks like a reference, but probably isn't: '4' on line 1583 -- Looks like a reference, but probably isn't: '5' on line 1586 -- Looks like a reference, but probably isn't: '6' on line 1588 -- Looks like a reference, but probably isn't: '7' on line 1591 -- Looks like a reference, but probably isn't: '8' on line 1594 -- Looks like a reference, but probably isn't: '9' on line 1596 -- Looks like a reference, but probably isn't: '10' on line 1599 -- Looks like a reference, but probably isn't: '11' on line 1602 -- Looks like a reference, but probably isn't: '12' on line 1605 -- Looks like a reference, but probably isn't: '13' on line 1607 == Unused Reference: 'I-D.openconfig-netmod-model-catalog' is defined on line 1522, but no explicit reference was found in the text ** Downref: Normative reference to an Informational draft: draft-verdt-netmod-yang-versioning-reqs (ref. 'I-D.verdt-netmod-yang-versioning-reqs') ** Obsolete normative reference: RFC 7895 (Obsoleted by RFC 8525) == Outdated reference: A later version (-21) exists of draft-ietf-netmod-yang-instance-file-format-02 == Outdated reference: A later version (-03) exists of draft-rwilton-netmod-yang-packages-00 Summary: 3 errors (**), 0 flaws (~~), 5 warnings (==), 17 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group B. Claise 3 Internet-Draft J. Clarke 4 Updates: 7950 (if approved) R. Rahman 5 Intended status: Standards Track R. Wilton, Ed. 6 Expires: September 12, 2019 Cisco Systems, Inc. 7 B. Lengyel 8 Ericsson 9 J. Sterne 10 Nokia 11 K. D'Souza 12 AT&T 13 March 11, 2019 15 YANG Semantic Versioning for Modules 16 draft-verdt-netmod-yang-semver-00 18 Abstract 20 This document specifies a new YANG module update procedure using 21 semantic version numbers, to allow for limited non-backwards- 22 compatible changes, as an alternative proposal to module update rules 23 in the YANG 1.1 specifications. This document updates RFC 7950, RFC 24 8407 and RFC 8525. 26 Status of This Memo 28 This Internet-Draft is submitted in full conformance with the 29 provisions of BCP 78 and BCP 79. 31 Internet-Drafts are working documents of the Internet Engineering 32 Task Force (IETF). Note that other groups may also distribute 33 working documents as Internet-Drafts. The list of current Internet- 34 Drafts is at https://datatracker.ietf.org/drafts/current/. 36 Internet-Drafts are draft documents valid for a maximum of six months 37 and may be updated, replaced, or obsoleted by other documents at any 38 time. It is inappropriate to use Internet-Drafts as reference 39 material or to cite them other than as "work in progress." 41 This Internet-Draft will expire on September 12, 2019. 43 Copyright Notice 45 Copyright (c) 2019 IETF Trust and the persons identified as the 46 document authors. All rights reserved. 48 This document is subject to BCP 78 and the IETF Trust's Legal 49 Provisions Relating to IETF Documents 50 (https://trustee.ietf.org/license-info) in effect on the date of 51 publication of this document. Please review these documents 52 carefully, as they describe your rights and restrictions with respect 53 to this document. Code Components extracted from this document must 54 include Simplified BSD License text as described in Section 4.e of 55 the Trust Legal Provisions and are provided without warranty as 56 described in the Simplified BSD License. 58 Table of Contents 60 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 61 1.1. Updates to YANG RFCs . . . . . . . . . . . . . . . . . . 4 62 1.1.1. Updates to RFC7950 . . . . . . . . . . . . . . . . . 4 63 1.1.2. Updates to RFC8525 . . . . . . . . . . . . . . . . . 4 64 1.1.3. Updates to RFC8407 . . . . . . . . . . . . . . . . . 5 65 1.2. Complementary solutions for the other requirements . . . 5 66 2. YANG Semantic Versioning . . . . . . . . . . . . . . . . . . 6 67 2.1. Classification of changes between module revisions . . . 6 68 2.2. YANG Semantic Versioning Scheme for Modules . . . . . . . 7 69 2.2.1. Examples for YANG semantic version numbers . . . . . 8 70 2.3. YANG Semantic Version Update Rules . . . . . . . . . . . 10 71 2.4. YANG Module Semver Extension . . . . . . . . . . . . . . 11 72 3. Import by Semantic Version . . . . . . . . . . . . . . . . . 13 73 3.1. Module import examples . . . . . . . . . . . . . . . . . 15 74 4. Classifying changes in YANG modules . . . . . . . . . . . . . 16 75 4.1. Editorial changes . . . . . . . . . . . . . . . . . . . . 16 76 4.2. Backwards-compatible changes . . . . . . . . . . . . . . 16 77 4.3. Non-backwards-compatible changes . . . . . . . . . . . . 17 78 5. Updates to ietf-yang-library . . . . . . . . . . . . . . . . 17 79 5.1. Advertising module version number . . . . . . . . . . . . 17 80 5.2. Resolving ambiguous module imports . . . . . . . . . . . 17 81 5.3. Reporting how deprecated and obsolete nodes are handled . 18 82 6. YANG status description extension . . . . . . . . . . . . . . 19 83 7. Semantic versioning of YANG instance data . . . . . . . . . . 19 84 8. Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . 20 85 8.1. Guidelines to YANG model authors . . . . . . . . . . . . 20 86 8.1.1. Use of YANG semantic versioning . . . . . . . . . . . 20 87 8.1.2. Making non-backwards-compatible changes to a YANG 88 module . . . . . . . . . . . . . . . . . . . . . . . 21 89 8.1.2.1. Removing a data node . . . . . . . . . . . . . . 22 90 8.1.2.2. Changing the type of a leaf node . . . . . . . . 23 91 8.1.2.3. Reducing the range of a leaf node . . . . . . . . 23 92 8.1.2.4. Changing the key of a list . . . . . . . . . . . 23 93 8.1.2.5. Renaming a node . . . . . . . . . . . . . . . . . 23 94 8.1.2.6. Changing a default value . . . . . . . . . . . . 23 95 8.2. Guidelines to YANG model clients . . . . . . . . . . . . 24 97 9. Semantic Version Extension YANG Modules . . . . . . . . . . . 24 98 10. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 30 99 11. Security Considerations . . . . . . . . . . . . . . . . . . . 31 100 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 31 101 12.1. YANG Module Registrations . . . . . . . . . . . . . . . 31 102 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 32 103 13.1. Normative References . . . . . . . . . . . . . . . . . . 32 104 13.2. Informative References . . . . . . . . . . . . . . . . . 32 105 Appendix A. Appendix . . . . . . . . . . . . . . . . . . . . . . 34 106 A.1. Open Issues . . . . . . . . . . . . . . . . . . . . . . . 34 107 A.2. Derived Semantic Version . . . . . . . . . . . . . . . . 35 108 A.2.1. The Derived Semantic Version . . . . . . . . . . . . 35 109 A.2.2. Implementation Experience . . . . . . . . . . . . . . 35 110 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 36 112 1. Introduction 114 This document defines a solution to the YANG module lifecycle 115 problems described in [I-D.verdt-netmod-yang-versioning-reqs], 116 covering all of the specified requirements except for requirements: 117 2.2, 3.1, and 3.2. 119 Specifically, this document recognises a need to sometimes allow YANG 120 modules to evolve with non-backwards-compatible changes, which might 121 end up breaking clients. The solution makes use of semantic version 122 numbers to help manage the lifecycle of YANG modules. 124 The solution is comprised of the following seven parts: 126 A definition for the YANG semantic versioning scheme for modules, 127 and an explanation of how the semver extension can be used to 128 annotate modules with their semantic version number. 130 A YANG extension to allow YANG module imports to be restricted to 131 modules with particular semantic versions, allowing inter-module 132 version dependencies to be captured within YANG module 133 definitions. 135 Updates to the YANG 1.1 module update rules to accommodate the 136 semantic versioning scheme. 138 Updates and augmentations to ietf-yang-library to include the YANG 139 semantic version number in the module descriptions, to report how 140 'deprecated' and 'obsolete' nodes are handled by a server, and to 141 clarify how module imports are resolved when multiple versions 142 could otherwise be chosen. 144 A YANG extension to add a 'description' statement to the YANG 145 'status' statement to allow additional documentation as to why a 146 node is being deprecated, and what alternatives may be available. 148 A description of how YANG semantic versioning applies to YANG 149 instance data. 151 Guidelines to YANG module authors on how the YANG semantic 152 versioning rules should be used, along with examples. 154 Open issues are listed at Appendix A.1, and tracked at 155 . 157 1.1. Updates to YANG RFCs 159 1.1.1. Updates to RFC7950 161 This document proposes updates to [RFC7950] to address some of the 162 requirements. It should be noted that there is also active WG 163 discussion on the next steps towards an updated version of YANG, and 164 potentially some of the functionality described here could be folded 165 into an updated revision of [RFC7950], although that might adversely 166 impact when (parts of) a standards based YANG module versioning 167 solution is available. 169 The sections listed below provide updates to [RFC7950]. The design 170 team does not believe any of the changes require a new version of the 171 YANG language. It is believed that the extensions as they are 172 defined can coexist with existing YANG 1.1 clients. 174 o Section 4 describes modification to the [RFC7950] Section 11 175 module update text to advise the use of semantic versioning as 176 described in this document. 178 o Section 3 describes an extension to do import by semantic version. 180 o Section 6 defines an extension that adds a description child 181 element to the YANG "status" statement. 183 1.1.2. Updates to RFC8525 185 This document updates [RFC8525]. Section 5 defines how a reader of a 186 YANG library datastore schema chooses which version of an import-only 187 module is used to resolve a module import when the definition is 188 otherwise ambiguous. 190 1.1.3. Updates to RFC8407 192 Section 8 updates [RFC8407] to provide guidelines on how the YANG 193 module semantic versioning can be used to manage the lifecycle of 194 YANG modules when using strict RFC 7950 chapter 11 backwards 195 compatibility rules are not pragmatic. 197 1.2. Complementary solutions for the other requirements 199 This section is to aid the WG understand how the full set of YANG 200 versioning requirements are intended to be holistically addressed and 201 is intended to be removed if this draft is adopted by the WG. 203 As stated previously, this draft does not address requirements 2.2, 204 3.1 and 3.2 of the requirements specified in 205 [I-D.verdt-netmod-yang-versioning-reqs]. Instead, additional work is 206 needed to address those requirements, which the design team believes 207 would be best addressed in separate drafts. It is hoped that the WG 208 agrees that viable solutions to the other requirements exist that 209 complement the solution proposed in this draft, and thus this work 210 can usefully progress in parallel. In particular, there is value to 211 the industry to achieve standardization of a partial solution that 212 addresses the majority, but not all, of the stated requirements, on 213 the agreement that a full solution will follow. 215 The two additional drafts are: 217 A tooling based solution is proposed for requirement 2.2, that allows 218 two YANG schema versions to be algorithmically compared, with the 219 algorithm reporting the list of differences between the two YANG 220 schema and whether each change is regarded as being editorial, 221 backwards-compatible, or non-backwards-compatible. Annotations to 222 the YANG modules, via the use of extension statements, may help 223 improve the accuracy of the comparison algorithm, particularly for 224 statements that are very hard for an algorithm to correctly classify 225 the scope of any differences (e.g., a change in the semantic 226 behaviour of a data node defined via modifications to the associated 227 YANG description statement). Given that requirement 2.2 is a soft 228 requirement (SHOULD rather than MUST), and practical experience with 229 the tooling is required, it is proposed that this work is deferred at 230 this time. 232 A proposed solution for requirements 3.1 and 3.2 is via the use of 233 YANG packages [I-D.rwilton-netmod-yang-packages] and a protocol based 234 version selection scheme that can be used by clients to choose a 235 particular YANG datastore schema from the set of datastore schema 236 that are supported by the server. 238 2. YANG Semantic Versioning 240 The chapter defines YANG Semantic Versioning, explains how it is used 241 with YANG modules, and the rules associated with changing a module's 242 semantic version number when the module definitions are updated. 244 The YANG semantic versioning scheme applies only to YANG modules. 245 YANG submodules are not independently versioned by the YANG semantic 246 versioning scheme. Instead, if a versioned module includes one or 247 more submodules then those submodules are implicitly versioned as 248 part of the module's 'semver:version' statements, and all the 249 module's 'include' statements MUST specify the revision-date for each 250 of the included submodules. 252 2.1. Classification of changes between module revisions 254 The principle aim of YANG semantic versioning is to allow a user of a 255 YANG module to understand the overall significance of any changes 256 between two module revisions solely based on the semantic version 257 number. 259 The semantic version change between any two arbitrary revisions of a 260 YANG module can be classified into one of four categories: 261 'unchanged', 'editorial, 'backwards-compatible' or 'non-backwards- 262 compatible'. A summary of the classification is given below, with 263 the specific rules as they apply to YANG statements provided in 264 Section 4. 266 The semantic version change between two module revisions is 267 defined as 'unchanged' if, after excluding 'revision' and 268 'semver:version' statements and their substatements, the only 269 remaining changes are insignificant white space changes. 271 An 'editorial' module semantic version change is where there are 272 changes in the module's statements, between the two module 273 revisions, but those changes do not affect the syntax or semantic 274 meaning of the module in any way. An example of an editorial 275 change would be a fix to a spelling mistake in a description 276 statement. 278 A 'backwards-compatible' module semantic version change is where 279 some syntax or semantic changes exists between the two module 280 revisions, but all changes follow the rules specified in 281 Section 4.2. 283 A 'non-backwards-compatible' module semantic version change is 284 where some syntax or semantic changes exists between the two 285 module revisions, and those changes do not follow the rules for a 286 'backwards-compatible' version change. 288 2.2. YANG Semantic Versioning Scheme for Modules 290 This document defines the YANG semantic versioning scheme that is 291 used for YANG modules. The versioning scheme has the following 292 properties: 294 The YANG semantic versioning scheme is extended from version 2.0.0 295 of the semantic versioning scheme defined at semver.org [semver] 296 to cover the additional requirements for the management of YANG 297 module lifecyles that cannot be addressed using the semver.org 298 2.0.0 versioning scheme alone. 300 Unlike the semver.org 2.0.0 versioning scheme, the YANG semantic 301 versioning scheme supports limited updates to older versions of 302 YANG modules, to allow for bug fixes and enhancements to module 303 versions that are not the latest. 305 Module definitions that follow the semver.org 2.0.0 versioning 306 scheme are fully compatible with implementations that understand 307 the YANG semantic versioning scheme. 309 If module updates are always restricted to the latest version of 310 the module only, then the version numbers used by the YANG 311 semantic versioning scheme are exactly the same as those defined 312 by the semver.org 2.0.0 versioning scheme. 314 Every YANG module versioned using the YANG semantic versioning scheme 315 specifies the module's semantic version number by including the 316 'semver:module-version' statement according to the following rules: 318 The module MUST include at least one revision statement. 320 The most recent module revision statement MUST include a 321 'semver:module-version' sub-statement, that defines the module's 322 YANG semantic version. 324 The preceding module revision statement SHOULD also include a 325 'semver:module-version' sub-statement, to allow the module's 326 semantic version history to be derived. 328 All other revision statements MAY include a 'semver:module- 329 version' sub-statement if they have an associated YANG semantic 330 version. 332 "The YANG semver version number is expressed as a string of the form: 333 'X.Y.Zv'; where X, Y, and Z each represent non-negative integers 334 smaller than 32768, and v represents an optional single character 335 suffix: 'm' or 'M'. 337 o 'X' is the MAJOR version. Changes in the major version number 338 indicate changes that are non-backwards-compatible to versions 339 with a lower major version number. 341 o 'Y' is the MINOR version. Changes in the minor version number 342 indicate changes that are backwards-compatible to versions with 343 the same major version number, but a lower minor version number 344 and no patch 'm' or 'M' modifier. 346 o 'Zv' is the PATCH version and modifier. Changes in the patch 347 version number can indicate editorial, backwards-compatible, or 348 non-backwards-compatible changes relative to versions with the 349 same major and minor version numbers, but lower patch version 350 number, depending on what form modifier 'v' takes: 352 * If the modifier letter is absent, the change represents an 353 editorial change 355 * 'm' - the change represents a backwards-compatible change 357 * 'M' - the change represents a non-backwards-compatible change 359 The YANG module name and YANG semantic version number uniquely 360 identifies a revision of a module, with an associated revision date. 361 There MUST NOT be multiple instances of a YANG module definition with 362 the same module name and YANG semantic version number but different 363 content or revision date. 365 There MUST NOT be multiple versions of a YANG module that have the 366 same MAJOR, MINOR and PATCH version numbers, but different patch 367 modifier letter. E.g., module version "1.2.3M" MUST NOT be defined 368 if module version "1.2.3" has already been defined. 370 2.2.1. Examples for YANG semantic version numbers 372 The following diagram and explanation illustrates how YANG semantic 373 version numbers work. 375 Example YANG semantic version numbers for an example module: 377 0.1.0 378 | 379 0.2.0 380 | 381 1.0.0 382 | \ 383 | 1.1.0 -> 1.1.1m -> 1.1.2M 384 | | 385 | 1.2.0 -> 1.2.1M -> 1.2.2M 386 | | 387 | 1.3.0 -> 1.3.1 388 | 389 2.0.0 390 | 391 3.0.0 392 \ 393 3.1.0 395 The tree diagram above illustrates how an example modules version 396 history might evolve. For example, the tree might represent the 397 following changes, listed in chronological order from oldest revision 398 to newest: 400 0.1.0 - first beta module version 402 0.2.0 - second beta module version (with NBC changes) 404 1.0.0 - first release (may have NBC changes from 0.2.0) 406 1.1.0 - added new functionality, leaf "foo" (BC) 408 1.2.0 - added new functionality, leaf "baz" (BC) 410 1.3.0 - improve existing functionality, added leaf "foo-64" (BC) 412 1.3.1 - improve description wording for "foo-64" (Editorial) 414 1.1.1m - backport "foo-64" leaf to 1.1.x to avoid implementing 415 "baz" from 1.2.0 (BC) 417 2.0.0 - change existing model for performance reasons, e.g. re-key 418 list (NBC) 420 1.1.2M - NBC point bug fix, not required in 2.0.0 due to model 421 changes (NBC) 422 3.0.0 - NBC bugfix, rename "baz" to "bar"; also add new BC leaf 423 "wibble"; (NBC) 425 1.2.1M - backport NBC fix, changing "baz" to "bar" 427 1.2.2M - backport "wibble". This is a BC change but "M" modifier 428 is sticky. 430 3.1.0 - introduce new leaf "wobble" (BC) 432 The partial ordering relationships based on the semantic versioning 433 numbers can be defined as follows: 435 1.0.0 < 1.1.0 < 1.2.0 < 1.3.0 < 2.0.0 < 3.0.0 < 3.1.0 437 1.0.0 < 1.1.0 < 1.1.1m < 1.1.2M 439 1.0.0 < 1.1.0 < 1.2.0 < 1.2.1M < 1.2.2M 441 There is no ordering relationship between 1.1.1M and either 1.2.0 or 442 1.2.1M, except that they share the common ancestor of 1.1.0. 444 Looking at the version number alone, the module definition in 2.0.0 445 does not necessarily contain the contents of 1.3.0. However, the 446 module revision history in 2.0.0 would likely indicate that it was 447 edited from module version 1.3.0. 449 2.3. YANG Semantic Version Update Rules 451 When a new revision of a module is produced, then the following rules 452 define how the YANG semantic version number for the new module 453 revision is calculated, based on the changes between the two module 454 revisions, and the YANG semantic version number of the base module 455 revision that the changes are derived from. A two step process is 456 used: 458 The first step is to classify the module change as 'editorial', 459 'backwards-compatible', or 'non-backwards-compatible version' using 460 the rules defined in Section 2.1 and Section 4. 462 The second step is to calculate the value of the 'semver:version' 463 field for the new module revision, based on the value of the 464 'semver:version' field in the base module, any how the module changes 465 have been classified. 467 The following rules define how the value for the 'semver:version' 468 argument in the new module revision is calculated: 470 1. If a module is being updated in a non-backwards-compatible way, 471 then the module version "X.Y.Z[m|M]" MUST be updated to "X+1.0.0" 472 unless that module version has already been defined with 473 different content, in which case the module version "X.Y.Z+1M 474 MUST be used instead. 476 2. If a module is being updated in a backwards-compatible way, then 477 the next version number depends on the format of the current 478 version number: 480 i "X.Y.Z" - the module version MUST be updated to "X.Y+1.0", 481 unless that module version has already been defined with 482 different content, when the module version MUST be updated 483 to "X.Y.Z+1m instead". 485 ii "X.Y.Zm" - the module version MUST be updated to 486 "X.Y.Z+1m". 488 iii "X.Y.ZM" - the module version MUST be updated to 489 "X.Y.Z+1M". 491 3. If a module is being updated in an editorial way, then the next 492 version number depends on the format of the current version 493 number: 495 i "X.Y.Z" - the module version MUST be updated to "X.Y.Z+1" 497 ii "X.Y.Zm" - the module version MUST be updated to 498 "X.Y.Z+1m". 500 iii "X.Y.ZM" - the module version MUST be updated to 501 "X.Y.Z+1M". 503 4. YANG module semantic version numbers beginning with 0, i.e 504 "0.X.Y" are regarded as beta definitions and need not follow the 505 rules above. Either the MINOR or PATCH version numbers may be 506 updated, regardless of whether the changes are non-backwards- 507 compatible, backwards-compatible, or editorial. 509 2.4. YANG Module Semver Extension 511 This document defines a YANG extension to add the YANG module 512 semantic version to a Module. The complete definition of this YANG 513 module is in Section 9. 515 extension module-version { 516 argument semver; 517 } 519 The extension would typically be used this way: 521 module yang-module-name { 523 namespace "name-space"; 524 prefix "prefix-name"; 526 import ietf-semver { prefix "semver"; } 528 description 529 "to be completed"; 531 revision 2018-02-28 { 532 description "Added leaf 'wobble'"; 533 semver:module-version "3.1.0"; 534 } 536 revision 2017-12-31 { 537 description "Rename 'baz' to 'bar', added leaf 'wibble'"; 538 semver:module-version "3.0.0"; 539 } 541 revision 2017-10-30 { 542 description "Change the module structure"; 543 semver:module-version "2.0.0"; 544 } 546 revision 2017-08-30 { 547 description "Clarified description of 'foo-64' leaf"; 548 semver:module-version "1.3.1"; 549 } 551 revision 2017-07-30 { 552 description "Added leaf foo-64"; 553 semver:module-version "1.3.0"; 554 } 556 revision 2017-04-20 { 557 description "Add new functionality, leaf 'baz'"; 558 semver:module-version "1.2.0"; 559 } 561 revision 2017-04-03 { 562 description "Add new functionality, leaf 'foo'"; 563 semver:module-version "1.1.0"; 564 } 566 revision 2017-04-03 { 567 description "First release version."; 568 semver:module-version "1.0.0"; 569 } 571 revision 2017-01-30 { 572 description "NBC changes to initial revision"; 573 semver:module-version "0.2.0"; 574 } 576 revision 2017-01-26 { 577 description "Initial module version"; 578 semver:module-version "0.1.0"; 579 } 581 //YANG module definition starts here 583 See also "Semantic Versioning and Structure for IETF Specifications" 584 [I-D.claise-semver] for a mechanism to combine the semantic 585 versioning, the GitHub tools, and a potential change to the IETF 586 process. 588 3. Import by Semantic Version 590 RFC 7950 allows YANG module 'import' statements to optionally require 591 the imported module to have a particular revision date. In practice, 592 importing a module with an exact revision date is overly burdensome 593 because it requires the importing module to be updated whenever any 594 change to the imported module occurs. The alternative choice of 595 using an import statement without a revision date is also not ideal 596 because the importing module may not work with all possible revisions 597 of the imported module. 599 With semantic versioning, it is desirable for a importing module to 600 specify the set of module versions of the imported module that are 601 anticipated to be compatible. 603 This document specifies a YANG extension for selecting which versions 604 of a module may be imported. It is designed around the assumption 605 that most changes to a YANG module do not break importing modules, 606 even if the changes themselves are not backwards compatible. E.g., 607 fixing an incorrect pattern statement or description for a leaf would 608 not break an import, changing the name of a leaf could break an 609 import but frequently would not, but removing a container would break 610 imports if it is augmented by another module. 612 The ietf-semver module defines the 'version' extension, a 613 substatement to the YANG 'import' statement. 615 An 'import' statement MAY contain 'version' statements or a 616 'revision-date' statement, but not both. 618 The 'version' statement MAY be specified multiple times, requiring 619 that the imported module version conforms to at least one of the 620 'version' statements. 622 The argument to the 'version' statement takes one of three valid 623 forms: 625 1. "A.B.C" - import the exact module version that matches "A.B.C". 627 2. "A.B.C+" - import any module version that matches, or is greater 628 than, "A.B.C". 630 3. "A.B.C-X.Y.Z" - import any module version that matches, or is 631 greater than, "A.B.C"; and also matches, or is less than, 632 "X.Y.Z". The word "MAX" can be used for 'Y' or 'Z' to represent 633 the numerical value 32,767. 635 The rules for comparing module version numbers are as follows: 637 1. Version "R.S.T" matches version "A.B.C", only if 639 R = A, S = B, and T = C 641 2. Version "R.S.T" is greater than version "A.B.C", only if 643 R = A, S = B, and T > C; or 645 R = A and S > B; or 647 R > A 649 3. Version "R.S.T" is less than version "X.Y.Z", only if 651 R = X, S = Y, and T < Z; or 653 R = X and S < Y; or 655 R < X 657 The patch modifier letter is not included as part of the 658 'semver:version' argument, and is entirely ignored for import 659 statement module version number comparisons. 661 3.1. Module import examples 663 Consider an example module "example-module" that is hypothetically 664 available in the following versions: 0.1.0, 0.2.0, 1.0.0, 1.1.0, 665 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, 666 and 3.1.0. E.g. matching the versions illustrated in Section 2.2.1. 668 The first example selects the specific version 1.1.2M. A specific 669 version import might be used if 1.1.2M contained changes that are 670 incompatible with other versions. 672 import example-module { 673 semver:version 1.1.2; 674 } 676 The next example selects module versions that match, or are greater 677 than, version 1.2.0. This form may be used if there is a dependency 678 on a data node introduced in version 1.2.0. This is expected to be 679 the most commonly used form of 'import by version'. 681 Includes versions: 1.2.0, 1.2.1M, 1.2.2M, 1.3.0, 1.3.1, 2.0.0, 3.0.0 682 and 3.1.0. 684 import example-module { 685 semver:version 1.2.0+; 686 } 688 The next example selects module versions that match, or are greater 689 than 1.1.0, but excluding all 1.1.x and 1.2.x 'M' versions. This 690 form may be needed if structural non backwards compatible changes are 691 introduced in a patch 'M' version. Generally, it is advisable to 692 avoid making such changes. 694 Includes versions: 1.1.0, 1.1.1m, 1.2.0, 1.3.0, 1.3.1, 2.0.0, 3.0.0, 695 and 3.1.0. 697 import example-module { 698 semver:version 1.1.0-1.1.1; 699 semver:version 1.2.0; 700 semver:version 1.3.0+; 701 } 703 The last example selects all module versions with a major version 704 number of 1. This form may be useful if significant non backwards 705 compatible changes have been introduced in version 2.0.0 that break 706 import backwards compatibility. 708 Includes versions: 1.0.0, 1.1.0, 1.1.1m, 1.1.2M, 1.2.0, 1.2.1M, 709 1.2.2M, 1.3.0 and 1.3.1. 711 import example-module { 712 semver:version 1.0.0-1.MAX.MAX; 713 } 715 4. Classifying changes in YANG modules 717 [RFC7950] chapter 11 defines the rules for what constitutes a 718 backwards compatible change in YANG 1.1. However, the YANG semantic 719 versioning scheme defined in this document uses a slightly modified 720 version of this scheme, and also provides rules to classify changes 721 as editorial, backwards-compatible, or non-backwards-compatible. 723 4.1. Editorial changes 725 Any changes that do not change the ordering or meaning of the YANG 726 module in any way are classified as 'editorial'. The following rules 727 define 'editorial': 729 o Changing any 'description' statement if it does not change the 730 semantic meaning of the statement is relates to. E.g., fixing 731 spelling or grammar, or changing layout, are all allowed. 733 o Adding or updating 'reference' statements. 735 o Adding or updating the 'organization' statement. 737 o Adding a new 'revision' or 'semver:module-version' statement, or 738 correcting a previous 'revision' or 'semver:module-version' 739 statement. 741 o A module may be split into a set of submodules or a submodule may 742 be removed, provided the definitions in the module do not change 743 except in the ways described above. 745 4.2. Backwards-compatible changes 747 [RFC7950] chapter 11 defines the rules for what constitutes a 748 backwards-compatible change in YANG 1.1. The document update these 749 rules in the following ways: 751 o Adding or changing a 'status' node to 'obsolete' is not a 752 backwards-compatible change. Other changes/additions of status 753 elements are backwards-compatible, as per [RFC7950]. 755 o Changing the ordering of statements is allowed if it does not 756 chanage the ordering of an rpc's 'input' substatements. 758 4.3. Non-backwards-compatible changes 760 All other changes to YANG modules that are not classified as 761 'editorial' or 'backwards-compatible' are defined as being non- 762 backwards-compatible. 764 Examples of non-backwards-compatible changes include: 766 o Deleting a data node, or changing it to status obsolete. 768 o Changing the name, type, or units of a data node. 770 o Modifying the description in a way that changes the semantic 771 meaning of the data node. 773 o Any changes that change or reduce the allowed value set of the 774 data node, either through changes in the type definition, or the 775 addition or changes to 'must' statements, or changes in the 776 description. 778 o Adding or modifying 'when' statements that reduce when the data 779 node is available in the schema. 781 o Making the statement conditional on if-feature. 783 5. Updates to ietf-yang-library 785 YANG library [RFC7895] [RFC8525] is modified to support semantic 786 versioning in three ways. 788 5.1. Advertising module version number 790 The ietf-semver YANG module augments the 'module' list in ietf-yang- 791 library with a 'version' leaf to optionally declare the YANG semantic 792 version of each module. 794 5.2. Resolving ambiguous module imports 796 A YANG datastore schema, defined in [RFC8525], can specify multiple 797 revisions of a YANG module in the schema using the 'import-only' 798 list, with the requirement from [RFC7950] that only a single revision 799 of a YANG module may be implemented. 801 If a YANG module import statement does not specify a specific version 802 or revision within the datastore schema then it could be ambiguous as 803 to which module revision the import statement should resolve to. 804 Hence, a datastore schema constructed by a client using the 805 information contained in YANG library may not exactly match the 806 datastore schema actually used by the server. 808 The following rules remove the ambiguity: 810 If a module import statement could resolve to more than one module 811 revision defined in the datastore schema, and one of those revisions 812 is implemented (i.e., not an 'import-only' module), then the import 813 statement MUST resolve to the revision of the module that is defined 814 as being implemented by the datastore schema. 816 If a module import statement could resolve to more than one module 817 revision defined in the datastore schema, and none of those revisions 818 are implemented, but one of more modules revisions specify a YANG 819 semantic version, then the import MUST resolve to the module with the 820 greatest version number, according to the version comparison rules in 821 Section 3. 823 If a module import statement could resolve to more than one module 824 revision defined in the datastore schema, none of those revisions are 825 implemented, and none of the modules revisions have a YANG semantic 826 version number, then the import MUST resolve to the module that has 827 the most recent revision date. 829 5.3. Reporting how deprecated and obsolete nodes are handled 831 The ietf-semver YANG module augments YANG library with two leaves to 832 allow a server to report how it handles status 'deprecated' and 833 status 'obsolete' nodes. The leaves are: 835 deprecated-nodes-implemented: If present, this leaf indicates that 836 all schema nodes with a status 'deprecated' child statement are 837 implemented equivalently as if they had status 'current', or 838 otherwise deviations MUST be used to explicitly remove 839 'deprecated' nodes from the schema. If this leaf is absent then 840 the behavior is unspecified. 842 obsolete-nodes-absent: If present, this leaf indicates that the 843 server does not implement any status 'obsolete' nodes. If this 844 leaf is absent then the behaviour is unspecified. 846 Implementations that implement the YANG semantic versioning scheme 847 defined in this document MUST set the 'deprecated-nodes-implemented' 848 leaf because the refined module update rules in Section 4 require 849 that this is how servers handle 'deprecated' and 'obsolete' nodes to 850 comply with YANG module semantic versioning. 852 If a server does not set the 'deprecated-nodes-implemented' leaf, 853 then clients MUST NOT rely solely on the YANG module semantic version 854 number to determine whether two module versions are backwards 855 compatible, and MUST also consider whether the status of any nodes 856 has changed to 'deprecated' and whether those nodes are implemented 857 by the server. 859 6. YANG status description extension 861 The ietf-semver module specifies the YANG extension 'status- 862 description' that can be used as a substatement of the status 863 statement. The argument to this extension can contain freeform text 864 to help readers of the module understand why the node was deprecated 865 or made obsolete, when it is anticipated that the node will no longer 866 be available for use, and potentially reference other schema elements 867 that can be used instead. An example is shown below. 869 leaf imperial-temperature { 870 type int64; 871 units "degrees Fahrenheit"; 872 status deprecated { 873 semver:status-description 874 "Imperial measurements are being phased out in favor 875 of their metric equivalents. Use metric-temperature 876 instead."; 877 } 878 description 879 "Temperature in degrees Fahrenheit."; 880 } 882 7. Semantic versioning of YANG instance data 884 Instance data sets [I-D.ietf-netmod-yang-instance-file-format] do not 885 have an associated YANG semantic version, as compatibility for 886 instance data is undefined. 888 However, instance data may reference an associated YANG schema, and 889 that schema could make use of semantic version numbers, both for the 890 individual YANG modules that comprise the schema, and potentially for 891 the entire schema itself (e.g., [I-D.rwilton-netmod-yang-packages]). 893 In this way, the versioning of a schema associated with an instance 894 data set, may allow a client to determine whether the instance data 895 could also be used in conjunction with other versions of the YANG 896 schema, or other versions of the modules that define the schema. 898 One common scenario, where instance data may have to cope with 899 changes to the schema is for the datastore when a server is 900 restarted with a different YANG schema (e.g. due to a software 901 upgrade or downgrade). How a server restores the configuration from 902 during such upgrades or downgrades is outside the scope of 903 this specification. 905 8. Guidelines 907 8.1. Guidelines to YANG model authors 909 NBC changes to YANG models may cause problems to clients, who are 910 consumers of YANG models, and SHOULD be avoided. However, there are 911 cases where NBC changes are required, e.g. to fix an incorrect YANG 912 model. 914 YANG model authors are recommended to minimize NBC changes and keep 915 changes BC whenever possible. 917 The use of status "deprecated" with the status-description statement 918 allows clients to plan a migration to alternative data nodes. 920 When NBC changes are introduced, consideration should be given to the 921 impact on clients and YANG model authors SHOULD try to mitigate that 922 impact. 924 8.1.1. Use of YANG semantic versioning 926 Module authors should use the following guidance when applying the 927 module version update rules specified in Section 2.3. 929 Updates to modules SHOULD be applied to the latest version of YANG 930 modules, avoiding the use the 'm|M' patch modifier. When used in 931 this way, the YANG semantic version numbers are compatible with the 932 versioning scheme defined by the semver.org 2.0.0 rules. 934 Changes to older versions of published YANG modules SHOULD be 935 minimized, since there may be a greater impact on clients, and 936 comparing between version numbers becomes more limited if the 'm|M' 937 modifiers are used. However, if it is necessary to make such changes 938 then the following guidelines apply: 940 Any changes SHOULD also be made to a new latest version of the 941 YANG module, if appropriate. 943 Where possible, changes SHOULD be restricted to backwards- 944 compatible changes only. 946 NBC changes MAY be made, subject to the constraints defined in 947 Section 2.3. The impact to clients SHOULD be carefully considered 948 and minimized if possible. 950 The version numbers associated with a module MUST never be reused. 951 E.g., when updating module version 3.4.0 in a NBC manner the module 952 author must verify whether version 4.0.0 is available for use and if 953 that version was already used, the updated module must use version 954 3.4.1M instead. 956 Patch modifier letters (i.e. 'm' or 'M') are sticky. For example if 957 version 3.4.1M is modified in a BC way, the next version is 3.4.2M. 958 This is to indicate that 3.4.2M is not BC with 3.4.0, however it 959 comes at the cost of not being able to indicate the type of change 960 between 3.4.1M and 3.4.2M. 962 As explained in Appendix A.2.2, while programatically determining a 963 semantic version is possible using tools (e.g. the pyang utility), 964 human oversight is highly recommended because of some special cases 965 which can not be detected by tools. Therefore, a model author SHOULD 966 use both means to determine a model's semantic version. 968 8.1.2. Making non-backwards-compatible changes to a YANG module 970 There are various valid situations where a YANG module has to be 971 modified in a non-backwards-compatible way. Here are the different 972 ways in which this can be done: 974 o If the server can support NBC versions of the YANG module 975 simultaneously using version selection, then the NBC changes MAY 976 be done immediately. Clients would be required to select the 977 version which they support and the NBC change would have no impact 978 on them. 980 o When possible, NBC changes are done incrementally to provide 981 clients time to adapt to NBC changes. 983 Here are some guidelines on how non-backwards compatible changes can 984 be made incrementally: 986 1. The changes should be made incrementally, e.g. a data node's 987 status SHOULD NOT be changed directly from "current" to 988 "obsolete" (see Section 4.7 of [RFC8407]), instead the status 989 SHOULD first be marked "deprecated" and then when support is 990 removed its status MUST be changed to "obsolete". Instead of 991 using the "obsolete" status, the data node MAY be removed from 992 the model but this has the risk of breaking modules which import 993 the modified module. 995 2. A node with status "deprecated" MUST be supported for the 996 solution described here to function properly. 998 3. A node with status "deprecated" SHOULD be available for at least 999 one year before its status is changed to "obsolete", see 1000 Section 4.7 of [RFC8407]. 1002 4. Support for a node which is "obsolete" is indicated by the node 1003 "obsolete-nodes-present, see Section 5. 1005 5. The new extension "status-description" SHOULD be used for nodes 1006 which are "obsolete" or "deprecated". 1008 6. For status "deprecated", the "status-description" SHOULD also 1009 indicate until when support for the node is guaranteed. If there 1010 is a replacement data node, rpc, action or notification for the 1011 deprecated node, this SHOULD be stated in the "status- 1012 description". 1014 7. When obsoleting or deprecating data nodes, the "deprecated" or 1015 "obsolete" status SHOULD be applied at the highest possible level 1016 in the data tree. For example, when deprecating all data nodes 1017 in a container, the "deprecated" status SHOULD be applied to the 1018 container. For clarity, the status MAY be added in all the 1019 affected nodes but the status-description SHOULD be added only at 1020 the highest level in the tree. 1022 The following sections have examples on how non-backwards-compatible 1023 changes can be made. 1025 8.1.2.1. Removing a data node 1027 Removing a leaf or container from the data tree, e.g. because support 1028 for the corresponding feature is being removed: 1030 1. The node's status SHOULD be changed to "deprecated" and it MUST 1031 be supported for at least one year. This is a backwards- 1032 compatible change. 1034 2. When the node is not available anymore, its status MUST be 1035 changed to "obsolete" and the "status-description" updated, this 1036 is a non-backwards-compatible change. The "status-description" 1037 SHOULD be used to explain why the node is not available anymore. 1039 8.1.2.2. Changing the type of a leaf node 1041 Changing the type of a leaf-node. e.g. consider a "vpn-id" node of 1042 type integer being changed to a string: 1044 1. The status of node "vpn-id" SHOULD be changed to "deprecated" and 1045 the node SHOULD be available for at least one year. This is a 1046 backwards-compatible change. 1048 2. A new node, e.g. "vpn-name", of type string is added to the same 1049 location as the existing node "vpn-id". This new node has status 1050 "current" and its description SHOULD explain that it is replacing 1051 node "vpn-id". 1053 3. During the period of time where both nodes are available, how the 1054 server behaves when either node is set is outside the scope of 1055 this document and will vary on a case by case basis. Here are 1056 some options: 1058 1. A server MAY prevent the new node from being set if the old 1059 node is already set (and vice-versa). The new node MAY have 1060 a when statement to achieve this. The old node MUST NOT have 1061 a when statement since this would be a non-backwards- 1062 compatible change, but the server MAY reject the old node 1063 from being set if the new node is already set. 1065 2. If the new node is set and a client does a get or get-config 1066 operation on the old node, the server MAY map the value. For 1067 example, if the new node "vpn-name" has value "123" then the 1068 server MAY return integer value 123 for the old node "vpn- 1069 id". However, if the value can not be mapped, we need a way 1070 of returning "unsupported" TBD. 1072 4. When node "vpn-id" is not available anymore, its status MUST be 1073 changed to "obsolete" and the "status-description" is updated. 1074 This is a non-backwards-compatible change. 1076 8.1.2.3. Reducing the range of a leaf node 1078 8.1.2.4. Changing the key of a list 1080 8.1.2.5. Renaming a node 1082 8.1.2.6. Changing a default value 1083 8.2. Guidelines to YANG model clients 1085 Guidelines for clients of modules using YANG semantic versioning: 1087 o Clients SHOULD be liberal when processing data received from a 1088 server. For example, the server may have increased the range of 1089 an operational node causing the client to receive a value which is 1090 outside the range of the YANG model revision it was coded against 1092 o Clients SHOULD monitor changes to published YANG modules through 1093 their version numbers, and use appropriate tooling to understand 1094 the specific changes between module versions. In particular, 1095 clients SHOULD NOT migrate to NBC versions of a module without 1096 first understanding the specifics of the NBC changes. 1098 o Clients SHOULD plan to make changes to match published status 1099 changes. When a node's status changes from "current" to 1100 "deprecated", clients SHOULD plan to stop using that node in a 1101 timely fashion. When a node's status changes to "obsolete", 1102 clients MUST stop using that node. 1104 9. Semantic Version Extension YANG Modules 1106 YANG module with extensions for defining a module's YANG semantic 1107 version number, and importing by version. 1109 file "ietf-semver@2019-02-07.yang" 1110 module ietf-semver { 1111 yang-version 1.1; 1112 namespace "urn:ietf:params:xml:ns:yang:ietf-semver"; 1113 prefix semver; 1115 organization 1116 "IETF NETMOD (Network Modeling) Working Group"; 1117 contact 1118 "WG Web: 1119 WG List: 1121 Author: Benoit Claise 1122 1124 Author: Joe Clarke 1125 1127 Author: Reshad Rahman 1128 1130 Author: Robert Wilton 1131 1133 Author: Kevin D'Souza 1134 1136 Author: Balazs Lengyel 1137 1139 Author: Jason Sterne 1140 "; 1141 description 1142 "This module contains a definition for a YANG 1.1 extension to 1143 express the semantic version of YANG modules."; 1145 revision 2019-02-27 { 1146 description 1147 "* Move YANG library augmentations into a separate module. 1148 * Update references."; 1149 reference 1150 "draft-verdt-netmod-yang-semver: 1151 YANG Semantic Versioning for Modules"; 1152 semver:module-version "0.3.0"; 1153 } 1155 revision 2018-04-05 { 1156 description 1157 "* Properly import ietf-yang-library. 1158 * Fix the name of module-semver => module-version. 1159 * Fix regular expression syntax. 1160 * Augment yang-library with booleans as to whether or not 1161 deprecated and obsolete nodes are present. 1162 * Add an extension to enable import by semantic version. 1163 * Add an extension status-description to track deprecated 1164 and obsolete reasons. 1165 * Fix yang-library augments to use 7895bis."; 1166 reference 1167 "draft-clacla-netmod-yang-model-update: 1168 New YANG Module Update Procedure"; 1169 semver:module-version "0.2.1"; 1170 } 1171 revision 2017-12-15 { 1172 description 1173 "Initial revision."; 1174 reference 1175 "draft-clacla-netmod-yang-model-update: 1176 New YANG Module Update Procedure"; 1177 semver:module-version "0.1.1"; 1178 } 1179 typedef version { 1180 type string { 1181 pattern '[0-9]{1,5}\.[0-9]{1,5}\.[0-9]{1,5}(m|M)?'; 1182 } 1183 description 1184 "The type used to represent a YANG semantic version number. 1186 The YANG semver version number is expressed as a string of the 1187 form: 'X.Y.Zv'; where X, Y, and Z each represent non-negative 1188 integers smaller than 32768, and v represents an optional 1189 single character suffix: 'm' or 'M'. 1191 o 'X' is the MAJOR version. Changes in the major version 1192 number indicate changes that are non-backwards-compatible to 1193 versions with a lower major version number. 1195 o 'Y' is the MINOR version. Changes in the minor version 1196 number indicate changes that are backwards-compatible to 1197 versions with the same major version number, but a lower 1198 minor version number. 1200 o 'Zv' is the PATCH version and modifier. Changes in the patch 1201 version number can indicate editorial, backwards-compatible, 1202 or non-backwards-compatible changes relative to versions with 1203 the same major and minor version numbers, but lower patch 1204 version number, depending on what form modifier 'v' takes: 1206 * 'M' - the change represents a non-backwards-compatible 1207 change 1209 * 'm' - the change represents a backwards-compatible change 1211 * If the modifier letter is absent, the change represents an 1212 editorial change"; 1214 reference 1215 "draft-verdt-netmod-yang-semver: YANG Semantic Versioning"; 1216 } 1218 extension module-version { 1219 argument semver; 1220 description 1221 "The version number for the module revision it is used in. 1223 This format of the argument matches the type version. 1225 The rules for updating the module-version number are described 1226 in section XXX of 'YANG Semantic Versioning for Modules'; 1227 By comparing the module-version between two revisions of a 1228 given module, one can determine if different revisions are 1229 backwards compatible or not, as well as whether or not new 1230 features have been added to a newer revision. 1232 If a module contains this extension it indicates that for this 1233 module the updated status and update rules as this described 1234 in RFC XXXX are used. 1236 The statement MUST only be a substatement of the 'revision' 1237 statements. Zero or one module-version statement is allowed 1238 per parent statement. No substatements are allowed. 1240 'revision' statements in submodules MAY contain a 1241 'module-version' statement for documentation purposes, but 1242 its meaning is undefined, and has no effect on the including 1243 module's semantic version."; 1244 reference 1245 "draft-verdt-netmod-yang-semver: 1246 YANG Semantic Versioning for Modules"; 1247 } 1249 extension import-versions { 1250 argument version-clause; 1251 description 1252 "This extension specifies an acceptable set of semantic 1253 versions of a given module that may be imported. 1255 The statement MUST only be a substatement of the import 1256 statement. 1258 The statement MUST NOT be present if the import has a 1259 revision-date substatement. 1261 The statement MUST NOT be present if the imported module does 1262 not support semantic versioning. 1264 Zero or more versions statements are allowed per parent 1265 statement. No substatements are allowed. 1267 The version-clause argument MUST follow one of the below 1268 patterns: 1269 (i) "+' \d+\.\d+\.\d+ '+" 1270 Matches exact version, e.g. 3.6.1 1272 (ii) "+ '\d+\.\d+\.\d+\+ '+" 1273 Matches exact version or greater, e.g. 3.6.1+ 1275 (iii) "+' \d+\.\d+.\d+-\d+\.(\d+|MAX).(\d|MAX)+ '+" 1276 Matches inclusive range, 1277 e.g. 3.6.1-7.8.4, or 3.2.1-3.MAX.MAX"; 1279 reference 1280 "draft-verdt-netmod-yang-semver: Import by Semantic Version"; 1281 } 1283 extension status-description { 1284 argument description; 1285 description 1286 "Freeform text that describes why a given node has been 1287 deprecated or made obsolete. This may point to other schema 1288 elements that can be used in lieu of the given node. 1290 This statement MUST only be used as a substatement of the 1291 status statement 1293 Zero or more status-description statements are allowed per 1294 parent statement. No substatements are allowed."; 1295 reference 1296 "draft-verdt-netmod-yang-semver: YANG status description 1297 extension"; 1298 } 1299 } 1300 1302 YANG module with augmentations to YANG Library to support semantic 1303 version numbers. 1305 file "ietf-yl-semver@2019-02-07.yang" 1306 module ietf-yl-semver { 1307 yang-version 1.1; 1308 namespace "urn:ietf:params:xml:ns:yang:ietf-yl-semver"; 1309 prefix yl-semver; 1311 import ietf-semver { 1312 prefix semver; 1313 } 1315 import ietf-yang-library { 1316 prefix yanglib; 1317 } 1319 organization 1320 "IETF NETMOD (Network Modeling) Working Group"; 1321 contact 1322 "WG Web: 1323 WG List: 1325 Author: Benoit Claise 1326 1328 Author: Joe Clarke 1329 1331 Author: Reshad Rahman 1332 1334 Author: Robert Wilton 1335 1337 Author: Kevin D'Souza 1338 1340 Author: Balazs Lengyel 1341 1343 Author: Jason Sterne 1344 "; 1345 description 1346 "This module contains augmentations to YANG Library to add module 1347 level semantic version numbers and to provide an indication of 1348 how deprecated and obsolete nodes are handled by the server."; 1350 semver:module-version "0.1.0"; 1352 revision 2019-02-27 { 1353 description 1354 "Moved YANG library augmentations into a separate module."; 1355 reference 1356 "draft-verdt-netmod-yang-semver: 1357 YANG Semantic Versioning for Modules"; 1358 semver:module-version "0.1.0"; 1359 } 1361 augment "/yanglib:yang-library/yanglib:module-set/yanglib:module" { 1362 description 1363 "Augmentation modules with a semantic version."; 1364 leaf version { 1365 type semver:version; 1366 description 1367 "The semantic version for this module. The version MUST 1368 match the semver:version value in specific revision of the 1369 module loaded in this module-set."; 1370 reference 1371 "draft-verdt-netmod-yang-semver: YANG Semantic Versioning"; 1372 } 1373 } 1375 augment "/yanglib:yang-library/yanglib:schema" { 1376 description 1377 "Augmentations to the ietf-yang-library module to indicate how 1378 deprecated and obsoleted nodes are handled for each datastore 1379 schema supported by the server."; 1381 leaf deprecated-nodes-implemented { 1382 type empty; 1383 description 1384 "If present, this leaf indicates that all schema nodes with a 1385 status 'deprecated' child statement are implemented 1386 equivalently as if they had status 'current', or otherwise 1387 deviations MUST be used to explicitly remove 'deprecated' 1388 nodes from the schema. If this leaf is absent then the 1389 behavior is unspecified."; 1390 reference 1391 "draft-verdt-netmod-yang-semver: Reporting how deprecated and 1392 obsolete nodes are handled"; 1393 } 1394 leaf obsolete-nodes-absent { 1395 type empty; 1396 description 1397 "If present, this leaf indicates that the server does not 1398 implement any status 'obsolete' nodes. If this leaf is 1399 absent then the behaviour is unspecified."; 1400 reference 1401 "draft-verdt-netmod-yang-semver: Reporting how deprecated and 1402 obsolete nodes are handled"; 1403 } 1404 } 1405 } 1406 1408 10. Contributors 1410 This document grew out of the YANG module versioning design team that 1411 started after IETF 101. The design team consists of the following 1412 members whom have worked on the YANG versioning project: 1414 o Balazs Lengyel 1416 o Benoit Claise 1418 o Ebben Aries 1419 o Jason Sterne 1421 o Joe Clarke 1423 o Juergen Schoenwaelder 1425 o Mahesh Jethanandani 1427 o Michael (Wangzitao) 1429 o Qin Wu 1431 o Reshad Rahman 1433 o Rob Wilton 1435 The initial revision of this document was refactored and built upon 1436 [I-D.clacla-netmod-yang-model-update]. 1438 Discussons on the use of Semver for YANG versioning has been held 1439 with authors of the OpenConfig YANG models. We would like thank both 1440 Anees Shaikh and Rob Shakir for their input into this problem space. 1442 11. Security Considerations 1444 The document does not define any new protocol or data model. There 1445 are no security impacts. 1447 12. IANA Considerations 1449 12.1. YANG Module Registrations 1451 The following YANG module is requested to be registred in the "IANA 1452 Module Names" registry: 1454 The ietf-semver module: 1456 Name: ietf-semver 1458 XML Namespace: urn:ietf:params:xml:ns:yang:ietf-semver 1460 Prefix: semver 1462 Reference: [RFCXXXX] 1464 The ietf-yl-semver module: 1466 Name: ietf-yl-semver 1467 XML Namespace: urn:ietf:params:xml:ns:yang:ietf-yl-semver 1469 Prefix: yl-semver 1471 Reference: [RFCXXXX] 1473 13. References 1475 13.1. Normative References 1477 [I-D.verdt-netmod-yang-versioning-reqs] 1478 Clarke, J., "YANG Module Versioning Requirements", draft- 1479 verdt-netmod-yang-versioning-reqs-02 (work in progress), 1480 November 2018. 1482 [RFC7895] Bierman, A., Bjorklund, M., and K. Watsen, "YANG Module 1483 Library", RFC 7895, DOI 10.17487/RFC7895, June 2016, 1484 . 1486 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 1487 RFC 7950, DOI 10.17487/RFC7950, August 2016, 1488 . 1490 [RFC8407] Bierman, A., "Guidelines for Authors and Reviewers of 1491 Documents Containing YANG Data Models", BCP 216, RFC 8407, 1492 DOI 10.17487/RFC8407, October 2018, 1493 . 1495 [RFC8525] Bierman, A., Bjorklund, M., Schoenwaelder, J., Watsen, K., 1496 and R. Wilton, "YANG Library", RFC 8525, 1497 DOI 10.17487/RFC8525, March 2019, 1498 . 1500 13.2. Informative References 1502 [I-D.clacla-netmod-model-catalog] 1503 Clarke, J. and B. Claise, "YANG module for 1504 yangcatalog.org", draft-clacla-netmod-model-catalog-03 1505 (work in progress), April 2018. 1507 [I-D.clacla-netmod-yang-model-update] 1508 Claise, B., Clarke, J., Lengyel, B., and K. D'Souza, "New 1509 YANG Module Update Procedure", draft-clacla-netmod-yang- 1510 model-update-06 (work in progress), July 2018. 1512 [I-D.claise-semver] 1513 Claise, B., Barnes, R., and J. Clarke, "Semantic 1514 Versioning and Structure for IETF Specifications", draft- 1515 claise-semver-02 (work in progress), January 2018. 1517 [I-D.ietf-netmod-yang-instance-file-format] 1518 Lengyel, B. and B. Claise, "YANG Instance Data File 1519 Format", draft-ietf-netmod-yang-instance-file-format-02 1520 (work in progress), February 2019. 1522 [I-D.openconfig-netmod-model-catalog] 1523 Shaikh, A., Shakir, R., and K. D'Souza, "Catalog and 1524 registry for YANG models", draft-openconfig-netmod-model- 1525 catalog-02 (work in progress), March 2017. 1527 [I-D.rwilton-netmod-yang-packages] 1528 Wilton, R., "YANG Packages", draft-rwilton-netmod-yang- 1529 packages-00 (work in progress), December 2018. 1531 [openconfigsemver] 1532 "Semantic Versioning for Openconfig Models", 1533 . 1535 [semver] "Semantic Versioning 2.0.0", . 1537 [yangcatalog] 1538 "YANG Catalog", . 1540 13.3. URIs 1542 [1] https://github.com/netmod-wg/yang-ver-dt/issues/14 1544 [2] https://github.com/netmod-wg/yang-ver-dt/issues/11 1546 [3] https://github.com/netmod-wg/yang-ver-dt/issues/13 1548 [4] https://github.com/netmod-wg/yang-ver-dt/issues/12 1550 [5] https://github.com/netmod-wg/yang-ver-dt/issues/10 1552 [6] https://github.com/netmod-wg/yang-ver-dt/issues/9 1554 [7] https://github.com/netmod-wg/yang-ver-dt/issues/8 1556 [8] https://github.com/netmod-wg/yang-ver-dt/issues/7 1558 [9] https://github.com/netmod-wg/yang-ver-dt/issues/6 1560 [10] https://github.com/netmod-wg/yang-ver-dt/issues/5 1562 [11] https://github.com/netmod-wg/yang-ver-dt/issues/4 1564 [12] https://github.com/netmod-wg/yang-ver-dt/issues/15 1566 [13] https://github.com/netmod-wg/yang-ver-dt/issues/2 1568 Appendix A. Appendix 1570 A.1. Open Issues 1572 Open issues are being tracked at . Currently open issues are: 1575 o Do we need a new version of YANG? #14 [1] 1577 o Add guidance text about warning NBC changes might break imports 1578 #11 [2] 1580 o Add a naming convention for versioned YANG file#13 [3] 1582 o Define editorial, bc, nbc impact of adding, changing, removing 1583 extension stmts#12 [4] 1585 o How to version modules in IETF drafts (after they have been 1586 published at 1.0.0 or later#10 [5] 1588 o The solution does not strictly support semver 2.0.0#9 [6] 1590 o Are whitespace changes allow between two module instances with the 1591 same version (or revision)?#8 [7] 1593 o Do we assume that a module has an implicit semver if none as been 1594 specified?#7 [8] 1596 o Is changing the ordering of nodes an NBC change?#6 [9] 1598 o Should version statement be at top level or under revision 1599 statement?#5 [10] 1601 o Figure out whether changing the imports constitute a BC or NBC 1602 change#4 [11] 1604 o Does BC or NBC depend on whether the node is config true/false?#15 1605 [12] 1607 o Status obsolete nodes#2 [13] 1609 A.2. Derived Semantic Version 1611 This temporary text is intended to be moved to a separate draft the 1612 describes the tool based approach for versioning YANG modules 1613 mentioned in Section 1.2. 1615 A.2.1. The Derived Semantic Version 1617 If an explicitly defined semantic version is not available in the 1618 YANG module, it is possible to algoritmically calculate a derived 1619 semantic version. This can be used for modules not containing a 1620 definitive semantic-version as defined in this document or as a 1621 starting value when specifying the definitive semantic-version. Be 1622 aware that this algorithm may sometimes incorrectly classify changes 1623 between the categories non-compatible, compatible or error- 1624 correction. 1626 A.2.2. Implementation Experience 1628 [yangcatalog] uses the pyang utility to calculate the derived- 1629 semantic-version for all of the modules contained within the catalog. 1630 [yangcatalog] contains many revisions of the same module in order to 1631 provide its derived-semantic-version for module consumers to know 1632 what has changed between revisions of the same module. 1634 Two distinct leafs in the YANG module 1635 [I-D.clacla-netmod-model-catalog] contain this semver notation: 1637 o the semantic-version leaf contains the value embedded within a 1638 YANG module (if it is available). 1640 o the derived-semantic-version leaf is established by examining the 1641 the YANG module themselves. As such derived-semantic-version only 1642 takes syntax into account as opposed to the meaning of various 1643 elements when it computes the semantic version. 1645 o The algorithm used to produce the derived-semantic-version is as 1646 follows: 1648 1. Order all modules of the same name by revision from oldest to 1649 newest. Include module revisions that are not available, but 1650 which are defined in the revision statements in one of the 1651 available module versions. 1653 2. If module A, revision N+1 has failed compilation, bump its 1654 derived semantic MAJOR version. For unavailable module 1655 versions assume non-backward compatible changes were done., 1656 thus bump its derived semantic MAJOR version. 1658 3. Else, run "pyang --check-update-from" on module A, revision N 1659 and revision N+1 to see if backward-incompatible changes 1660 exist. 1662 4. If backward-incompatible changes exist, bump module A, 1663 revision N+1's derived MAJOR semantic version. 1665 5. If no backward-incompatible changes exist, compare the pyang 1666 trees of module A, revision N and revision N+1. 1668 6. If there are structural differences (e.g., new nodes), bump 1669 module A, revision N+1's derived MINOR semantic version. 1671 7. If no structural differences exist, bump module A, revision 1672 N+1's derived PATCH semantic version. 1674 The pyang utility checks many of the points listed in section 11 of 1675 [RFC7950] for known module incompatibilities. While this approach is 1676 a good way to programmatically obtain a semantic version number, it 1677 does not address all cases whereby a major version number might need 1678 to be increased. For example, a node may have the same name and same 1679 type, but its meaning may change from one revision of a module to 1680 another. This represents a semantic change that breaks backward 1681 compatibility, but the above algorithm would not find it. Therefore, 1682 additional, sometimes manual, rigor must be done to ensure a proper 1683 version is chosen for a given module revision. 1685 Authors' Addresses 1687 Benoit Claise 1688 Cisco Systems, Inc. 1689 De Kleetlaan 6a b1 1690 1831 Diegem 1691 Belgium 1693 Phone: +32 2 704 5622 1694 Email: bclaise@cisco.com 1696 Joe Clarke 1697 Cisco Systems, Inc. 1698 7200-12 Kit Creek Rd 1699 Research Triangle Park, North Carolina 1700 United States of America 1702 Phone: +1-919-392-2867 1703 Email: jclarke@cisco.com 1704 Reshad Rahman 1705 Cisco Systems, Inc. 1707 Email: rrahman@cisco.com 1709 Robert Wilton (editor) 1710 Cisco Systems, Inc. 1712 Email: rwilton@cisco.com 1714 Balazs Lengyel 1715 Ericsson 1716 Magyar Tudosok Korutja 1717 1117 Budapest 1718 Hungary 1720 Phone: +36-70-330-7909 1721 Email: balazs.lengyel@ericsson.com 1723 Jason Sterne 1724 Nokia 1726 Email: jason.sterne@nokia.com 1728 Kevin D'Souza 1729 AT&T 1730 200 S. Laurel Ave 1731 Middletown, NJ 1732 United States of America 1734 Email: kd6913@att.com