idnits 2.17.1 draft-clacla-netmod-yang-model-update-03.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 97: '...name. Thus, a module name MUST NOT be...' RFC 2119 keyword, line 98: '... the "namespace" statement MUST NOT be...' RFC 2119 keyword, line 104: '... this MUST be achieved by a new ...' RFC 2119 keyword, line 315: '...finition is obsolete and SHOULD NOT be...' RFC 2119 keyword, line 477: '...ted schema nodes MUST still work as de...' (5 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (December 15, 2017) is 2317 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Outdated reference: A later version (-03) exists of draft-clacla-netmod-model-catalog-02 == Outdated reference: A later version (-02) exists of draft-claise-semver-01 -- Obsolete informational reference (is this intentional?): RFC 8049 (Obsoleted by RFC 8299) Summary: 1 error (**), 0 flaws (~~), 3 warnings (==), 2 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) Cisco Systems, Inc. 5 Intended status: Standards Track B. Lengyel 6 Expires: June 18, 2018 Ericsson 7 K. D'Souza 8 AT&T 9 December 15, 2017 11 New YANG Module Update Procedure 12 draft-clacla-netmod-yang-model-update-03 14 Abstract 16 This document specifies a new YANG module update procedure in case of 17 backward-incompatible changes, as an alternative proposal to the YANG 18 1.1 specifications. This document updates RFC 7950. 20 Status of This Memo 22 This Internet-Draft is submitted in full conformance with the 23 provisions of BCP 78 and BCP 79. 25 Internet-Drafts are working documents of the Internet Engineering 26 Task Force (IETF). Note that other groups may also distribute 27 working documents as Internet-Drafts. The list of current Internet- 28 Drafts is at http://datatracker.ietf.org/drafts/current/. 30 Internet-Drafts are draft documents valid for a maximum of six months 31 and may be updated, replaced, or obsoleted by other documents at any 32 time. It is inappropriate to use Internet-Drafts as reference 33 material or to cite them other than as "work in progress." 35 This Internet-Draft will expire on June 18, 2018. 37 Copyright Notice 39 Copyright (c) 2017 IETF Trust and the persons identified as the 40 document authors. All rights reserved. 42 This document is subject to BCP 78 and the IETF Trust's Legal 43 Provisions Relating to IETF Documents 44 (http://trustee.ietf.org/license-info) in effect on the date of 45 publication of this document. Please review these documents 46 carefully, as they describe your rights and restrictions with respect 47 to this document. Code Components extracted from this document must 48 include Simplified BSD License text as described in Section 4.e of 49 the Trust Legal Provisions and are provided without warranty as 50 described in the Simplified BSD License. 52 Table of Contents 54 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 55 2. The Problems . . . . . . . . . . . . . . . . . . . . . . . . 3 56 2.1. Slow Standardization . . . . . . . . . . . . . . . . . . 3 57 2.2. Some YANG Modules are Not Backward Compatible . . . . . . 3 58 2.3. Non-Backward Compatible Errors . . . . . . . . . . . . . 4 59 2.4. A Zoo of YANG Modules . . . . . . . . . . . . . . . . . . 4 60 2.5. YANG Modules Obsolete Relationship . . . . . . . . . . . 5 61 2.6. YANG Module Transition Strategy . . . . . . . . . . . . . 6 62 2.7. Need to Allow Non-Backward Compatible changes . . . . . . 6 63 2.8. Problematic Handling of Status Statement . . . . . . . . 7 64 2.9. No way to easily decide whether a change is Backward 65 Compatible . . . . . . . . . . . . . . . . . . . . . . . 7 66 2.10. Early Warning about Removal . . . . . . . . . . . . . . . 8 67 3. The Solution . . . . . . . . . . . . . . . . . . . . . . . . 8 68 3.1. SEMVER Semantic Versioning . . . . . . . . . . . . . . . 9 69 3.2. Updates to YANG 1.1 status statement . . . . . . . . . . 11 70 3.3. Updating the YANG 1.1 Module Update rules . . . . . . . . 11 71 3.4. The Derived Semantic Version . . . . . . . . . . . . . . 11 72 3.5. Import by Semantic Version . . . . . . . . . . . . . . . 12 73 4. Open Issues . . . . . . . . . . . . . . . . . . . . . . . . . 13 74 5. Semantic Version Extension YANG Module . . . . . . . . . . . 14 75 6. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 16 76 7. Security Considerations . . . . . . . . . . . . . . . . . . . 16 77 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 17 78 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 17 79 9.1. Normative References . . . . . . . . . . . . . . . . . . 17 80 9.2. Informative References . . . . . . . . . . . . . . . . . 17 81 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 18 83 1. Introduction 85 The YANG data modeling language [RFC7950] specifies strict rules for 86 updating YANG modules (see section 11 "Updating a Module"). Citing a 87 few of the relevant rules: 89 1. "As experience is gained with a module, it may be desirable to 90 revise that module. However, changes to published modules are 91 not allowed if they have any potential to cause interoperability 92 problems between a client using an original specification and a 93 server using an updated specification." 95 2. "Note that definitions contained in a module are available to be 96 imported by any other module and are referenced in "import" 97 statements via the module name. Thus, a module name MUST NOT be 98 changed. Furthermore, the "namespace" statement MUST NOT be 99 changed, since all XML elements are qualified by the namespace." 101 3. "Otherwise, if the semantics of any previous definition are 102 changed (i.e., if a non-editorial change is made to any 103 definition other than those specifically allowed above), then 104 this MUST be achieved by a new definition with a new identifier." 106 4. "deprecated indicates an obsolete definition, but it permits new/ 107 continued implementation in order to foster interoperability with 108 older/existing implementations." 110 What are the consequences? 112 1. Ideally, the YANG module names should not be changed due the 113 importance of not changing the automation code in case of import 114 statements or service composition at the orchestration layer. 116 2. When the same YANG module name is kept, its new revision must be 117 updated in a backward-compatible way. 119 3. While most of the non-backward compatible changes are prohibited, 120 a client still does not know if a changed module is backward 121 compatible, as a server may remove parts of a module after 122 marking it deprecated or obsolete. 124 2. The Problems 126 This section lists a series of problems, hopefully listed in a 127 logical order, which leads to the solution in the next section. 129 2.1. Slow Standardization 131 The conclusions drawn in the introduction lead to the logical 132 conclusion that the standardized YANG modules have to be perfect on 133 day one (at least the structure), which in turn might explain why all 134 the IETF YANG modules take so long to standardize. Shooting for 135 perfection (at least in structure) is obviously a noble goal, but if 136 the perfect standard comes too late, it doesn't help the industry. 138 2.2. Some YANG Modules are Not Backward Compatible 140 As we learn from our mistakes, we're going to face more and more 141 backward-incompatible YANG modules. An example is the YANG data 142 model for L3VPN service delivery [RFC8049], which, based on 143 implementation experience, must be updated in a backward-incompatible 144 way with draft-wu-l3sm-rfc8049bis [I-D.wu-l3sm-rfc8049bis]. 146 While Standards Development Organization (SDO) YANG modules are 147 obviously better for the industry, we must recognize that many YANG 148 modules are actually generated YANG modules (for example, from 149 internal databases), also known as native YANG modules, or vendor 150 modules [RFC8199]. From time to time, the new YANG modules are not 151 backward-compatible. 153 In such cases, it would be better to indicate how backward-compatible 154 a given YANG module actually is. 156 2.3. Non-Backward Compatible Errors 158 Sometimes small errors force us to make non-backward compatible 159 updates. As an example imagine that we have a string with a complex 160 pattern (e.g., an IP address). Let's assume the initial pattern 161 incorrectly allows IP addresses to start with 355. In the next 162 version this is corrected to disallow addresses starting with 355. 163 Formally this is an non-backward compatible change as the value space 164 of the string is decreased. In reality an IP address and the 165 implementation behind it was never capable of handling an address 166 starting with 355. So practically this is a backward compatible 167 change, just like a correction of the description statement. Still 168 current YANG rules would force a module name change. 170 2.4. A Zoo of YANG Modules 172 Even if we focus on the IETF, we have to observe that many SDOs, 173 opensource fora, and vendors develop YANG modules. This should be 174 considered a success for an IETF developed technology. However, the 175 operators are faced with this problem: how to select the YANG modules 176 to take into account for their service developments. 178 The site (and the YANG catalog that it 179 provides: YANG module for yangcatalog.org, 180 [I-D.clacla-netmod-model-catalog]) is an attempt to become a 181 reference for all YANG modules available in the industry, for both 182 YANG developers to search on what exists already) and for operators 183 (to discover the more mature YANG models to automate services). This 184 YANG catalog should not only contain pointers to the YANG modules 185 themselves, but also contain metadata related to those YANG modules: 186 What is the module type (service model or not?); what is the maturity 187 level? (e.g., for the IETF: is this an RFC, a working group document 188 or an individual draft?); is this module implemented?; who is the 189 contact?; is there open-source code available? And we expect many 190 more in the future. The industry has begun to understand that the 191 metadata related to YANG models become equally important as the YANG 192 models themselves. 194 The yangcatalog.org instantiation of the catalog provides a means for 195 module authors and vendors implementing modules to upload their 196 metadata, which is then searchable via an API, as well as using a 197 variety of web-based tools. The instructions for contributing and 198 searching for metadata can be found at . 201 The issue is actually the number of YANG modules the operators are 202 offered. At the time of writing this document, the number of unique 203 YANG modules in the catalog is exactly 2596 (and that number keeps 204 growing), while the IETF has standardized or is busy standardizing a 205 small subset of those. Therefore, it's important to distinguish the 206 relevant YANG modules with the pack and to understand the 207 relationship between the YANG modules. 209 2.5. YANG Modules Obsolete Relationship 211 So the operators use the yangcatalog.org to discover which YANG 212 modules they can use NOW. They base their selection not only on the 213 YANG module content, but also on the related metadata. When faced 214 with the zoo of the YANG modules, it's difficult to understand the 215 relationship between YANG modules. As an example: how could an 216 operator discover that YANG-MODULE-B obsoletes YANG-MODULE-A? 217 Indeed, both have different YANG module names. The only available 218 information is an "obsolete" tag in the published RFC containing 219 YANG-MODULE-B: this tag would point to YANG-MODULE-A. In the world 220 of automation, going through a published RFC as a level of 221 indirection to understand the YANG module obsolete relationship is a 222 non-starter. Food for thought: the IETF should stop thinking that 223 the metric for success is an RFC number, as opposed to the contained 224 YANG module(s). 226 We need an automatic way to discover that a YANG-MODULE-B obsoletes 227 YANG-MODULE-A, so that YANG-MODULE-A should not be given any 228 attention. 230 The following example is not an automatic way. 232 description 233 "This YANG module defines a generic service configuration 234 model for Layer 3 VPNs. This model is common across all 235 vendor implementations. This obsoletes the RFC8049 YANG 236 module, ietf-l3vpn-svc@2017-01-2"; 237 revision 2017-09-14 { 238 description 239 "First revision of RFC8049."; 240 reference 241 "RFC xxxx: YANG Data Model for L3VPN Service Delivery"; 243 Along the same lines, while going through an out-of-band tool such as 244 the yangcatalog.org in order to discover the obsolete relationship is 245 a possible automatic way, it is not ideal. 247 2.6. YANG Module Transition Strategy 249 Let's assume for a moment that we change the YANG module, with the 250 specific example of ietf-routing, which some propose to update to 251 ietf-routing-2. 253 Here are all the ietf-routing dependent YANG modules (those modules 254 that depend on ietf-routing) . So many 257 YANG modules. 259 Let's look at the difference for ietf-routing-2: 260 . 264 Changing the module name from ietf-routing to ietf-routing-2 implies 265 that the we have to warn all draft authors of ietf-routing YANG 266 dependent modules. First, to make sure they are aware of ietf- 267 routing-2 (publishing a RFC8022bis mentioning in the module 268 description that this module is not compatible with the NMDA 269 architecture, and providing a pointer to ietf-routing-2 ... is not an 270 automatic way... so barely useful). And second, to ask them to 271 change their import (or service composition) to ietf-routing-2. 272 Hopefully, in the ietf-routing case, most dependent YANG modules are 273 part of the IETF, so the communication is a manageable. For the 274 already existing dependent vendor modules the problem is worse. 276 Changing the ietf-interfaces YANG module name would be a different 277 challenge, as it's used throughout the industry: 278 282 2.7. Need to Allow Non-Backward Compatible changes 284 As described in the previous sections, there is a need to allow non- 285 backward compatible changes without changing a module's name. This 286 would avoid many of the above problems. In most cases even after 287 non-backward compatible updates a module should keep its name. 288 However, for really major changes renaming the module is still the 289 proper way to go: 291 when splitting a module into two separate modules 293 when removing 80% of a module's schema 295 when a standard module is moved from one organization to another 296 (e.g., from ietf to ieee) 298 when a company's name is changed and new versions of the module 299 are renamed to reflect that 301 Allowing non-backward compatible changes to happen without a module 302 name change will decrease the number of separate modules to handle 303 and will make it a trivial task to track these non-backward 304 compatible changes. 306 2.8. Problematic Handling of Status Statement 308 The current definition of deprecated and obsolete in [RFC7950] (as 309 quoted below) is problematic and should be corrected. 311 o "deprecated" indicates an obsolete definition, but it permits new/ 312 continued implementation in order to foster interoperability with 313 older/existing implementations. 315 o "obsolete" means that the definition is obsolete and SHOULD NOT be 316 implemented and/or can be removed from implementations. 318 YANG is considered an interface contract between the server and the 319 client. The current definitions of deprecated and obsolete mean that 320 a schema node that is either deprecated or obsolete may or may not be 321 implemented. The client has no way to find out which is the case 322 except for by trying to write or read data at the leaf in question. 323 This probing would need to be done for each separate data-node, which 324 not a trivial thing to do. This "may or may not" is unacceptable in 325 a contract. In effect, this works as if there would be an if-feature 326 statement on each deprecated schema node where the server does not 327 advertise whether the feature is supported or not. Why is it not 328 advertised? 330 2.9. No way to easily decide whether a change is Backward Compatible 332 A management system, SDN controller or any other user of a module 333 should be capable of easily determining the compatibility between two 334 module versions. Higher level logic for a network function, 335 something that can not be implemented in a purely model driven way, 336 is always dependent on a specific version of the module. If the 337 client finds that the module has been updated on the network node, it 338 has to decide if it tries to handle it as it handled the previous 339 version of the model or if it just stops, to avoid problems. To make 340 this decision the client needs to know if the module was updated in a 341 backward compatible way or not. 343 This is not possible to decide today because of the following: 345 o It is possible to change the semantic behavior of a data node, 346 action or rpc while the YANG definition does not change (with the 347 possible exception of the description statement). In such a case 348 it is impossible to determine whether the change is backward 349 compatible just by looking at the YANG statements. Its only the 350 human model designer that can decide. 352 o Problems with the status statement, Section 2.8 354 o Modelers might decide to violate YANG 1.1 update rules for some of 355 the reasons above 357 Finding status changes or violations of update rules need a line by 358 line comparision of the old and new modules, no easy task. 360 2.10. Early Warning about Removal 362 If a schema part is considered old/bad we need to be able to give 363 advance warning that it will be removed. As this is an advance 364 warning the part shall still be present and usable in the current 365 revision; however, it will be removed in one of the next revisions. 366 We need the advance warning to allow users of the module time enough 367 to plan/execute migration away from the deprecated functionality. 368 Often deprecation will be accompanied by information whether the 369 functionality will just disappear or that there is an alternative, 370 possibly more advanced solution that should be used. 372 Vendors use such warnings often, but the NMDA related redesign of 373 IETF modules is also an example where it would be useful. (As 374 another example see the usage of deprecated in the Java programing 375 language.) The current definition of the deprecated status does not 376 serve this purpose as described in Section 2.8. The definition of 377 "deprecated" in the status statement shall be changed to address this 378 issue. 380 3. The Solution 382 The solution is composed of four parts, a semantic versioning YANG 383 extension, updates to the YANG 1.1. status statement and module 384 update rules and the import by version statement. An optional 385 additional check, validating the semantic versioning from a syntactic 386 point of view, can either assist in determining the correct semantic 387 versioning values, or can help in determining the values for YANG 388 modules that don't support this extension. 390 3.1. SEMVER Semantic Versioning 392 The semantic versioning solution proposed here has already been 393 proposed in [I-D.openconfig-netmod-model-catalog] (included here with 394 the authors permission)which itself is based on [openconfigsemver]. 395 The goal is to indicate the YANG module backwards (in)compatibility, 396 following semver.org semantic versioning [semver]: 398 "The SEMVER version number for the module is introduced. This is 399 expressed as a semantic version number of the form: x.y.z 401 o x is the MAJOR version. It is incremented when the new version of 402 the specification is incompatible with previous versions. 404 o y is the MINOR version. It is incremented when new functionality 405 is added in a manner that is backward-compatible with previous 406 versions. 408 o z is the PATCH level. It is incremented when bug fixes are made 409 in a backward-compatible manner. 411 Along these lines, we propose the following YANG 1.1 extension for a 412 more generic semantic version. The formal definition is found at the 413 end of this document. 415 extension module-version { 416 argument "semver" { 417 yin-element false; 418 } 419 } 421 The extension would typically be used this way: 423 module yang-module-name { 425 namespace "name-space"; 426 prefix "prefix-name"; 428 import ietf-semver { prefix "semver"; } 430 description 431 "to be completed"; 433 revision 2017-10-30 { 434 description 435 "Change the module structure"; 436 semver:module-version "2.0.0"; 437 } 439 revision 2017-07-30 { 440 description 441 "Added new feature XXX"; 442 semver:module-version "1.2.0";"; 443 } 445 revision 2017-04-03 { 446 description 447 "Update copyright notice."; 448 semver:module-version "1.0.1";; 449 } 451 revision 2017-04-03 { 452 description 453 "First release version."; 454 semver:module-version "1.0.0";; 455 } 457 revision 2017-01-26 { 458 description 459 "Initial module for inet types"; 460 semver:module-version "0.1.0";; 461 } 463 //YANG module definition starts here 465 See also "Semantic Versioning and Structure for IETF Specifications" 466 [I-D.claise-semver] for a mechanism to combine the semantic 467 versioning, the github tools, and a potential change to the IETF 468 process. 470 3.2. Updates to YANG 1.1 status statement 472 RFC 7950 section 11, must be updated to change the definition of 473 deprecated and obsolete. In both cases the client must be able to 474 determine whether the relevant parts are implemented or not without 475 probing. The following definition is proposed: 477 o Deprecated schema nodes MUST still work as defined. The 478 deprecated status serves only as a a warning that the schema node 479 will be removed or obsoleted in the future. 481 o Obsolete schema nodes MUST be removed from the implementation. 482 Requests concerning these schema nodes MUST be rejected with: 484 * error-tag: operation-failed 486 * error-app-tag: obsolete element 488 If there is a need to allow the server to decide whether a 489 deprecated/obsolete schema part is implemented YANG already has a 490 facility for that: the feature statement. Use it! 492 3.3. Updating the YANG 1.1 Module Update rules 494 RFC 7950 section 11, must be updated to express: 496 "As experience is gained with a module, it may be desirable to revise 497 that module. Changes to published modules are allowed, even if they 498 have some potential to cause interoperability problems, if the 499 module-version YANG extension is used in the revision statement to 500 clearly indicate the nature of the change." 502 3.4. The Derived Semantic Version 504 The YANG catalog contains not only the most up-to-date YANG module 505 revision of a given module, but keeps all previous revisions as well. 506 With APIs in mind, it's important to understand whether different 507 YANG module revisions are backward compatible (this is specifically 508 imported for native YANG modules, i.e. the ones where generated-from 509 = native), even for the YANG modules that don't support the YANG 510 extension specified in this document. 512 Two distinct leaves in the YANG module 513 [I-D.clacla-netmod-model-catalog] contain this semver notation: 515 o the semantic-version leaf contains the value embedded within a 516 YANG module (if it is available). 518 o the derived-semantic-version leaf is established by examining the 519 the YANG module themselves. As such derived-semantic-version only 520 takes syntax into account as opposed to the meaning of various 521 elements when it computes the semantic version. 523 o The algorithm used to produce the derived-semantic-version is as 524 follows: 526 1. Order all modules of the same name by revision from oldest to 527 newest. Include module revisions that are not available, but 528 which are defined in the revision statements in one of the 529 available module versions. 531 2. If module A, revision N+1 has failed compilation, bump its 532 derived semantic MAJOR version. For unavailable module 533 versions assume non-backward compatible changes were done., 534 thus bump its derived semantic MAJOR version. 536 3. Else, run "pyang --check-update-from" on module A, revision N 537 and revision N+1 to see if backward-incompatible changes 538 exist. 540 4. If backward-incompatible changes exist, bump module A, 541 revision N+1's derived MAJOR semantic version. 543 5. If no backward-incompatible changes exist, compare the pyang 544 trees of module A, revision N and revision N+1. 546 6. If there are structural differences (e.g., new nodes), bump 547 module A, revision N+1's derived MINOR semantic version. 549 7. If no structural differences exist, bump module A, revision 550 N+1's derived PATCH semantic version. 552 Note that the absolute numbers in the semantic-version and derived- 553 semantic-version are actually meaningless by themselves. That is, 554 one must compare two different semver values for a given module to 555 understand the compatibility between them. 557 3.5. Import by Semantic Version 559 If a module is imported by another one, it is usually not specified 560 which version of the imported module should be used. However not all 561 versions may be acceptable. Today YANG 1.1 allows us to specify the 562 revision date of the imported module, but that is too specific, as 563 even a small spelling correction of the imported module results in a 564 change to its revision date, thus making the module revision 565 ineligible for import. 567 Using semantic versioning to indicate the acceptable imported module 568 versions is much more flexible. 570 o We might indicate that any compatible module-version after e.g. 571 3.1.0 is acceptable 573 o We might indicate that any compatible module-version of the 3.1.0, 574 4.0.0 or 5.0.0 major versions is acceptable. Later depending on 575 updates in the 6.0.0 series we might allow those revisions also to 576 be imported. As an non-backward compatible change in the 6.0.0 577 line might just change a small part of the imported module, the 578 non-backward compatible changes may or may not affect the 579 importer. 581 The module-version statement SHOULD be a substatement of the import 582 statement. An import statement MUST NOT contain both a module- 583 version and a revision substatement. The use of the revision 584 substatement of import should be discouraged/deprecated. 586 4. Open Issues 588 There are a number of open issues to be disccused. These include the 589 following: 591 o Do we need include-by-Semver? 593 o Should IETF/IANA officially generate derived semantic versions for 594 their own modules? As they are the owner of the modules it should 595 be their responsibility, but how to document it? 597 o There are cases where the module's name should be changed but we 598 still want to formally document the connection between the old and 599 the new module names. For these cases shall we introduce a new 600 YANG extension statement 602 o "replaces-module ietf-vlan;" ? 604 o We could consider a new naming convention for module files. 605 Today, module files are named using a module@revision.yang 606 notation. We could consider a module%semver.yang variant. Re- 607 using the '@' for version is not ideal, so another separator 608 character should be used. In this manner, both version and 609 revision could be used. 611 o Taking another page from Openconfig, the notion of a module bundle 612 could be considered. That is, there may need to be a way to 613 enumerate modules that are part of a bundle and are known to 614 interoperate. This may not be as critical if a rich import-by- 615 version is defined. 616 While the issue is interesting, it will be not be handled in this 617 document. 619 o Similarly, the concept of a feature bundle should be considered. 620 Typically, operators combine and test YANG modules to build value- 621 add services. These bundles form releases for specific features 622 or services, and it is critical to ensure as the modules evolve, 623 the bundles can coherently evolve with them. 624 While the issue is interesting, it will be not be handled in this 625 document. 627 o When we'll start using this new procedure for a new YANG module 628 revision, will we have to update all the dependent YANG modules to 629 start using this new procedure, along with the new import 630 statement? Is this a moot point, as a new YANG module name would 631 suffer from the same symptoms? 632 We see no need for updating other dependent modules. It is a good 633 idea to update them, as they will benefit from using SEMVER, 634 however there is no specific need to update them. 636 5. Semantic Version Extension YANG Module 638 The extension described in this module is defined in the YANG module 639 below. 641 file "ietf-semver@2017-12-15.yang" 642 module ietf-semver { 643 yang-version 1.1; 644 namespace "urn:ietf:params:xml:ns:yang:ietf-semver"; 645 prefix semver; 647 organization 648 "IETF NETMOD (Network Modeling) Working Group"; 649 contact 650 "WG Web: 651 WG List: 653 Author: Benoit Claise 654 656 Author: Joe Clarke 657 659 Author: Kevin D'Souza 660 662 Author: Balazs Lengyel 663 "; 664 description 665 "This module contains a definition for a YANG 1.1 extension to 666 express the semantic version of YANG modules."; 668 revision 2017-12-15 { 669 description 670 "Initial revision."; 671 reference "draft-clacla-netmod-yang-model-update: 672 New YANG Module Update Procedure"; 673 semver:module-semver 0.1.1; 674 } 676 extension module-version { 677 argument semver; 678 description 679 "The version number for the module revision it is used in. 680 This is expressed as a semantic version string in the form: 681 x.y.z 682 where: 683 * x corresponds to the major version, 684 * y corresponds to a minor version, 685 * z corresponds to a patch version. 687 A major version number of 0 indicates that this model is still 688 in development, and is potentially subject to change. 690 Following a release of major version 1, all modules will 691 increment major revision number where backwards incompatible 692 changes to the model are made. 694 The minor version is changed when features are added to the 695 model that do not impact current clients use of the model. 696 When major version is stepped, the minor version is reset to 0. 698 The patch-level version is incremented when non-feature changes 699 (such as bugfixes or clarifications to human-readable 700 descriptions that do not impact model functionality) are made 701 that maintain backwards compatibility. 702 When major or minor version is stepped, the patch-level is 703 reset to 0. 705 The version number is stored in the module meta-data. 707 By comparing the module-version between two revisions of a 708 given module, one can know if revision N+1 is backwards 709 compatible or not relative to revision N, as well as 710 whether or not new features have been added to revision N+1. 712 If a module contains this extension it indicates that for this 713 module the updated status and update rules as this described in 714 RFC XXXX are used. 716 The statement MUST only be a substatement of the revision, 717 import or include statements. 718 Zero or One module-version statement is allowed per parent 719 statement. NO substatements are allowed. 720 "; 722 reference "http://semver.org/ : Semantic Versioning 2.0.0"; 723 } 725 augment /yanglib:modules-state/yanglib:module { 726 leaf module-version { 727 type string { 728 pattern "[0-9]+.[0-9]+.[0-9]+"; 729 } 730 } 731 } 733 augment /yanglib:modules-state/yanglib:module/yanglib:submodule { 734 leaf submodule-version { 735 type string { 736 pattern "[0-9]+.[0-9]+.[0-9]+"; 737 } 738 } 739 } 741 } 742 744 6. Contributors 746 o Anees Shaikh, Google 748 o Rob Shakir, Google 750 7. Security Considerations 752 The document does not define any new protocol or data model. There 753 are no security impacts. 755 8. IANA Considerations 757 No IANA action is requested. 759 9. References 761 9.1. Normative References 763 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 764 RFC 7950, DOI 10.17487/RFC7950, August 2016, 765 . 767 9.2. Informative References 769 [I-D.clacla-netmod-model-catalog] 770 Clarke, J. and B. Claise, "YANG module for 771 yangcatalog.org", draft-clacla-netmod-model-catalog-02 772 (work in progress), October 2017. 774 [I-D.claise-semver] 775 Claise, B., Barnes, R., and J. Clarke, "Semantic 776 Versioning and Structure for IETF Specifications", draft- 777 claise-semver-01 (work in progress), July 2017. 779 [I-D.openconfig-netmod-model-catalog] 780 Shaikh, A., Shakir, R., and K. D'Souza, "Catalog and 781 registry for YANG models", draft-openconfig-netmod-model- 782 catalog-02 (work in progress), March 2017. 784 [I-D.wu-l3sm-rfc8049bis] 785 Wu, Q., Litkowski, S., Tomotaki, L., and K. Ogaki, "YANG 786 Data Model for L3VPN Service Delivery", draft-wu-l3sm- 787 rfc8049bis-11 (work in progress), December 2017. 789 [openconfigsemver] 790 "Semantic Versioning for Openconfig Models", 791 . 793 [RFC8049] Litkowski, S., Tomotaki, L., and K. Ogaki, "YANG Data 794 Model for L3VPN Service Delivery", RFC 8049, 795 DOI 10.17487/RFC8049, February 2017, . 798 [RFC8199] Bogdanovic, D., Claise, B., and C. Moberg, "YANG Module 799 Classification", RFC 8199, DOI 10.17487/RFC8199, July 800 2017, . 802 [semver] "Semantic Versioning 2.0.0", . 804 Authors' Addresses 806 Benoit Claise 807 Cisco Systems, Inc. 808 De Kleetlaan 6a b1 809 1831 Diegem 810 Belgium 812 Phone: +32 2 704 5622 813 Email: bclaise@cisco.com 815 Joe Clarke 816 Cisco Systems, Inc. 817 7200-12 Kit Creek Rd 818 Research Triangle Park, North Carolina 819 United States of America 821 Phone: +1-919-392-2867 822 Email: jclarke@cisco.com 824 Balazs Lengyel 825 Ericsson 826 Magyar Tudosok Korutja 827 1117 Budapest 828 Hungary 830 Phone: +36-70-330-7909 831 Email: balazs.lengyel@ericsson.com 833 Kevin D'Souza 834 AT&T 835 200 S. Laurel Ave 836 Middletown, NJ 837 United States of America 839 Email: kd6913@att.com