idnits 2.17.1 draft-ietf-netmod-yang-semver-05.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 : ---------------------------------------------------------------------------- ** There are 7 instances of too long lines in the document, the longest one being 24 characters in excess of 72. -- The draft header indicates that this document updates RFC8407, but the abstract doesn't seem to mention this, which it should. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (8 November 2021) is 893 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) == Missing Reference: 'RFCXXXX' is mentioned on line 905, but not defined == Outdated reference: A later version (-11) exists of draft-ietf-netmod-yang-module-versioning-04 == Outdated reference: A later version (-03) exists of draft-ietf-netmod-yang-packages-02 == Outdated reference: A later version (-02) exists of draft-ietf-netmod-yang-schema-comparison-01 Summary: 1 error (**), 0 flaws (~~), 5 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group J. Clarke, Ed. 3 Internet-Draft R. Wilton, Ed. 4 Updates: 8407 (if approved) Cisco Systems, Inc. 5 Intended status: Standards Track R. Rahman 6 Expires: 12 May 2022 7 B. Lengyel 8 Ericsson 9 J. Sterne 10 Nokia 11 B. Claise 12 Huawei 13 8 November 2021 15 YANG Semantic Versioning 16 draft-ietf-netmod-yang-semver-05 18 Abstract 20 This document specifies a scheme and guidelines for applying an 21 extended set of semantic versioning rules to revisions of YANG 22 artifacts (e.g., modules and packages). Additionally, this document 23 defines an RFCAAAA-compliant revision-label-scheme for this YANG 24 semantic versioning scheme. 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 12 May 2022. 43 Copyright Notice 45 Copyright (c) 2021 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 (https://trustee.ietf.org/ 50 license-info) in effect on the date of publication of this document. 51 Please review these documents carefully, as they describe your rights 52 and restrictions with respect to this document. Code Components 53 extracted from this document must include Simplified BSD License text 54 as described in Section 4.e of the Trust Legal Provisions and are 55 provided without warranty as described in the Simplified BSD License. 57 Table of Contents 59 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 60 2. Terminology and Conventions . . . . . . . . . . . . . . . . . 3 61 3. YANG Semantic Versioning . . . . . . . . . . . . . . . . . . 3 62 3.1. YANG Semver Pattern . . . . . . . . . . . . . . . . . . . 4 63 3.2. Semantic Versioning Scheme for YANG Artifacts . . . . . . 4 64 3.2.1. YANG Semver with submodules . . . . . . . . . . . . . 7 65 3.2.2. Examples for YANG semantic versions . . . . . . . . . 7 66 3.3. YANG Semantic Version Update Rules . . . . . . . . . . . 9 67 3.4. Examples of the YANG Semver Label . . . . . . . . . . . . 11 68 3.4.1. Example Module Using YANG Semver . . . . . . . . . . 11 69 3.4.2. Example of Package Using YANG Semver . . . . . . . . 13 70 4. Import Module by Semantic Version . . . . . . . . . . . . . . 13 71 5. Guidelines for Using Semver During Module Development . . . . 14 72 5.1. Pre-release Version Precedence . . . . . . . . . . . . . 15 73 5.2. YANG Semver in IETF Modules . . . . . . . . . . . . . . . 16 74 6. YANG Module . . . . . . . . . . . . . . . . . . . . . . . . . 16 75 7. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 19 76 8. Security Considerations . . . . . . . . . . . . . . . . . . . 19 77 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 19 78 9.1. YANG Module Registrations . . . . . . . . . . . . . . . . 20 79 9.2. Guidance for YANG Semver in IANA maintained YANG modules 80 and submodules . . . . . . . . . . . . . . . . . . . . . 20 81 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 21 82 10.1. Normative References . . . . . . . . . . . . . . . . . . 21 83 10.2. Informative References . . . . . . . . . . . . . . . . . 22 84 Appendix A. Example IETF Module Development . . . . . . . . . . 23 85 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 24 87 1. Introduction 89 [I-D.ietf-netmod-yang-module-versioning] puts forth a number of 90 concepts relating to modified rules for updating modules and 91 submodules, a means to signal when a new revision of a module or 92 submodule has non-backwards-compatible (NBC) changes compared to its 93 previous revision, and a scheme that uses the revision history as a 94 lineage for determining from where a specific revision of a YANG 95 module or submodule is derived. Additionally, section 3.4 of 97 [I-D.ietf-netmod-yang-module-versioning] defines a revision-label 98 which can be used as an alias to provide additional context or as a 99 meaningful label to refer to a specific revision. 101 This document defines a revision-label scheme that uses extended 102 [semver] rules for YANG artifacts (i.e., YANG modules, YANG 103 submodules, and YANG packages [I-D.ietf-netmod-yang-packages] ) as 104 well as the revision label definition for using this scheme. The 105 goal being to add a human readable revision label that provides 106 compatibility information for the YANG artifact without needing to 107 compare or parse its body. The label and rules defined herein 108 represent the RECOMMENDED revision label scheme for IETF YANG 109 artifacts. 111 Note that a specific revision of the Semver 2.0.0 specification is 112 referenced here (from June 19, 2020) to provide an immutable version. 113 This is because the 2.0.0 version of the specification has changed 114 over time without any change to the semantic version itself. In some 115 cases the text has changed in non-backwards-compatible ways. 117 2. Terminology and Conventions 119 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 120 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 121 "OPTIONAL" in this document are to be interpreted as described in BCP 122 14 [RFC2119] [RFC8174] when, and only when, they appear in all 123 capitals, as shown here. 125 Additionally, this document uses the following terminology: 127 * YANG artifact: YANG modules, YANG submodules, and YANG packages 128 [I-D.ietf-netmod-yang-packages] are examples of YANG artifacts for 129 the purposes of this document. 131 * YANG Semver: A revision-label identifier that is consistent with 132 the extended set of semantic versioning rules, based on [semver] , 133 defined within this document. 135 3. YANG Semantic Versioning 137 This section defines YANG Semantic Versioning, explains how it is 138 used with YANG artifacts, and describes the rules associated with 139 changing an artifact's semantic version when its contents are 140 updated. 142 3.1. YANG Semver Pattern 144 YANG artifacts that employ semantic versioning as defined in this 145 document MUST use a version string (e.g., in revision-label or as a 146 package version) that corresponds to the following pattern: 147 X.Y.Z_COMPAT. Where: 149 * X, Y and Z are mandatory non-negative integers that are each less 150 than or equal to 2147483647 (i.e., the maximum signed 32-bit 151 integer value) and MUST NOT contain leading zeroes, 153 * The '.' is a literal period (ASCII character 0x2e), 155 * The '_' is an optional single literal underscore (ASCII character 156 0x5f) and MUST only be present if the following COMPAT element is 157 included, 159 * COMPAT, if specified, MUST be either the literal string 160 "compatible" or the literal string "non_compatible". 162 Additionally, [semver] defines two specific types of metadata that 163 may be appended to a semantic version string. Pre-release metadata 164 MAY be appended to a semver string after a trailing '-' character. 165 Build metadata MAY be appended after a trailing '+' character. If 166 both pre-release and build metadata are present, then build metadata 167 MUST follow pre-release metadata. While build metadata MUST be 168 ignored when comparing YANG semantic versions, pre-release metadata 169 MUST be used during module and submodule development as specified in 170 Section 5 . Both pre-release and build metadata are allowed in order 171 to support all the [semver] rules. Thus, a version lineage that 172 follows strict [semver] rules is allowed for a YANG artifact. 174 To signal the use of this versioning scheme, modules and submodules 175 MUST set the revision-label-scheme extension, as defined in 176 [I-D.ietf-netmod-yang-module-versioning] , to the identity "yang- 177 semver". That identity value is defined in the ietf-yang-semver 178 module below. 180 Additionally, this ietf-yang-semver module defines a typedef that 181 formally specifies the syntax of the YANG Semver. 183 3.2. Semantic Versioning Scheme for YANG Artifacts 185 This document defines the YANG semantic versioning scheme that is 186 used for YANG artifacts that employ the YANG Semver label. The 187 versioning scheme has the following properties: 189 * The YANG semantic versioning scheme is extended from version 2.0.0 190 of the semantic versioning scheme defined at semver.org [semver] 191 to cover the additional requirements for the management of YANG 192 artifact lifecyles that cannot be addressed using the semver.org 193 2.0.0 versioning scheme alone. 195 * Unlike the [semver] versioning scheme, the YANG semantic 196 versioning scheme supports updates to older versions of YANG 197 artifacts, to allow for bug fixes and enhancements to artifact 198 versions that are not the latest. However, it does not provide 199 for the unlimited branching and updating of older revisions which 200 are documented by the general rules in 201 [I-D.ietf-netmod-yang-module-versioning] . 203 * YANG artifacts that follow the [semver] versioning scheme are 204 fully compatible with implementations that understand the YANG 205 semantic versioning scheme defined in this document. 207 * If updates are always restricted to the latest revision of the 208 artifact only, then the version numbers used by the YANG semantic 209 versioning scheme are exactly the same as those defined by the 210 [semver] versioning scheme. 212 Every YANG module and submodule versioned using the YANG semantic 213 versioning scheme specifies the module's or submodule's semantic 214 version as the argument to the 'rev:revision-label' statement. 216 Because the rules put forth in 217 [I-D.ietf-netmod-yang-module-versioning] are designed to work well 218 with existing versions of YANG and allow for artifact authors to 219 migrate to this scheme, it is not expected that all revisions of a 220 given YANG artifact will have a semantic version label. For example, 221 the first revision of a module or submodule may have been produced 222 before this scheme was available. 224 YANG packages that make use of this YANG Semver will reflect that in 225 the package metadata. 227 As stated above, the YANG semantic version is expressed as a string 228 of the form: 'X.Y.Z_COMPAT'; where X, Y, and Z each represent non- 229 negative integers less than or equal to 2147483647 without leading 230 zeroes, and _COMPAT represents an optional suffix of either 231 "_compatible" or "_non_compatible". 233 * 'X' is the MAJOR version. Changes in the MAJOR version number 234 indicate changes that are non-backwards-compatible to versions 235 with a lower MAJOR version number. 237 * 'Y' is the MINOR version. Changes in the MINOR version number 238 indicate changes that are backwards-compatible to versions with 239 the same MAJOR version number, but a lower MINOR version number 240 and no PATCH "_compatible" or "_non_compatible" modifier. 242 * 'Z_COMPAT' is the PATCH version and modifier. Changes in the 243 PATCH version number can indicate editorial, backwards-compatible, 244 or non-backwards-compatible changes relative to versions with the 245 same MAJOR and MINOR version numbers, but lower PATCH version 246 number, depending on what form modifier "_COMPAT" takes: 248 - If the modifier string is absent, the change represents an 249 editorial change. An editorial change is defined to be a 250 change in the YANG artifact's content that does not affect the 251 semantic meaning or functionality provided by the artifact in 252 any way. Some examples include correcting a spelling mistake 253 in the description of a leaf within a YANG module or submodule, 254 non-significant whitespace changes (e.g., realigning 255 description statements or changing indendation), or changes to 256 YANG comments. Note: restructuring how a module uses, or does 257 not use, submodules is treated as an editorial level change on 258 the condition that there is no change in the module's semantic 259 behavior due to the restructuring. 261 - If, however, the modifier string is present, the meaning is 262 described below: 264 - "_compatible" - the change represents a backwards-compatible 265 change 267 - "_non_compatible" - the change represents a non-backwards- 268 compatible change 270 The YANG artifact name and YANG semantic version uniquely identify a 271 revision of said artifact. There MUST NOT be multiple instances of a 272 YANG artifact definition with the same name and YANG semantic version 273 but different content (and in the case of modules and submodules, 274 different revision dates). 276 There MUST NOT be multiple versions of a YANG artifact that have the 277 same MAJOR, MINOR and PATCH version numbers, but different patch 278 modifier strings. E.g., artifact version "1.2.3_non_compatible" MUST 279 NOT be defined if artifact version "1.2.3" has already been defined. 281 3.2.1. YANG Semver with submodules 283 YANG Semver MAY be used to version submodules. Submodule version are 284 separate of any version on the including module, but if a submodule 285 has changed, then the version of the including module MUST also be 286 updated. 288 The rules for determining the version change of a submodule are the 289 same as those defined in Section 3.1 and Section 3.2 as applied to 290 YANG modules, except they only apply to the part of the module schema 291 defined within the submodule's file. 293 One interesting case is moving definitions from one submodule to 294 another in a way that does not change the resultant schema of the 295 including module. In this case: 297 1. The including module has editorial changes 299 2. The submodule with the schema definition removed has non- 300 backwards-compatible changes 302 3. The submodule with the schema definitions added has backwards- 303 compatible changes 305 Note that the meaning of a submodule may change drastically despite 306 having no changes in content or revision due to changes in other 307 submodules belonging to the same module (e.g. groupings and typedefs 308 declared in one submodule and used in another). 310 3.2.2. Examples for YANG semantic versions 312 The following diagram and explanation illustrate how YANG semantic 313 versions work. 315 YANG Semantic versions for an example module: 317 0.1.0 318 | 319 0.2.0 320 | 321 1.0.0 322 | 323 1.1.0 -> 1.1.1_compatible -> 1.1.2_non_compatible 324 | 325 1.2.0 -> 1.2.1_non_compatible -> 1.2.2_non_compatible 326 | \ 327 2.0.0 \ 328 | \--> 1.3.0 -> 1.3.1_non_compatible 329 3.0.0 | 330 | 1.4.0 331 3.1.0 333 The tree diagram above illustrates how the version history might 334 evolve for an example module. The tree diagram only shows the 335 parent/child ancestry relationships between the revisions. It does 336 not describe the chronology of the revisions (i.e. when in time each 337 revision was published relative to the other revisions). 339 The following description lists an example of what the chronological 340 order of the revisions could look like, from oldest revision to 341 newest: 343 0.1.0 - first pre-release module version 345 0.2.0 - second pre-release module version (with NBC changes) 347 1.0.0 - first release (may have NBC changes from 0.2.0) 349 1.1.0 - added new functionality, leaf "foo" (BC) 351 1.2.0 - added new functionality, leaf "baz" (BC) 353 2.0.0 - change existing model for performance reasons, e.g. re-key 354 list (NBC) 356 1.3.0 - improve existing functionality, added leaf "foo-64" (BC) 358 1.1.1_compatible - backport "foo-64" leaf to 1.1.x to avoid 359 implementing "baz" from 1.2.0. This revision was created after 360 1.2.0 otherwise it may have been released as 1.2.0. (BC) 362 3.0.0 - NBC bugfix, rename "baz" to "bar"; also add new BC leaf 363 "wibble"; (NBC) 364 1.3.1_non_compatible - backport NBC fix, rename "baz" to "bar" 365 (NBC) 367 1.2.1_non_compatible - backport NBC fix, rename "baz" to "bar" 368 (NBC) 370 1.1.2_non_compatible - NBC point bug fix, not required in 2.0.0 371 due to model changes (NBC) 373 1.4.0 - introduce new leaf "ghoti" (BC) 375 3.1.0 - introduce new leaf "wobble" (BC) 377 1.2.2_non_compatible - backport "wibble". This is a BC change but 378 "non_compatible" modifier is sticky. (BC) 380 The partial ancestry relationships based on the semantic versioning 381 numbers are as follows: 383 1.0.0 < 1.1.0 < 1.2.0 < 2.0.0 < 3.0.0 < 3.1.0 385 1.0.0 < 1.1.0 < 1.1.1_compatible < 1.1.2_non_compatible 387 1.0.0 < 1.1.0 < 1.2.0 < 1.2.1_non_compatible < 388 1.2.2_non_compatible 390 1.0.0 < 1.1.0 < 1.2.0 < 1.3.0 < 1.3.1_non_compatible 392 1.0.0 < 1.1.0 < 1.2.0 < 1.3.0 < 1.4.0 394 There is no ordering relationship between 1.1.1_non_compatible and 395 either 1.2.0 or 1.2.1_non_compatible, except that they share the 396 common ancestor of 1.1.0. 398 Looking at the version number alone does not indicate ancestry. The 399 module definition in 2.0.0, for example, does not contain all the 400 contents of 1.3.0. Version 2.0.0 is not derived from 1.3.0. 402 3.3. YANG Semantic Version Update Rules 404 When a new revision of an artifact is produced, then the following 405 rules define how the YANG semantic version for the new artifact 406 revision is calculated, based on the changes between the two artifact 407 revisions, and the YANG semantic version of the base artifact 408 revision from which the changes are derived. 410 The following four rules specify the RECOMMENDED, and REQUIRED 411 minimum, update to a YANG semantic version: 413 1. If an artifact is being updated in a non-backwards-compatible 414 way, then the artifact version 415 "X.Y.Z[_compatible|_non_compatible]" SHOULD be updated to 416 "X+1.0.0" unless that version has already been used for this 417 artifact but with different content, in which case the artifact 418 version "X.Y.Z+1_non_compatible" SHOULD be used instead. 420 2. If an artifact is being updated in a backwards-compatible way, 421 then the next version number depends on the format of the current 422 version number: 424 i "X.Y.Z" - the artifact version SHOULD be updated to 425 "X.Y+1.0", unless that version has already been used for 426 this artifact but with different content, when the artifact 427 version SHOULD be updated to "X.Y.Z+1_compatible"" instead. 429 ii "X.Y.Z_compatible" - the artifact version SHOULD be updated 430 to "X.Y.Z+1_compatible". 432 iii "X.Y.Z_non_compatible" - the artifact version SHOULD be 433 updated to "X.Y.Z+1_non_compatible". 435 3. If an artifact is being updated in an editorial way, then the 436 next version number depends on the format of the current version 437 number: 439 i "X.Y.Z" - the artifact version SHOULD be updated to 440 "X.Y.Z+1" 442 ii "X.Y.Z_compatible" - the artifact version SHOULD be updated 443 to "X.Y.Z+1_compatible". 445 iii "X.Y.Z_non_compatible" - the artifact version SHOULD be 446 updated to "X.Y.Z+1_non_compatible". 448 4. YANG artifact semantic version numbers beginning with 0, i.e., 449 "0.X.Y", are regarded as pre-release definitions and need not 450 follow the rules above. Either the MINOR or PATCH version 451 numbers may be updated, regardless of whether the changes are 452 non-backwards-compatible, backwards-compatible, or editorial. 453 See Section 5 for more details on using this notation during 454 module and submodule development. 456 5. Additional pre-release rules for modules that have had at least 457 one release are specified in Section 5 . 459 Although artifacts SHOULD be updated according to the rules above, 460 which specify the recommended (and minimum required) update to the 461 version number, the following rules MAY be applied when choosing a 462 new version number: 464 1. An artifact author MAY update the version number with a more 465 significant update than described by the rules above. For 466 example, an artifact could be given a new MAJOR version number 467 (i.e., X+1.0.0), even though no non-backwards-compatible changes 468 have occurred, or an artifact could be given a new MINOR version 469 number (i.e., X.Y+1.0) even if the changes were only editorial. 471 2. An artifact author MAY skip version numbers. That is, an 472 artifact's revision history could be 1.0.0, 1.1.0, and 1.3.0 473 where 1.2.0 is skipped. Note that skipping versions has an 474 impact when importing modules by revision-or-derived. See 475 Section 4 for more details on importing modules with revision- 476 label version gaps. 478 Although YANG Semver always indicates when a non-backwards- 479 compatible, or backwards-compatible change may have occurred to a 480 YANG artifact, it does not guarantee that such a change has occurred, 481 or that consumers of that YANG artifact will be impacted by the 482 change. Hence, tooling, e.g., 483 [I-D.ietf-netmod-yang-schema-comparison] , also plays an important 484 role for comparing YANG artifacts and calculating the likely impact 485 from changes. 487 [I-D.ietf-netmod-yang-module-versioning] defines the "rev:non- 488 backwards-compatible" extension statement to indicate where non- 489 backwards-compatible changes have occurred in the module revision 490 history. If a revision entry in a module's revision history includes 491 the "rev:non-backwards-compatible" statement then that MUST be 492 reflected in any YANG semantic version associated with that revision. 493 However, the reverse does not necessarily hold, i.e., if the MAJOR 494 version has been incremented it does not necessarily mean that a 495 "rev:non-backwards-compatible" statement would be present. 497 3.4. Examples of the YANG Semver Label 499 3.4.1. Example Module Using YANG Semver 501 Below is a sample YANG module that uses the YANG Semver revision- 502 label based on the rules defined in this document. 504 module example-versioned-module { 505 yang-version 1.1; 506 namespace "urn:example:versioned:module"; 507 prefix "exvermod"; 508 rev:revision-label-scheme "ysver:yang-semver"; 510 import ietf-yang-revisions { prefix "rev"; } 511 import ietf-yang-semver { prefix "ysver"; } 513 description 514 "to be completed"; 516 revision 2017-08-30 { 517 description "Backport 'wibble' leaf"; 518 rev:revision-label 1.2.2_non_compatible; 519 } 521 revision 2017-07-30 { 522 description "Rename 'baz' to 'bar'"; 523 rev:revision-label 1.2.1_non_compatible; 524 rev:non-backwards-compatible; 525 } 527 revision 2017-04-20 { 528 description "Add new functionality, leaf 'baz'"; 529 rev:revision-label 1.2.0; 530 } 532 revision 2017-04-03 { 533 description "Add new functionality, leaf 'foo'"; 534 rev:revision-label 1.1.0; 535 } 537 revision 2017-02-07 { 538 description "First release version."; 539 rev:revision-label 1.0.0; 540 } 542 // Note: semver rules do not apply to 0.X.Y labels. 543 // The following pre-release revision statements would not 544 // appear in any final published version of a module. They 545 // are removed when the final version is published. 546 // During the pre-release phase of development, only a 547 // single one of these revision statements would appear 549 // revision 2017-01-30 { 550 // description "NBC changes to initial revision"; 551 // rev:revision-label 0.2.0; 552 // rev:non-backwards-compatible; // optional 553 // // (theoretically no 554 // // 'previous released version') 555 // } 557 // revision 2017-01-26 { 558 // description "Initial module version"; 559 // rev:revision-label 0.1.0; 560 // } 562 //YANG module definition starts here 563 } 565 3.4.2. Example of Package Using YANG Semver 567 Below is an example YANG package that uses the semver revision label 568 based on the rules defined in this document. 570 { 571 "ietf-yang-instance-data:instance-data-set": { 572 "name": "example-yang-pkg", 573 "target-ptr": "TBD", 574 "timestamp": "2018-09-06T17:00:00Z", 575 "description": "Example IETF package definition", 576 "content-data": { 577 "ietf-yang-package:yang-package": { 578 "name": "example-yang-pkg", 579 "version": "1.3.1", 580 ... 581 } 583 4. Import Module by Semantic Version 585 [I-D.ietf-netmod-yang-module-versioning] allows for imports to be 586 done based on a module or a derived revision of a module. The 587 rev:revision-or-derived statement can specify either a revision date 588 or a revision label. The YANG Semver revision-label value can be 589 used as the argument to rev:revision-or-derived . When used as such, 590 any module that contains exactly the same YANG semantic version in 591 its revision history may be used to satisfy the import requirement. 592 For example: 594 import example-module { 595 rev:revision-or-derived 3.0.0; 596 } 598 Note: the import lookup does not stop when a non-backward-compatible 599 change is encountered. That is, if module B imports a module A at or 600 derived from version 2.0.0, resolving that import will pass through a 601 revision of module A with version 2.1.0_non_compatible in order to 602 determine if the present instance of module A derives from 2.0.0. 604 If an import by revision-or-derived cannot locate the specified 605 revision-label in a given module's revision history, that import will 606 fail. This is noted in the case of version gaps. That is, if a 607 module's history includes 1.0.0, 1.1.0, and 1.3.0, an import from 608 revision-or-derived at 1.2.0 will be unable to locate the specified 609 revision entry and thus the import cannot be satisfied. 611 5. Guidelines for Using Semver During Module Development 613 This section and the IETF-specific sub-section below provides YANG 614 Semver-specific guidelines to consider when developing new YANG 615 modules. As such this section updates [RFC8407] . 617 Development of a brand new YANG module or submodule outside of the 618 IETF that uses YANG Semver as its revision-label scheme SHOULD begin 619 with a 0 for the MAJOR version component. This allows the module or 620 submodule to disregard strict semver rules with respect to non- 621 backwards-compatible changes during its initial development. 622 However, module or submodule developers MAY choose to use the semver 623 pre-release syntax instead with a 1 for the MAJOR version component. 624 For example, an initial module or submodule revision-label might be 625 either 0.0.1 or 1.0.0-alpha.1. If the authors choose to use the 0 626 MAJOR version component scheme, they MAY switch to the pre-release 627 scheme with a MAJOR version component of 1 when the module or 628 submodule is nearing initial release (e.g., a module's or submodule's 629 revision label may transition from 0.3.0 to 1.0.0-beta.1 to indicate 630 it is more mature and ready for testing). 632 When using pre-release notation, the format MUST include at least one 633 alphabetic component and MUST end with a '.' or '-' and then one or 634 more digits. These alphanumeric components will be used when 635 deciding pre-release precedence. The following are examples of valid 636 pre-release versions 638 1.0.0-alpha.1 640 1.0.0-alpha.3 642 2.1.0-beta.42 644 3.0.0-202007.rc.1 646 When developing a new revision of an existing module or submodule 647 using the YANG semver revision-label scheme, the intended target 648 semver version MUST be used along with pre-release notation. For 649 example, if a released module or submodule which has a current 650 revision-label of 1.0.0 is being modified with the intent to make 651 non-backwards-compatible changes, the first development MAJOR version 652 component must be 2 with some pre-release notation such as -alpha.1, 653 making the version 2.0.0-alpha.1. That said, every publicly 654 available release of a module or submodule MUST have a unique YANG 655 semver revision-label (where a publicly available release is one that 656 could be implemented by a vendor or consumed by an end user). 657 Therefore, it may be prudent to include the year or year and month 658 development began (e.g., 2.0.0-201907-alpha.1). As a module or 659 submodule undergoes development, it is possible that the original 660 intent changes. For example, a 1.0.0 version of a module or 661 submodule that was destined to become 2.0.0 after a development cycle 662 may have had a scope change such that the final version has no non- 663 backwards-compatible changes and becomes 1.1.0 instead. This change 664 is acceptable to make during the development phase so long as pre- 665 release notation is present in both versions (e.g., 2.0.0-alpha.3 666 becomes 1.1.0-alpha.4). However, on the next development cycle 667 (after 1.1.0 is released), if again the new target release is 2.0.0, 668 new pre-release components must be used such that every revision- 669 label for a given module or submodule MUST be unique throughout its 670 entire lifecycle (e.g., the first pre-release version might be 671 2.0.0-202005-alpha.1 if keeping the same year and month notation 672 mentioned above). 674 5.1. Pre-release Version Precedence 676 As a module or submodule is developed, the scope of the work may 677 change. That is, while a ratified module or submodule with revision- 678 label 1.0.0 is initially intended to become 2.0.0 in its next 679 ratified version, the scope of work may change such that the final 680 version is 1.1.0. During the development cycle, the pre-release 681 versions could move from 2.0.0-some-pre-release-tag to 1.1.0-some- 682 pre-release-tag. This downwards changing of version numbers makes it 683 difficult to evaluate semver rules between pre-release versions. 684 However, taken independently, each pre-release version can be 685 compared to the previously ratified version (e.g., 1.1.0-some-pre- 686 release-tag and 2.0.0-some-pre-release-tag can each be compared to 687 1.0.0). Module and submodule developers SHOULD maintain only one 688 revision statement in a pre-released module or submodule that 689 reflects the latest revision. IETF authors MAY choose to include an 690 appendix in the associated draft to track overall changes to the 691 module or submodule. 693 5.2. YANG Semver in IETF Modules 695 All published IETF modules and submodules MUST use YANG semantic 696 versions for their revision-labels. 698 Development of a new module or submodule within the IETF SHOULD begin 699 with the 0 MAJOR number scheme as described above. When revising an 700 existing IETF module or submodule, the revision-label MUST use the 701 target (i.e., intended) MAJOR and MINOR version components with a 0 702 PATCH version component. If the intended ratified release will be 703 non-backward-compatible with the current ratified release, the MINOR 704 version component MUST be 0. 706 All IETF modules and submodules in development MUST use the whole 707 document name as a pre-release version string, including the current 708 document revision. For example, if a module or submodule which is 709 currently released at version 1.0.0 is being revised to include non- 710 backwards-compatible changes in draft-user-netmod-foo, its 711 development revision-labels MUST include 2.0.0-draft-user-netmod-foo 712 followed by the document's revision (e.g., 2.0.0-draft-user-netmod- 713 foo-02). This will ensure each pre-release version is unique across 714 the lifecycle of the module or submodule. Even when using the 0 715 MAJOR version for initial module or submodule development (where 716 MINOR and PATCH can change), appending the draft name as a pre- 717 release component helps to ensure uniqueness when there are perhaps 718 multiple, parallel efforts creating the same module or submodule. 720 For IETF YANG modules and submodules that have already been 721 published, revision-labels MUST be retroactively applied to all 722 existing revisions when the next new revision is created, starting at 723 version "1.0.0" for the initial published revision, and then 724 incrementing according to the YANG Semver version rules specified in 725 Section 3.3 . For example, if a module or submodule started out in 726 the pre-NMDA ([RFC8342] ) world, and then had NMDA support added 727 without removing any legacy "state" branches -- and you are looking 728 to add additional new features -- a sensible choice for the target 729 YANG Semver would be 1.2.0 (since 1.0.0 would have been the initial, 730 pre-NMDA release, and 1.1.0 would have been the NMDA revision). 732 See Appendix A for a detailed example of IETF pre-release versions. 734 6. YANG Module 736 This YANG module contains the typedef for the YANG semantic version 737 and the identity to signal its use. 739 file "ietf-yang-semver@2021-11-04.yang" 740 module ietf-yang-semver { 741 yang-version 1.1; 742 namespace "urn:ietf:params:xml:ns:yang:ietf-yang-semver"; 743 prefix ysver; 744 rev:revision-label-scheme "yang-semver"; 746 import ietf-yang-revisions { 747 prefix rev; 748 } 750 organization 751 "IETF NETMOD (Network Modeling) Working Group"; 752 contact 753 "WG Web: 754 WG List: 756 Author: Joe Clarke 757 758 Author: Robert Wilton 759 760 Author: Reshad Rahman 761 762 Author: Balazs Lengyel 763 764 Author: Jason Sterne 765 766 Author: Benoit Claise 767 "; 768 description 769 "This module provides type and grouping definitions for YANG 770 packages. 772 Copyright (c) 2021 IETF Trust and the persons identified as 773 authors of the code. All rights reserved. 775 Redistribution and use in source and binary forms, with or 776 without modification, is permitted pursuant to, and subject 777 to the license terms contained in, the Simplified BSD License 778 set forth in Section 4.c of the IETF Trust's Legal Provisions 779 Relating to IETF Documents 780 (http://trustee.ietf.org/license-info). 782 This version of this YANG module is part of RFC XXXX; see 783 the RFC itself for full legal notices."; 785 // RFC Ed.: update the date below with the date of RFC publication 786 // and remove this note. 788 // RFC Ed.: replace XXXX with actual RFC number and remove this 789 // note. 790 // RFC Ed. update the rev:revision-label to "1.0.0". 792 revision 2021-11-04 { 793 rev:revision-label "1.0.0-draft-ietf-netmod-yang-semver-05"; 794 description 795 "Initial revision"; 796 reference 797 "RFC XXXX: YANG Semantic Versioning."; 798 } 800 /* 801 * Identities 802 */ 804 identity yang-semver { 805 base rev:revision-label-scheme-base; 806 description 807 "The revision-label scheme corresponds to the YANG Semver scheme 808 which is defined by the pattern in the 'version' typedef below. 809 The rules governing this revision-label scheme are defined in the 810 reference for this identity."; 811 reference 812 "RFC XXXX: YANG Semantic Versioning."; 813 } 815 /* 816 * Typedefs 817 */ 819 typedef version { 820 type rev:revision-label { 821 pattern '[0-9]+[.][0-9]+[.][0-9]+(_(non_)?compatible)?' 822 + '(-[A-Za-z0-9.-]+[.-][0-9]+)?([+][A-Za-z0-9.-]+)?'; 823 } 824 description 825 "Represents a YANG semantic version. The rules governing the 826 use of this revision label scheme are defined in the reference for 827 this typedef."; 828 reference 829 "RFC XXXX: YANG Semantic Versioning."; 830 } 831 } 832 834 7. Contributors 836 This document grew out of the YANG module versioning design team that 837 started after IETF 101. The design team consists of the following 838 members whom have worked on the YANG versioning project: 840 * Balazs Lengyel 842 * Benoit Claise 844 * Bo Wu 846 * Ebben Aries 848 * Jan Lindblad 850 * Jason Sterne 852 * Joe Clarke 854 * Juergen Schoenwaelder 856 * Mahesh Jethanandani 858 * Michael (Wangzitao) 860 * Qin Wu 862 * Reshad Rahman 864 * Rob Wilton 866 The initial revision of this document was refactored and built upon 867 [I-D.clacla-netmod-yang-model-update] . We would like the thank 868 Kevin D'Souza for his initial work in this problem space. 870 Discussons on the use of Semver for YANG versioning has been held 871 with authors of the OpenConfig YANG models based on their own 872 [openconfigsemver] . We would like thank both Anees Shaikh and Rob 873 Shakir for their input into this problem space. 875 8. Security Considerations 877 The document does not define any new protocol or data model. There 878 are no security impacts. 880 9. IANA Considerations 881 9.1. YANG Module Registrations 883 This document requests IANA to register a URI in the "IETF XML 884 Registry" [RFC3688] . Following the format in RFC 3688, the 885 following registration is requested. 887 URI: urn:ietf:params:xml:ns:yang:ietf-yang-semver 889 Registrant Contact: The IESG. 891 XML: N/A, the requested URI is an XML namespace. 893 The following YANG module is requested to be registred in the "IANA 894 Module Names" [RFC6020] . Following the format in RFC 6020, the 895 following registrations are requested: 897 The ietf-yang-semver module: 899 Name: ietf-yang-semver 901 XML Namespace: urn:ietf:params:xml:ns:yang:ietf-yang-semver 903 Prefix: yangver 905 Reference: [RFCXXXX] 907 9.2. Guidance for YANG Semver in IANA maintained YANG modules and 908 submodules 910 Note for IANA (to be removed by the RFC editor): Please check that 911 the registries and IANA YANG modules and submodules are referenced in 912 the appropriate way. 914 IANA is responsible for maintaining and versioning some YANG modules 915 and submodules, e.g., iana-if-types.yang [IfTypeYang] and iana- 916 routing-types.yang [RoutingTypesYang] . 918 In addition to following the rules specified in the IANA 919 Considerations section of [I-D.ietf-netmod-yang-module-versioning] , 920 IANA maintained YANG modules and submodules MUST also include a YANG 921 Semver revision label for all new revisions, as defined in Section 3 922 . 924 The YANG Semver version associated with the new revision MUST follow 925 the rules defined in Section 3.3 . 927 Note: For IANA maintained YANG modules and submodules that have 928 already been published, revision labels MUST be retroactively applied 929 to all existing revisions when the next new revision is created, 930 starting at version "1.0.0" for the initial published revision, and 931 then incrementing according to the YANG Semver rules specified in 932 Section 3.3 . 934 Most changes to IANA maintained YANG modules and submodules are 935 expected to be backwards-compatible changes and classified as MINOR 936 version changes. The PATCH version may be incremented instead when 937 only editorial changes are made, and the MAJOR version would be 938 incremented if non-backwards-compatible changes are made. 940 Given that IANA maintained YANG modules are versioned with a linear 941 history, it is anticipated that it should not be necessary to use the 942 "_compatible" or "_non_compatible" modifiers to the "Z_COMPAT" 943 version element. 945 10. References 947 10.1. Normative References 949 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 950 Requirement Levels", BCP 14, RFC 2119, 951 DOI 10.17487/RFC2119, March 1997, 952 . 954 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 955 DOI 10.17487/RFC3688, January 2004, 956 . 958 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 959 the Network Configuration Protocol (NETCONF)", RFC 6020, 960 DOI 10.17487/RFC6020, October 2010, 961 . 963 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 964 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 965 May 2017, . 967 [RFC8407] Bierman, A., "Guidelines for Authors and Reviewers of 968 Documents Containing YANG Data Models", BCP 216, RFC 8407, 969 DOI 10.17487/RFC8407, October 2018, 970 . 972 [I-D.ietf-netmod-yang-module-versioning] 973 Wilton, R., Rahman, R., Lengyel, B., Clarke, J., and J. 974 Sterne, "Updated YANG Module Revision Handling", Work in 975 Progress, Internet-Draft, draft-ietf-netmod-yang-module- 976 versioning-04, 25 October 2021, 977 . 980 10.2. Informative References 982 [I-D.clacla-netmod-yang-model-update] 983 Claise, B., Clarke, J., Lengyel, B., and K. D'Souza, "New 984 YANG Module Update Procedure", Work in Progress, Internet- 985 Draft, draft-clacla-netmod-yang-model-update-06, 2 July 986 2018, . 989 [I-D.ietf-netmod-yang-packages] 990 Wilton, R., Rahman, R., Clarke, J., Sterne, J., and B. Wu, 991 "YANG Packages", Work in Progress, Internet-Draft, draft- 992 ietf-netmod-yang-packages-02, 25 October 2021, 993 . 996 [I-D.ietf-netmod-yang-schema-comparison] 997 Wilton, R., "YANG Schema Comparison", Work in Progress, 998 Internet-Draft, draft-ietf-netmod-yang-schema-comparison- 999 01, 2 November 2020, . 1002 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 1003 and R. Wilton, "Network Management Datastore Architecture 1004 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 1005 . 1007 [openconfigsemver] 1008 "Semantic Versioning for Openconfig Models", 1009 . 1011 [semver] "Semantic Versioning 2.0.0 (text from June 19, 2020)", 1012 . 1015 [IfTypeYang] 1016 "iana-if-type YANG Module", 1017 . 1020 [RoutingTypesYang] 1021 "iana-routing-types YANG Module", 1022 . 1025 Appendix A. Example IETF Module Development 1027 Assume a new YANG module is being developed in the netmod working 1028 group in the IETF. Initially, this module is being developed in an 1029 individual internet draft, draft-jdoe-netmod-example-module. The 1030 following represents the initial version tree (i.e., value of 1031 revision-label) of the module as it's being initially developed. 1033 Version lineage for initial module development: 1035 0.0.1-draft-jdoe-netmod-example-module-00 1036 | 1037 0.1.0-draft-jdoe-netmod-example-module-01 1038 | 1039 0.2.0-draft-jdoe-netmod-example-module-02 1040 | 1041 0.2.1-draft-jdoe-netmod-example-module-03 1043 At this point, development stabilizes, and the workgroup adopts the 1044 draft. Thus now the draft becomes draft-ietf-netmod-example-module. 1045 The initial pre-release lineage continues as follows. 1047 Continued version lineage after adoption: 1049 1.0.0-draft-ietf-netmod-example-module-00 1050 | 1051 1.0.0-draft-ietf-netmod-example-module-01 1052 | 1053 1.0.0-draft-ietf-netmod-example-module-02 1055 At this point, the draft is ratified and becomes RFC12345 and the 1056 YANG module version becomes 1.0.0. 1058 A time later, the module needs to be revised to add additional 1059 capabilities. Development will be done in a backwards-compatible 1060 way. Two new individual drafts are proposed to go about adding the 1061 capabilities in different ways: draft-jdoe-netmod-exmod-enhancements 1062 and draft-jadoe-netmod-exmod-changes. These are initially developed 1063 in parallel with the following versions. 1065 Parallel development for next module revision: 1067 1.1.0-draft-jdoe-netmod-exmod-enhancements-00 || 1.1.0-draft-jadoe-netmod-exmod-changes-00 1068 | | 1069 1.1.0-draft-jdoe-netmod-exmod-enhancements-01 || 1.1.0-draft-jadoe-netmod-exmod-changes-01 1071 At this point, the WG decides to merge some aspects of both and adopt 1072 the work in jadoe's draft as draft-ietf-netmod-exmod-changes. A 1073 single version lineage continues. 1075 1.1.0-draft-ietf-netmod-exmod-changes-00 1076 | 1077 1.1.0-draft-ietf-netmod-exmod-changes-01 1078 | 1079 1.1.0-draft-ietf-netmod-exmod-changes-02 1080 | 1081 1.1.0-draft-ietf-netmod-exmod-changes-03 1083 The draft is ratified, and the new module version becomes 1.1.0. 1085 Authors' Addresses 1087 Joe Clarke (editor) 1088 Cisco Systems, Inc. 1089 7200-12 Kit Creek Rd 1090 Research Triangle Park, North Carolina 1091 United States of America 1093 Phone: +1-919-392-2867 1094 Email: jclarke@cisco.com 1096 Robert Wilton (editor) 1097 Cisco Systems, Inc. 1099 Email: rwilton@cisco.com 1101 Reshad Rahman 1103 Email: reshad@yahoo.com 1105 Balazs Lengyel 1106 Ericsson 1107 1117 Budapest 1108 Magyar Tudosok Korutja 1109 Hungary 1111 Phone: +36-70-330-7909 1112 Email: balazs.lengyel@ericsson.com 1114 Jason Sterne 1115 Nokia 1117 Email: jason.sterne@nokia.com 1119 Benoit Claise 1120 Huawei 1122 Email: benoit.claise@huawei.com