idnits 2.17.1 draft-ietf-netmod-yang-semver-02.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 9 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 (21 February 2021) is 1161 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 780, but not defined == Outdated reference: A later version (-11) exists of draft-ietf-netmod-yang-module-versioning-01 == Outdated reference: A later version (-03) exists of draft-ietf-netmod-yang-packages-01 Summary: 1 error (**), 0 flaws (~~), 4 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 Huawei 4 Updates: 8407 (if approved) J. Clarke, Ed. 5 Intended status: Standards Track R. Rahman 6 Expires: 25 August 2021 R. Wilton, Ed. 7 Cisco Systems, Inc. 8 B. Lengyel 9 Ericsson 10 J. Sterne 11 Nokia 12 K. D'Souza 13 AT&T 14 21 February 2021 16 YANG Semantic Versioning 17 draft-ietf-netmod-yang-semver-02 19 Abstract 21 This document specifies a scheme and guidelines for applying a 22 modified set of semantic versioning rules to revisions of YANG 23 modules. Additionally, this document defines a revision-label for 24 this modified semver 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 25 August 2021. 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 Semantic Versioning Pattern . . . . . . . . . . . . 3 63 3.2. Semantic Versioning Scheme for YANG Artifacts . . . . . . 4 64 3.2.1. Examples for YANG semantic version numbers . . . . . 6 65 3.3. YANG Semantic Version Update Rules . . . . . . . . . . . 8 66 3.4. Examples of the YANG Semver Label . . . . . . . . . . . . 9 67 3.4.1. Example Module Using YANG Semver . . . . . . . . . . 9 68 3.4.2. Example of Package Using YANG Semver . . . . . . . . 11 69 4. Import Module by Semantic Version . . . . . . . . . . . . . . 11 70 5. Guidelines for Using Semver During Module Development . . . . 12 71 5.1. Pre-release Version Precedence . . . . . . . . . . . . . 13 72 5.2. YANG Semver in IETF Modules . . . . . . . . . . . . . . . 13 73 6. YANG Module . . . . . . . . . . . . . . . . . . . . . . . . . 14 74 7. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 16 75 8. Security Considerations . . . . . . . . . . . . . . . . . . . 17 76 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 17 77 9.1. YANG Module Registrations . . . . . . . . . . . . . . . . 17 78 9.2. Guidance for YANG Semver in IANA maintained YANG 79 modules . . . . . . . . . . . . . . . . . . . . . . . . . 17 80 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 18 81 10.1. Normative References . . . . . . . . . . . . . . . . . . 18 82 10.2. Informative References . . . . . . . . . . . . . . . . . 18 83 Appendix A. Example IETF Module Development . . . . . . . . . . 19 84 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 21 86 1. Introduction 88 [I-D.ietf-netmod-yang-module-versioning] puts forth a number of 89 concepts relating to modified rules for updating modules, a means to 90 signal when a new revision of a module has non-backwards-compatible 91 (NBC) changes compared to its previous revision, and a versioning 92 scheme that uses the revision history as a lineage for determining 93 from where a specific revision of a YANG module is derived. 94 Additionally, section 3.3 of [I-D.ietf-netmod-yang-module-versioning] 95 defines a revision label which can be used as an overlay or alias to 96 provide additional context or an additional way to refer to a 97 specific revision. 99 This document defines a revision-label scheme that uses modified 100 [semver] rules for YANG artifacts (i.e., YANG modules and YANG 101 packages [I-D.ietf-netmod-yang-packages] ) as well as the revision 102 label definition for using this scheme. The goal of this is to add a 103 human readable version label that provides compatibility information 104 for the YANG artifact without one needing to compare or parse its 105 body. The label and rules defined herein represent the RECOMMENDED 106 revision label scheme for IETF YANG artifacts. 108 2. Terminology and Conventions 110 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 111 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 112 "OPTIONAL" in this document are to be interpreted as described in BCP 113 14 [RFC2119] [RFC8174] when, and only when, they appear in all 114 capitals, as shown here. 116 Additionally, this document uses the following terminology: 118 * YANG artifact: YANG modules, YANG packages 119 [I-D.ietf-netmod-yang-packages] , and YANG schema elements are 120 examples of YANG artifacts for the purposes of this document. 122 3. YANG Semantic Versioning 124 This section defines YANG Semantic Versioning, explains how it is 125 used with YANG artifacts, and the rules associated with changing an 126 artifact's semantic version number when its contents are updated. 128 3.1. YANG Semantic Versioning Pattern 130 YANG artifacts that employ semantic versioning as defined in this 131 document MUST use a version string (e.g., in revision-label or as a 132 package version) that corresponds to the following pattern: 133 X.Y.Z_COMPAT. Where: 135 * X, Y and Z are mandatory non-negative integers that are each less 136 than 2147483647 (i.e., the maximum signed 32-bit integer value) 137 and MUST NOT contain leading zeroes 139 * The '.' is a literal period (ASCII character 0x2e) 141 * The '_' is an optional single literal underscore (ASCII character 142 0x5f) and MUST only present if the following COMPAT element is 143 included 145 * COMPAT, if it is specified, MUST be either the literal string 146 "compatible" or the literal string "non_compatible" 148 Additionally, [semver] defines two specific types of metadata that 149 may be appended to a semantic version string. Pre-release metadata 150 MAY be appended to a semver string after a trailing '-' character. 151 Build metadata MAY be appended after a trailing '+' character. If 152 both pre-release and build metadata are present, then build metadata 153 MUST follow pre-release metadata. While build metadata MUST be 154 ignored by YANG semver parsers, pre-release metadata MUST be used 155 during module development and MUST be considered base on Section 5 . 156 Both pre-release and build metadata are allowed in order to support 157 all of the [semver] rules. Thus, a version lineage that follows 158 strict [semver] rules is allowed for a YANG artifact. 160 To signal the use of this versioning scheme, modules MUST set the 161 revision-label-scheme extension as defined in 162 [I-D.ietf-netmod-yang-module-versioning] to the identity "yang- 163 semver". That identity value is defined in the ietf-yang-semver 164 module below. 166 Additionally, this ietf-yang-semver module defines a typedef that 167 formally specifies the syntax of the YANG semver version string. 169 3.2. Semantic Versioning Scheme for YANG Artifacts 171 This document defines the YANG semantic versioning scheme that is 172 used for YANG artifacts that employ the YANG semver label. The 173 versioning scheme has the following properties: 175 * The YANG semantic versioning scheme is extended from version 2.0.0 176 of the semantic versioning scheme defined at semver.org [semver] 177 to cover the additional requirements for the management of YANG 178 artifact lifecyles that cannot be addressed using the semver.org 179 2.0.0 versioning scheme alone. 181 * Unlike the [semver] versioning scheme, the YANG semantic 182 versioning scheme supports updates to older versions of YANG 183 artifacts, to allow for bug fixes and enhancements to artifact 184 versions that are not the latest. However, it does not provide 185 for the unlimited branching and updating of older revisions which 186 are documented by the general rules in 187 [I-D.ietf-netmod-yang-module-versioning] . 189 * YANG artifacts that follow the [semver] versioning scheme are 190 fully compatible with implementations that understand the YANG 191 semantic versioning scheme defined in this document. 193 * If updates are always restricted to the latest revision of the 194 artifact only, then the version numbers used by the YANG semantic 195 versioning scheme are exactly the same as those defined by the 196 [semver] versioning scheme. 198 Every YANG module versioned using the YANG semantic versioning scheme 199 specifies the module's semantic version number as the argument to the 200 'rev:revision-label' statement. 202 Because the rules put forth in 203 [I-D.ietf-netmod-yang-module-versioning] are designed to work well 204 with existing versions of YANG and allow for artifact authors to 205 migrate to this scheme, it is not expected that all revisions of a 206 given YANG artifact will have a semantic version label. For example, 207 the first revision of a module may have been produced before this 208 scheme was available. 210 YANG packages that make use of this semantic versioning scheme will 211 have their semantic version as the value of the "revision_label" 212 property. 214 As stated above, the YANG semver version number is expressed as a 215 string of the form: 'X.Y.Z_COMPAT'; where X, Y, and Z each represent 216 non-negative integers smaller than 2147483647 without leading zeroes, 217 and _COMPAT represents an optional suffix of either "_compatible" or 218 "_non_compatible". 220 * 'X' is the MAJOR version. Changes in the MAJOR version number 221 indicate changes that are non-backwards-compatible to versions 222 with a lower MAJOR version number. 224 * 'Y' is the MINOR version. Changes in the MINOR version number 225 indicate changes that are backwards-compatible to versions with 226 the same MAJOR version number, but a lower MINOR version number 227 and no PATCH "_compatible" or "_non_compatible" modifier. 229 * 'Z_COMPAT' is the PATCH version and modifier. Changes in the 230 PATCH version number can indicate editorial, backwards-compatible, 231 or non-backwards-compatible changes relative to versions with the 232 same MAJOR and MINOR version numbers, but lower PATCH version 233 number, depending on what form modifier "_COMPAT" takes: 235 - If the modifier string is absent, the change represents an 236 editorial change. An editorial change is defined to be a 237 change in the YANG artifact's content that does not affect the 238 semantic meaning or functionality provided by the artifact in 239 any way. Some examples include correcting a spelling mistake 240 in the description of a leaf within a YANG module, non- 241 significant whitespace changes (e.g. realigning description 242 statements, or changing indendation), or changes to YANG 243 comments. Note: restructuring how a module uses, or does not 244 use, submodules is treated as an editorial level change on the 245 condition that there is no change in the module's semantic 246 behavior due to the restructuring. 248 - If, however, the modifier string is present, the meaning is 249 described below: 251 - "_compatible" - the change represents a backwards-compatible 252 change 254 - "_non_compatible" - the change represents a non-backwards- 255 compatible change 257 The YANG artifact name and YANG semantic version number uniquely 258 identify a revision of said artifact. There MUST NOT be multiple 259 instances of a YANG artifact definition with the same name and YANG 260 semantic version number but different content (and in the case of 261 modules, different revision dates). 263 There MUST NOT be multiple versions of a YANG artifact that have the 264 same MAJOR, MINOR and PATCH version numbers, but different patch 265 modifier strings. E.g., artifact version "1.2.3_non_compatible" MUST 266 NOT be defined if artifact version "1.2.3" has already been defined. 268 3.2.1. Examples for YANG semantic version numbers 270 The following diagram and explanation illustrates how YANG semantic 271 version numbers work. 273 Example YANG semantic version numbers for an example artifact: 275 0.1.0 276 | 277 0.2.0 278 | 279 1.0.0 280 | \ 281 | 1.1.0 -> 1.1.1_compatible -> 1.1.2_non_compatible 282 | | 283 | 1.2.0 -> 1.2.1_non_compatible -> 1.2.2_non_compatible 284 | | 285 | 1.3.0 -> 1.3.1 286 | 287 2.0.0 288 | 289 3.0.0 290 \ 291 3.1.0 293 Assume the tree diagram above illustrates how an example YANG 294 module's version history might evolve. For example, the tree might 295 represent the following changes, listed in chronological order from 296 oldest revision to newest: 298 0.1.0 - first beta module version 300 0.2.0 - second beta module version (with NBC changes) 302 1.0.0 - first release (may have NBC changes from 0.2.0) 304 1.1.0 - added new functionality, leaf "foo" (BC) 306 1.2.0 - added new functionality, leaf "baz" (BC) 308 1.3.0 - improve existing functionality, added leaf "foo-64" (BC) 310 1.3.1 - improve description wording for "foo-64" (Editorial) 312 1.1.1_compatible - backport "foo-64" leaf to 1.1.x to avoid 313 implementing "baz" from 1.2.0 (BC) 315 2.0.0 - change existing model for performance reasons, e.g. re-key 316 list (NBC) 318 1.1.2_non_compatible - NBC point bug fix, not required in 2.0.0 319 due to model changes (NBC) 321 3.0.0 - NBC bugfix, rename "baz" to "bar"; also add new BC leaf 322 "wibble"; (NBC) 323 1.2.1_non_compatible - backport NBC fix, changing "baz" to "bar" 325 1.2.2_non_compatible - backport "wibble". This is a BC change but 326 "non_compatible" modifier is sticky. 328 3.1.0 - introduce new leaf "wobble" (BC) 330 The partial ordering relationships based on the semantic versioning 331 numbers can be defined as follows: 333 1.0.0 < 1.1.0 < 1.2.0 < 1.3.0 < 2.0.0 < 3.0.0 < 3.1.0 335 1.0.0 < 1.1.0 < 1.1.1_compatible < 1.1.2_non_compatible 337 1.0.0 < 1.1.0 < 1.2.0 < 1.2.1_non_compatible < 338 1.2.2_non_compatible 340 There is no ordering relationship between 1.1.1_non_compatible and 341 either 1.2.0 or 1.2.1_non_compatible, except that they share the 342 common ancestor of 1.1.0. 344 Looking at the version number alone, the module definition in 2.0.0 345 does not necessarily contain the contents of 1.3.0. However, the 346 module revision history in 2.0.0 may well indicate that it was edited 347 from module version 1.3.0. 349 3.3. YANG Semantic Version Update Rules 351 When a new revision of an artifact is produced, then the following 352 rules define how the YANG semantic version number for the new 353 artifact revision is calculated, based on the changes between the two 354 artifact revisions, and the YANG semantic version number of the base 355 artifact revision from which the changes are derived: 357 1. If an artifact is being updated in a non-backwards-compatible 358 way, then the artifact version 359 "X.Y.Z[_compatible|_non_compatible]" MUST be updated to "X+1.0.0" 360 unless that artifact version has already been defined with 361 different content, in which case the artifact version 362 "X.Y.Z+1_non_compatible" MUST be used instead. 364 2. Under some circumstances (e.g., to avoid adding a "_compatible" 365 modifier) an artifact author MAY also update the MAJOR version 366 when the only changes are backwards-compatible. This is where 367 tooling is important to highlight all changes. Because, while 368 avoiding the "_compatible" and "_non_compatible" modifiers have a 369 clear advantage, bumping a MAJOR version when changes are 370 entirely backwards-compatible may confuse end users. 372 3. An artifact author MAY choose to skip version numbers. That is, 373 an artifact's revision history can include 1.0.0, 1.1.0, and 374 1.3.0 where 1.2.0 is skipped. Note that doing so has an impact 375 when importing modules by revision-or-derived. See Section 4 for 376 more details on importing modules with revision-label version 377 gaps. 379 4. If an artifact is being updated in a backwards-compatible way, 380 then the next version number depends on the format of the current 381 version number: 383 i "X.Y.Z" - the artifact version MUST be updated to "X.Y+1.0", 384 unless that artifact version has already been defined with 385 different content, when the artifact version MUST be updated 386 to "X.Y.Z+1_compatible"" instead. 388 ii "X.Y.Z_compatible" - the artifact version MUST be updated to 389 "X.Y.Z+1_compatible". 391 iii "X.Y.Z_non_compatible" - the artifact version MUST be 392 updated to "X.Y.Z+1_non_compatible". 394 5. If an artifact is being updated in an editorial way, then the 395 next version number depends on the format of the current version 396 number: 398 i "X.Y.Z" - the artifact version MUST be updated to "X.Y.Z+1" 400 ii "X.Y.Z_compatible" - the artifact version MUST be updated to 401 "X.Y.Z+1_compatible". 403 iii "X.Y.Z_non_compatible" - the artifact version MUST be 404 updated to "X.Y.Z+1_non_compatible". 406 6. YANG artifact semantic version numbers beginning with 0, i.e 407 "0.X.Y" are regarded as beta definitions and need not follow the 408 rules above. Either the MINOR or PATCH version numbers may be 409 updated, regardless of whether the changes are non-backwards- 410 compatible, backwards-compatible, or editorial. See Section 5 411 for more details on using this notation during module 412 development. 414 3.4. Examples of the YANG Semver Label 416 3.4.1. Example Module Using YANG Semver 418 Below is a sample YANG module that uses the YANG semver revision 419 label based on the rules defined in this document. 421 module example-versioned-module { 422 yang-version 1.1; 423 namespace "urn:example:versioned:module"; 424 prefix "exvermod"; 425 rev:revision-label-scheme "yangver:yang-semver"; 427 import ietf-yang-revisions { prefix "rev"; } 428 import ietf-yang-semver { prefix "yangver"; } 430 description 431 "to be completed"; 433 revision 2018-02-28 { 434 description "Added leaf 'wobble'"; 435 rev:revision-label "3.1.0"; 436 } 438 revision 2017-12-31 { 439 description "Rename 'baz' to 'bar', added leaf 'wibble'"; 440 rev:revision-label "3.0.0"; 441 rev:nbc-changes; 442 } 444 revision 2017-10-30 { 445 description "Change the module structure"; 446 rev:revision-label "2.0.0"; 447 rev:nbc-changes; 448 } 450 revision 2017-08-30 { 451 description "Clarified description of 'foo-64' leaf"; 452 rev:revision-label "1.3.1"; 453 } 455 revision 2017-07-30 { 456 description "Added leaf foo-64"; 457 rev:revision-label "1.3.0"; 458 } 460 revision 2017-04-20 { 461 description "Add new functionality, leaf 'baz'"; 462 rev:revision-label "1.2.0"; 463 } 465 revision 2017-04-03 { 466 description "Add new functionality, leaf 'foo'"; 467 rev:revision-label "1.1.0"; 468 } 469 revision 2017-04-03 { 470 description "First release version."; 471 rev:revision-label "1.0.0"; 472 } 474 // Note: semver rules do not apply to 0.X.Y labels. 476 revision 2017-01-30 { 477 description "NBC changes to initial revision"; 478 semver:module-version "0.2.0"; 479 } 481 revision 2017-01-26 { 482 description "Initial module version"; 483 semver:module-version "0.1.0"; 484 } 486 //YANG module definition starts here 488 3.4.2. Example of Package Using YANG Semver 490 Below is an example YANG package that uses the semver revision label 491 based on the rules defined in this document. 493 { 494 "ietf-yang-instance-data:instance-data-set": { 495 "name": "example-yang-pkg", 496 "target-ptr": "TBD", 497 "timestamp": "2018-09-06T17:00:00Z", 498 "description": "Example IETF package definition", 499 "content-data": { 500 "ietf-yang-package:yang-package": { 501 "name": "example-yang-pkg", 502 "version": "1.3.1", 503 ... 504 } 506 4. Import Module by Semantic Version 508 [I-D.ietf-netmod-yang-module-versioning] allows for imports to be 509 done based on a module or a derived revision of a module. The 510 rev:revision-or-derived statement can specify either a revision date 511 or a revision label. When importing by semver, the YANG semver 512 revision label value MAY be used as an argument to rev:revision-or- 513 derived. In so, any module which has that semver label as its latest 514 revision label or has that label in its revision history can be used 515 to satisfy the import requirement. For example: 517 import example-module { 518 rev:revision-or-derived "3.0.0"; 519 } 521 Note: the import lookup does not stop when a non-backward-compatible 522 change is encountered. That is, if module B imports a module A at or 523 derived from version 2.0.0, resolving that import will pass through a 524 revision of module A with version 2.1.0_non_compatible in order to 525 determine if the present instance of module A derives from 2.0.0. 527 If an import by revision-or-derived cannot locate the specified 528 revision-label in a given module's revision history, that import will 529 fail. This is noted in the case of version gaps. That is, if a 530 module's history includes 1.0.0, 1.1.0, and 1.3.0, an import from 531 revision-or-derived at 1.2.0 will be unable to locate the specified 532 revision entry and thus the import cannot be satisfied. 534 5. Guidelines for Using Semver During Module Development 536 This section and the IETF-specific sub-section below provides YANG 537 semver-specific guidelines to consider when developing new YANG 538 modules. As such this section updates [RFC8407] . 540 Development of a brand new YANG module outside of the IETF that uses 541 YANG semver as its revision-label scheme SHOULD begin with a 0 for 542 the MAJOR version component. This allows the module to disregard 543 strict semver rules with respect to non-backwards-compatible changes 544 during its initial development. However, module developers MAY 545 choose to use the semver pre-release syntax instead with a 1 for the 546 MAJOR version component. For example, an initial module revision- 547 label might be either 0.0.1 or 1.0.0-alpha.1. If the authors choose 548 to use the 0 MAJOR version component scheme, they MAY switch to the 549 pre-release scheme with a MAJOR version component of 1 when the 550 module is nearing initial release (e.g., a module's revision label 551 may transition from 0.3.0 to 1.0.0-beta.1 to indicate it is more 552 mature and ready for testing). 554 When using pre-release notation, the format MUST include at least one 555 alphabetic component and MUST end with a '.' and then one or more 556 digits. These alphanumeric components will be used when deciding 557 pre-release precedence. The following are examples of valid pre- 558 release versions 560 1.0.0-alpha.1 562 1.0.0-alpha.3 564 2.1.0-beta.42 565 3.0.0-202007.rc.1 567 When developing a new revision of an existing module using the YANG 568 semver revision-label scheme, the intended target semver version MUST 569 be used along with pre-release notation. For example, if a released 570 module which has a current revision-label of 1.0.0 is being modified 571 with the intent to make non-backwards-compatible changes, the first 572 development MAJOR version component must be 2 with some pre-release 573 notation such as -alpha.1, making the version 2.0.0-alpha.1. That 574 said, every publicly available release of a module MUST have a unique 575 YANG semver revision-label (where a publicly available release is one 576 that could be implemented by a vendor or consumed by an end user). 577 Therefore, it may be prudent to include the year or year and month 578 development began (e.g., 2.0.0-201907-alpha.1). As a module 579 undergoes development, it is possible that the original intent 580 changes. For example, a 1.0.0 version of a module that was destined 581 to become 2.0.0 after a development cycle may have had a scope change 582 such that the final version has no non-backwards-compatible changes 583 and becomes 1.1.0 instead. This change is acceptable to make during 584 the development phase so long as pre-release notation is present in 585 both versions (e.g., 2.0.0-alpha.3 becomes 1.1.0-alpha.4). However, 586 on the next development cycle (after 1.1.0 is released), if again the 587 new target release is 2.0.0, new pre-release components must be used 588 such that every revision-label for a given module MUST be unique 589 throughout its entire lifecycle (e.g., the first pre-release version 590 might be 2.0.0-202005-alpha.1 if keeping the same year and month 591 notation mentioned above). 593 5.1. Pre-release Version Precedence 595 [TODO: Describe precedence considering there could be changes during 596 development and parallel development tracks.] 598 5.2. YANG Semver in IETF Modules 600 All publish IETF modules MUST use YANG semantic versions for their 601 revision-labels. For IETF YANG modules that have already been 602 published, revision labels MUST be retrospectively applied to all 603 existing revisions when the next new revision is created, starting at 604 version "1.0.0" for the initial published revision, and then 605 incrementing according to the YANG Semver version rules specified in 606 Section 3.3 . 608 Net new module development within the IETF SHOULD begin with the 0 609 MAJOR number scheme as described above. When revising an existing 610 IETF module, the revision-label MUST use the target (i.e., intended) 611 MAJOR and MINOR version components with a 0 PATCH version component. 612 If the intended ratified release will be non-backward-compatible with 613 the current ratified release, the MINOR version component MUST be 0. 615 All IETF modules in development MUST use the whole document name as a 616 pre-release version string, including the current document revision. 617 For example, if a module which is currently released at version 1.0.0 618 is being revised to include non-backwards-compatible changes in 619 draft-user-netmod-foo, its development revision-labels MUST include 620 2.0.0-draft-user-netmod-foo followed by the document's revision 621 (e.g., 2.0.0-draft-user-netmod-foo-02). This will ensure each pre- 622 release version is unique across the lifecycle of the module. Even 623 when using the 0 MAJOR version for initial module development (where 624 MINOR and PATCH can change), appending the draft name as a pre- 625 release component helps to ensure uniqueness when there are perhaps 626 multiple, parallel efforts creating the same module. 628 If a module is being revised and the original module never had a 629 revision-label (i.e., you wish to start using YANG semver in future 630 module revisions), choose a semver value that makes the most sense 631 based on the module's history. For example, if a module started out 632 in the pre-NMDA ([RFC8342] ) world, and then had NMDA support added 633 without removing any legacy "state" branches -- and you are looking 634 to add additional new features -- a sensible choice for the target 635 YANG semver would be 1.2.0 (since 1.0.0 would have been the initial, 636 pre-NMDA release, and 1.1.0 would have been the NMDA revision). 638 See Appendix A for a detailed example of IETF pre-release versions. 640 6. YANG Module 642 This YANG module contains the typedef for the YANG semantic version. 644 file "ietf-yang-semver@2020-06-30.yang" 645 module ietf-yang-semver { 646 yang-version 1.1; 647 namespace "urn:ietf:params:xml:ns:yang:ietf-yang-semver"; 648 prefix yangver; 649 rev:revision-label-scheme "yang-semver"; 651 import ietf-yang-revisions { 652 prefix rev; 653 } 655 organization 656 "IETF NETMOD (Network Modeling) Working Group"; 657 contact 658 "WG Web: 659 WG List: 661 Author: Joe Clarke 662 "; 663 description 664 "This module provides type and grouping definitions for YANG 665 packages. 667 Copyright (c) 2020 IETF Trust and the persons identified as 668 authors of the code. All rights reserved. 670 Redistribution and use in source and binary forms, with or 671 without modification, is permitted pursuant to, and subject 672 to the license terms contained in, the Simplified BSD License 673 set forth in Section 4.c of the IETF Trust's Legal Provisions 674 Relating to IETF Documents 675 (http://trustee.ietf.org/license-info). 677 This version of this YANG module is part of RFC XXXX; see 678 the RFC itself for full legal notices."; 680 // RFC Ed.: update the date below with the date of RFC publication 681 // and remove this note. 682 // RFC Ed.: replace XXXX with actual RFC number and remove this 683 // note. 685 revision 2020-06-30 { 686 rev:revision-label "1.0.0-draft-ietf-netmod-yang-semver-01"; 687 description 688 "Initial revision"; 689 reference 690 "RFC XXXX: YANG Semantic Versioning."; 691 } 693 /* 694 * Identities 695 */ 697 identity yang-semver { 698 base rev:revision-label-scheme-base-identity; 699 description 700 "The revision-label scheme corresponds to the YANG semver scheme 701 which is defined by the pattern in the 'version' typedef below. 702 The rules governing this revision-label scheme are defined in the 703 reference for this identity."; 705 reference 706 "RFC XXXX: YANG Semantic Versioning."; 707 } 709 /* 710 * Typedefs 711 */ 713 typedef version { 714 type string { 715 pattern '\d+[.]\d+[.]\d+(_(non_)?compatible)?(-[\w\d.]+)?([+][\w\d\.]+)?'; 716 } 717 description 718 "Represents a YANG semantic version number. The rules governing the 719 use of this revision label scheme are defined in the reference for 720 this typedef."; 721 reference 722 "RFC XXXX: YANG Semantic Versioning."; 723 } 724 } 725 727 7. Contributors 729 This document grew out of the YANG module versioning design team that 730 started after IETF 101. The design team consists of the following 731 members whom have worked on the YANG versioning project: 733 * Balazs Lengyel 735 * Benoit Claise 737 * Ebben Aries 739 * Jason Sterne 741 * Joe Clarke 743 * Juergen Schoenwaelder 745 * Mahesh Jethanandani 747 * Michael (Wangzitao) 749 * Qin Wu 751 * Reshad Rahman 752 * Rob Wilton 754 The initial revision of this document was refactored and built upon 755 [I-D.clacla-netmod-yang-model-update] . 757 Discussons on the use of Semver for YANG versioning has been held 758 with authors of the OpenConfig YANG models based on their own 759 [openconfigsemver] . We would like thank both Anees Shaikh and Rob 760 Shakir for their input into this problem space. 762 8. Security Considerations 764 The document does not define any new protocol or data model. There 765 are no security impacts. 767 9. IANA Considerations 769 9.1. YANG Module Registrations 771 The following YANG module is requested to be registred in the "IANA 772 Module Names" registry: 774 Name: ietf-yang-semver 776 XML Namespace: urn:ietf:params:xml:ns:yang:ietf-yang-semver 778 Prefix: yangver 780 Reference: [RFCXXXX] 782 9.2. Guidance for YANG Semver in IANA maintained YANG modules 784 Note for IANA (to be removed by the RFC editor): Please check that 785 the registries and IANA YANG modules are referenced in the 786 appropriate way. 788 IANA is responsible for maintaining and versioning some YANG modules, 789 e.g., iana-if-types.yang [IfTypeYang] and iana-routing-types.yang 790 [RoutingTypesYang] . 792 In addition to following the rules specified in the IANA 793 Considerations section of [I-D.ietf-netmod-yang-module-versioning] , 794 IANA maintained YANG modules MUST also include a YANG Semver revision 795 label for all new revisions, as defined in Section 3 . 797 The YANG Semver version associated with the new revision MUST follow 798 the rules defined in Section 3.3 . 800 Note: For IANA maintained YANG modules that have already been 801 published, revision labels MUST be retrospectively applied to all 802 existing revisions when the next new revision is created, starting at 803 version "1.0.0" for the initial published revision, and then 804 incrementing according to the YANG Semver version rules specified in 805 Section 3.3 . 807 Most changes to IANA maintained YANG modules are expected to be 808 backwards-compatible changes and classified as MINOR version changes. 809 The PATCH version may be incremented instead when only editorial 810 changes are made, and the MAJOR version would be incremented if non- 811 backwards-compatible major changes are made. 813 Given that IANA maintained YANG modules are versioned with a linear 814 history, it is anticipated that it should not be necessary to use the 815 "_compatible" or "_non_compatible" modifiers to the "Z_COMPAT" 816 version element. 818 10. References 820 10.1. Normative References 822 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 823 Requirement Levels", BCP 14, RFC 2119, 824 DOI 10.17487/RFC2119, March 1997, 825 . 827 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 828 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 829 May 2017, . 831 [RFC8407] Bierman, A., "Guidelines for Authors and Reviewers of 832 Documents Containing YANG Data Models", BCP 216, RFC 8407, 833 DOI 10.17487/RFC8407, October 2018, 834 . 836 [I-D.ietf-netmod-yang-module-versioning] 837 Wilton, R., Rahman, R., Lengyel, B., Clarke, J., Sterne, 838 J., Claise, B., and K. D'Souza, "Updated YANG Module 839 Revision Handling", Work in Progress, Internet-Draft, 840 draft-ietf-netmod-yang-module-versioning-01, 10 July 2020, 841 . 844 10.2. Informative References 846 [I-D.clacla-netmod-yang-model-update] 847 Claise, B., Clarke, J., Lengyel, B., and K. D'Souza, "New 848 YANG Module Update Procedure", Work in Progress, Internet- 849 Draft, draft-clacla-netmod-yang-model-update-06, 2 July 850 2018, . 853 [I-D.ietf-netmod-yang-packages] 854 Wilton, R., Rahman, R., Clarke, J., Sterne, J., and W. Bo, 855 "YANG Packages", Work in Progress, Internet-Draft, draft- 856 ietf-netmod-yang-packages-01, 2 November 2020, 857 . 860 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 861 and R. Wilton, "Network Management Datastore Architecture 862 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 863 . 865 [openconfigsemver] 866 "Semantic Versioning for Openconfig Models", 867 . 869 [semver] "Semantic Versioning 2.0.0", . 871 [IfTypeYang] 872 "iana-if-type YANG Module", 873 . 876 [RoutingTypesYang] 877 "iana-routing-types YANG Module", 878 . 881 Appendix A. Example IETF Module Development 883 Assume a new YANG module is being developed in the netmod working 884 group in the IETF. Initially, this module is being developed in an 885 individual internet draft, draft-jdoe-netmod-example-module. The 886 following represents the initial version tree (i.e., value of 887 revision-label) of the module as it's being initially developed. 889 Version lineage for initial module development: 891 0.0.1-draft-jdoe-netmod-example-module-00 892 | 893 0.1.0-draft-jdoe-netmod-example-module-01 894 | 895 0.2.0-draft-jdoe-netmod-example-module-02 896 | 897 0.2.1-draft-jdoe-netmod-example-module-03 899 At this point, development stabilizes, and the workgroup adopts the 900 draft. Thus now the draft becomes draft-ietf-netmod-example-module. 901 The initial pre-release lineage continues as follows. 903 Continued version lineage after adoption: 905 1.0.0-draft-ietf-netmod-example-module-00 906 | 907 1.0.0-draft-ietf-netmod-example-module-01 908 | 909 1.0.0-draft-ietf-netmod-example-module-02 911 At this point, the draft is ratified and becomes RFC12345 and the 912 YANG module version number becomes 1.0.0. 914 A time later, the module needs to be revised to add additional 915 capabilities. Development will be done in a backwards-compatible 916 way. Two new individual drafts are proposed to go about adding the 917 capabilities in different ways: draft-jdoe-netmod-exmod-enhancements 918 and draft-jadoe-netmod-exmod-changes. These are initially developed 919 in parallel with the following versions. 921 Parallel development for next module revision: 923 1.1.0-draft-jdoe-netmod-exmod-enhancements-00 || 1.1.0-draft-jadoe-netmod-exmod-changes-00 924 | | 925 1.1.0-draft-jdoe-netmod-exmod-enhancements-01 || 1.1.0-draft-jadoe-netmod-exmod-changes-01 927 At this point, the WG decides to merge some aspects of both and adopt 928 the work in jadoe's draft as draft-ietf-netmod-exmod-changes. A 929 single version lineage continues. 931 1.1.0-draft-ietf-netmod-exmod-changes-00 932 | 933 1.1.0-draft-ietf-netmod-exmod-changes-01 934 | 935 1.1.0-draft-ietf-netmod-exmod-changes-02 936 | 937 1.1.0-draft-ietf-netmod-exmod-changes-03 939 The draft is ratified, and the new module version becomes 1.1.0. 941 Authors' Addresses 943 Benoit Claise 944 Huawei 946 Email: benoit.claise@huawei.com 948 Joe Clarke (editor) 949 Cisco Systems, Inc. 950 7200-12 Kit Creek Rd 951 Research Triangle Park, North Carolina 952 United States of America 954 Phone: +1-919-392-2867 955 Email: jclarke@cisco.com 957 Reshad Rahman 958 Cisco Systems, Inc. 960 Email: rrahman@cisco.com 962 Robert Wilton (editor) 963 Cisco Systems, Inc. 965 Email: rwilton@cisco.com 967 Balazs Lengyel 968 Ericsson 969 1117 Budapest 970 Magyar Tudosok Korutja 971 Hungary 973 Phone: +36-70-330-7909 974 Email: balazs.lengyel@ericsson.com 976 Jason Sterne 977 Nokia 979 Email: jason.sterne@nokia.com 980 Kevin D'Souza 981 AT&T 982 200 S. Laurel Ave 983 Middletown, NJ 984 United States of America 986 Email: kd6913@att.com