idnits 2.17.1 draft-ietf-netmod-yang-semver-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 : ---------------------------------------------------------------------------- ** 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 (12 July 2021) is 1019 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 839, but not defined == Outdated reference: A later version (-11) exists of draft-ietf-netmod-yang-module-versioning-02 == Outdated reference: A later version (-03) exists of draft-ietf-netmod-yang-packages-01 == 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 B. Claise 3 Internet-Draft Huawei 4 Updates: 8407 (if approved) J. Clarke, Ed. 5 Intended status: Standards Track R. Rahman 6 Expires: 13 January 2022 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 12 July 2021 16 YANG Semantic Versioning 17 draft-ietf-netmod-yang-semver-03 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 13 January 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 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 . . . . . . . . . . . . 10 67 3.4.1. Example Module Using YANG Semver . . . . . . . . . . 10 68 3.4.2. Example of Package Using YANG Semver . . . . . . . . 12 69 4. Import Module by Semantic Version . . . . . . . . . . . . . . 12 70 5. Guidelines for Using Semver During Module Development . . . . 13 71 5.1. Pre-release Version Precedence . . . . . . . . . . . . . 14 72 5.2. YANG Semver in IETF Modules . . . . . . . . . . . . . . . 15 73 6. YANG Module . . . . . . . . . . . . . . . . . . . . . . . . . 16 74 7. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 17 75 8. Security Considerations . . . . . . . . . . . . . . . . . . . 18 76 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 18 77 9.1. YANG Module Registrations . . . . . . . . . . . . . . . . 18 78 9.2. Guidance for YANG Semver in IANA maintained YANG modules 79 and submodules . . . . . . . . . . . . . . . . . . . . . 19 80 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 19 81 10.1. Normative References . . . . . . . . . . . . . . . . . . 19 82 10.2. Informative References . . . . . . . . . . . . . . . . . 20 83 Appendix A. Example IETF Module Development . . . . . . . . . . 21 84 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 22 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 and 90 submodules, a means to signal when a new revision of a module or 91 submodule has non-backwards-compatible (NBC) changes compared to its 92 previous revision, and a versioning scheme that uses the revision 93 history as a lineage for determining from where a specific revision 94 of a YANG module or submodule is derived. Additionally, section 3.3 95 of [I-D.ietf-netmod-yang-module-versioning] defines a revision label 96 which can be used as an overlay or alias to provide additional 97 context or an additional way to refer to a specific revision. 99 This document defines a revision-label scheme that uses modified 100 [semver] rules for YANG artifacts (i.e., YANG modules, YANG 101 submodules, and YANG packages [I-D.ietf-netmod-yang-packages] ) as 102 well as the revision label definition for using this scheme. The 103 goal of this is to add a human readable version label that provides 104 compatibility information for the YANG artifact without one needing 105 to compare or parse its body. The label and rules defined herein 106 represent the RECOMMENDED revision label scheme for IETF YANG 107 artifacts. 109 Note that a specific revision of the Semver 2.0.0 specification is 110 referenced here (from June 19, 2020) to provide an immutable version. 111 This is because the 2.0.0 version of the specification has changed 112 over time without any change to the semantic version itself. In some 113 cases the text has changed in non-backwards-compatible ways. 115 2. Terminology and Conventions 117 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 118 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 119 "OPTIONAL" in this document are to be interpreted as described in BCP 120 14 [RFC2119] [RFC8174] when, and only when, they appear in all 121 capitals, as shown here. 123 Additionally, this document uses the following terminology: 125 * YANG artifact: YANG modules, YANG submodules, and YANG packages 126 [I-D.ietf-netmod-yang-packages] , and YANG schema elements are 127 examples of YANG artifacts for the purposes of this document. 129 3. YANG Semantic Versioning 131 This section defines YANG Semantic Versioning, explains how it is 132 used with YANG artifacts, and the rules associated with changing an 133 artifact's semantic version number when its contents are updated. 135 3.1. YANG Semantic Versioning Pattern 137 YANG artifacts that employ semantic versioning as defined in this 138 document MUST use a version string (e.g., in revision-label or as a 139 package version) that corresponds to the following pattern: 140 X.Y.Z_COMPAT. Where: 142 * X, Y and Z are mandatory non-negative integers that are each less 143 than 2147483647 (i.e., the maximum signed 32-bit integer value) 144 and MUST NOT contain leading zeroes 146 * The '.' is a literal period (ASCII character 0x2e) 148 * The '_' is an optional single literal underscore (ASCII character 149 0x5f) and MUST only present if the following COMPAT element is 150 included 152 * COMPAT, if it is specified, MUST be either the literal string 153 "compatible" or the literal string "non_compatible" 155 Additionally, [semver] defines two specific types of metadata that 156 may be appended to a semantic version string. Pre-release metadata 157 MAY be appended to a semver string after a trailing '-' character. 158 Build metadata MAY be appended after a trailing '+' character. If 159 both pre-release and build metadata are present, then build metadata 160 MUST follow pre-release metadata. While build metadata MUST be 161 ignored by YANG semver parsers, pre-release metadata MUST be used 162 during module and submodule development and MUST be considered base 163 on Section 5 . Both pre-release and build metadata are allowed in 164 order to support all of the [semver] rules. Thus, a version lineage 165 that follows strict [semver] rules is allowed for a YANG artifact. 167 To signal the use of this versioning scheme, modules and submodules 168 MUST set the revision-label-scheme extension as defined in 169 [I-D.ietf-netmod-yang-module-versioning] to the identity "yang- 170 semver". That identity value is defined in the ietf-yang-semver 171 module below. 173 Additionally, this ietf-yang-semver module defines a typedef that 174 formally specifies the syntax of the YANG semver version string. 176 3.2. Semantic Versioning Scheme for YANG Artifacts 178 This document defines the YANG semantic versioning scheme that is 179 used for YANG artifacts that employ the YANG semver label. The 180 versioning scheme has the following properties: 182 * The YANG semantic versioning scheme is extended from version 2.0.0 183 of the semantic versioning scheme defined at semver.org [semver] 184 to cover the additional requirements for the management of YANG 185 artifact lifecyles that cannot be addressed using the semver.org 186 2.0.0 versioning scheme alone. 188 * Unlike the [semver] versioning scheme, the YANG semantic 189 versioning scheme supports updates to older versions of YANG 190 artifacts, to allow for bug fixes and enhancements to artifact 191 versions that are not the latest. However, it does not provide 192 for the unlimited branching and updating of older revisions which 193 are documented by the general rules in 194 [I-D.ietf-netmod-yang-module-versioning] . 196 * YANG artifacts that follow the [semver] versioning scheme are 197 fully compatible with implementations that understand the YANG 198 semantic versioning scheme defined in this document. 200 * If updates are always restricted to the latest revision of the 201 artifact only, then the version numbers used by the YANG semantic 202 versioning scheme are exactly the same as those defined by the 203 [semver] versioning scheme. 205 Every YANG module and submodule versioned using the YANG semantic 206 versioning scheme specifies the module's or submodule's semantic 207 version number as the argument to the 'rev:revision-label' statement. 209 Because the rules put forth in 210 [I-D.ietf-netmod-yang-module-versioning] are designed to work well 211 with existing versions of YANG and allow for artifact authors to 212 migrate to this scheme, it is not expected that all revisions of a 213 given YANG artifact will have a semantic version label. For example, 214 the first revision of a module or submodule may have been produced 215 before this scheme was available. 217 YANG packages that make use of this semantic versioning scheme will 218 have their semantic version as the value of the "revision_label" 219 property. 221 As stated above, the YANG semver version number is expressed as a 222 string of the form: 'X.Y.Z_COMPAT'; where X, Y, and Z each represent 223 non-negative integers smaller than 2147483647 without leading zeroes, 224 and _COMPAT represents an optional suffix of either "_compatible" or 225 "_non_compatible". 227 * 'X' is the MAJOR version. Changes in the MAJOR version number 228 indicate changes that are non-backwards-compatible to versions 229 with a lower MAJOR version number. 231 * 'Y' is the MINOR version. Changes in the MINOR version number 232 indicate changes that are backwards-compatible to versions with 233 the same MAJOR version number, but a lower MINOR version number 234 and no PATCH "_compatible" or "_non_compatible" modifier. 236 * 'Z_COMPAT' is the PATCH version and modifier. Changes in the 237 PATCH version number can indicate editorial, backwards-compatible, 238 or non-backwards-compatible changes relative to versions with the 239 same MAJOR and MINOR version numbers, but lower PATCH version 240 number, depending on what form modifier "_COMPAT" takes: 242 - If the modifier string is absent, the change represents an 243 editorial change. An editorial change is defined to be a 244 change in the YANG artifact's content that does not affect the 245 semantic meaning or functionality provided by the artifact in 246 any way. Some examples include correcting a spelling mistake 247 in the description of a leaf within a YANG module or submodule, 248 non-significant whitespace changes (e.g. realigning 249 description statements, or changing indendation), or changes to 250 YANG comments. Note: restructuring how a module uses, or does 251 not use, submodules is treated as an editorial level change on 252 the condition that there is no change in the module's semantic 253 behavior due to the restructuring. 255 - If, however, the modifier string is present, the meaning is 256 described below: 258 - "_compatible" - the change represents a backwards-compatible 259 change 261 - "_non_compatible" - the change represents a non-backwards- 262 compatible change 264 The YANG artifact name and YANG semantic version number uniquely 265 identify a revision of said artifact. There MUST NOT be multiple 266 instances of a YANG artifact definition with the same name and YANG 267 semantic version number but different content (and in the case of 268 modules and submodules, different revision dates). 270 There MUST NOT be multiple versions of a YANG artifact that have the 271 same MAJOR, MINOR and PATCH version numbers, but different patch 272 modifier strings. E.g., artifact version "1.2.3_non_compatible" MUST 273 NOT be defined if artifact version "1.2.3" has already been defined. 275 3.2.1. Examples for YANG semantic version numbers 277 The following diagram and explanation illustrates how YANG semantic 278 version numbers work. 280 Example YANG semantic version numbers for an example artifact: 282 0.1.0 283 | 284 0.2.0 285 | 286 1.0.0 287 | \ 288 | 1.1.0 -> 1.1.1_compatible -> 1.1.2_non_compatible 289 | | 290 | 1.2.0 -> 1.2.1_non_compatible -> 1.2.2_non_compatible 291 | | 292 | 1.3.0 -> 1.3.1 293 | 294 2.0.0 295 | 296 3.0.0 297 \ 298 3.1.0 300 Assume the tree diagram above illustrates how an example YANG 301 module's version history might evolve. For example, the tree might 302 represent the following changes, listed in chronological order from 303 oldest revision to newest: 305 0.1.0 - first beta module version 307 0.2.0 - second beta module version (with NBC changes) 309 1.0.0 - first release (may have NBC changes from 0.2.0) 311 1.1.0 - added new functionality, leaf "foo" (BC) 313 1.2.0 - added new functionality, leaf "baz" (BC) 315 1.3.0 - improve existing functionality, added leaf "foo-64" (BC) 317 1.3.1 - improve description wording for "foo-64" (Editorial) 319 1.1.1_compatible - backport "foo-64" leaf to 1.1.x to avoid 320 implementing "baz" from 1.2.0 (BC) 322 2.0.0 - change existing model for performance reasons, e.g. re-key 323 list (NBC) 325 1.1.2_non_compatible - NBC point bug fix, not required in 2.0.0 326 due to model changes (NBC) 328 3.0.0 - NBC bugfix, rename "baz" to "bar"; also add new BC leaf 329 "wibble"; (NBC) 330 1.2.1_non_compatible - backport NBC fix, changing "baz" to "bar" 332 1.2.2_non_compatible - backport "wibble". This is a BC change but 333 "non_compatible" modifier is sticky. 335 3.1.0 - introduce new leaf "wobble" (BC) 337 The partial ordering relationships based on the semantic versioning 338 numbers can be defined as follows: 340 1.0.0 < 1.1.0 < 1.2.0 < 1.3.0 < 2.0.0 < 3.0.0 < 3.1.0 342 1.0.0 < 1.1.0 < 1.1.1_compatible < 1.1.2_non_compatible 344 1.0.0 < 1.1.0 < 1.2.0 < 1.2.1_non_compatible < 345 1.2.2_non_compatible 347 There is no ordering relationship between 1.1.1_non_compatible and 348 either 1.2.0 or 1.2.1_non_compatible, except that they share the 349 common ancestor of 1.1.0. 351 Looking at the version number alone, the module definition in 2.0.0 352 does not necessarily contain the contents of 1.3.0. However, the 353 module revision history in 2.0.0 may well indicate that it was edited 354 from module version 1.3.0. 356 3.3. YANG Semantic Version Update Rules 358 When a new revision of an artifact is produced, then the following 359 rules define how the YANG semantic version number for the new 360 artifact revision is calculated, based on the changes between the two 361 artifact revisions, and the YANG semantic version number of the base 362 artifact revision from which the changes are derived. 364 The following four rules specify the RECOMMENDED, and REQUIRED 365 minimum, update to a YANG semantic version number: 367 1. If an artifact is being updated in a non-backwards-compatible 368 way, then the artifact version 369 "X.Y.Z[_compatible|_non_compatible]" SHOULD be updated to 370 "X+1.0.0" unless that version has already been used for this 371 artifact but with different content, in which case the artifact 372 version "X.Y.Z+1_non_compatible" SHOULD be used instead. 374 2. If an artifact is being updated in a backwards-compatible way, 375 then the next version number depends on the format of the current 376 version number: 378 i "X.Y.Z" - the artifact version SHOULD be updated to 379 "X.Y+1.0", unless that version has already been used for 380 this artifact but with different content, when the artifact 381 version SHOULD be updated to "X.Y.Z+1_compatible"" instead. 383 ii "X.Y.Z_compatible" - the artifact version SHOULD be updated 384 to "X.Y.Z+1_compatible". 386 iii "X.Y.Z_non_compatible" - the artifact version SHOULD be 387 updated to "X.Y.Z+1_non_compatible". 389 3. If an artifact is being updated in an editorial way, then the 390 next version number depends on the format of the current version 391 number: 393 i "X.Y.Z" - the artifact version SHOULD be updated to 394 "X.Y.Z+1" 396 ii "X.Y.Z_compatible" - the artifact version SHOULD be updated 397 to "X.Y.Z+1_compatible". 399 iii "X.Y.Z_non_compatible" - the artifact version SHOULD be 400 updated to "X.Y.Z+1_non_compatible". 402 4. YANG artifact semantic version numbers beginning with 0, i.e., 403 "0.X.Y", are regarded as beta definitions and need not follow the 404 rules above. Either the MINOR or PATCH version numbers may be 405 updated, regardless of whether the changes are non-backwards- 406 compatible, backwards-compatible, or editorial. See Section 5 407 for more details on using this notation during module and 408 submodule development. 410 5. XXX - Add some text about pre-release labels, or perhaps as a 411 rule 5 above. 413 Although artifacts SHOULD be updated according to the rules above, 414 which specify the recommended (and minimum required) update to the 415 version number, the following rules MAY be applied when choosing a 416 new version number: 418 1. An artifact author MAY update the version number with a more 419 significant update than described by the rules above. For 420 example, an artifact could be given a new MAJOR version number 421 (i.e., X+1.0.0), even though no non-backwards-compatible changes 422 have occurred, or an artifact could be given a new MINOR version 423 number (i.e., X.Y+1.0) even if the changes were only editorial. 425 2. An artifact author MAY skip version numbers. That is, an 426 artifact's revision history could be 1.0.0, 1.1.0, and 1.3.0 427 where 1.2.0 is skipped. Note that skipping versions has an 428 impact when importing modules by revision-or-derived. See 429 Section 4 for more details on importing modules with revision- 430 label version gaps. 432 Although YANG Semver always indicates when a non-backwards- 433 compatible, or backwards-compatible change may have occurred to a 434 YANG artifact, it does not guarantee that such a change has occurred, 435 or that consumers of that YANG artifact will be impacted by the 436 change. Hence, tooling, e.g., 437 [I-D.ietf-netmod-yang-schema-comparison] , also plays an important 438 role for comparing YANG artifacts and calculating the likely impact 439 from changes. 441 [I-D.ietf-netmod-yang-module-versioning] defines the "rev:nbc- 442 changes" extension statement to indicate where non-backwards- 443 compatible changes have occurred in the module revision history. If 444 a revision entry in a module's revision history includes the 445 "rev:nbc-changes" statement then that MUST be reflected in any YANG 446 Semver version associated with that revision. However, the reverse 447 does not necessarily hold, i.e., if the MAJOR version has been 448 incremented it does not necessarily mean that a "rev:nbc-changes" 449 statement would be present. 451 3.4. Examples of the YANG Semver Label 453 3.4.1. Example Module Using YANG Semver 455 Below is a sample YANG module that uses the YANG semver revision 456 label based on the rules defined in this document. 458 module example-versioned-module { 459 yang-version 1.1; 460 namespace "urn:example:versioned:module"; 461 prefix "exvermod"; 462 rev:revision-label-scheme "yangver:yang-semver"; 464 import ietf-yang-revisions { prefix "rev"; } 465 import ietf-yang-semver { prefix "yangver"; } 467 description 468 "to be completed"; 470 revision 2018-02-28 { 471 description "Added leaf 'wobble'"; 472 rev:revision-label "3.1.0"; 474 } 476 revision 2017-12-31 { 477 description "Rename 'baz' to 'bar', added leaf 'wibble'"; 478 rev:revision-label "3.0.0"; 479 rev:nbc-changes; 480 } 482 revision 2017-10-30 { 483 description "Change the module structure"; 484 rev:revision-label "2.0.0"; 485 rev:nbc-changes; 486 } 488 revision 2017-08-30 { 489 description "Clarified description of 'foo-64' leaf"; 490 rev:revision-label "1.3.1"; 491 } 493 revision 2017-07-30 { 494 description "Added leaf foo-64"; 495 rev:revision-label "1.3.0"; 496 } 498 revision 2017-04-20 { 499 description "Add new functionality, leaf 'baz'"; 500 rev:revision-label "1.2.0"; 501 } 503 revision 2017-04-03 { 504 description "Add new functionality, leaf 'foo'"; 505 rev:revision-label "1.1.0"; 506 } 508 revision 2017-04-03 { 509 description "First release version."; 510 rev:revision-label "1.0.0"; 511 } 513 // Note: semver rules do not apply to 0.X.Y labels. 515 revision 2017-01-30 { 516 description "NBC changes to initial revision"; 517 semver:module-version "0.2.0"; 518 } 520 revision 2017-01-26 { 521 description "Initial module version"; 522 semver:module-version "0.1.0"; 523 } 525 //YANG module definition starts here 527 3.4.2. Example of Package Using YANG Semver 529 Below is an example YANG package that uses the semver revision label 530 based on the rules defined in this document. 532 { 533 "ietf-yang-instance-data:instance-data-set": { 534 "name": "example-yang-pkg", 535 "target-ptr": "TBD", 536 "timestamp": "2018-09-06T17:00:00Z", 537 "description": "Example IETF package definition", 538 "content-data": { 539 "ietf-yang-package:yang-package": { 540 "name": "example-yang-pkg", 541 "version": "1.3.1", 542 ... 543 } 545 4. Import Module by Semantic Version 547 [I-D.ietf-netmod-yang-module-versioning] allows for imports to be 548 done based on a module or a derived revision of a module. The 549 rev:revision-or-derived statement can specify either a revision date 550 or a revision label. When importing by semver, the YANG semver 551 revision label value MAY be used as an argument to rev:revision-or- 552 derived. When used as such, any module which has that semver label 553 as its latest revision label or has that label in its revision 554 history can be used to satisfy the import requirement. For example: 556 import example-module { 557 rev:revision-or-derived "3.0.0"; 558 } 560 Note: the import lookup does not stop when a non-backward-compatible 561 change is encountered. That is, if module B imports a module A at or 562 derived from version 2.0.0, resolving that import will pass through a 563 revision of module A with version 2.1.0_non_compatible in order to 564 determine if the present instance of module A derives from 2.0.0. 566 If an import by revision-or-derived cannot locate the specified 567 revision-label in a given module's revision history, that import will 568 fail. This is noted in the case of version gaps. That is, if a 569 module's history includes 1.0.0, 1.1.0, and 1.3.0, an import from 570 revision-or-derived at 1.2.0 will be unable to locate the specified 571 revision entry and thus the import cannot be satisfied. 573 5. Guidelines for Using Semver During Module Development 575 This section and the IETF-specific sub-section below provides YANG 576 semver-specific guidelines to consider when developing new YANG 577 modules. As such this section updates [RFC8407] . 579 Development of a brand new YANG module or submodule outside of the 580 IETF that uses YANG semver as its revision-label scheme SHOULD begin 581 with a 0 for the MAJOR version component. This allows the module or 582 submodule to disregard strict semver rules with respect to non- 583 backwards-compatible changes during its initial development. 584 However, module or submodule developers MAY choose to use the semver 585 pre-release syntax instead with a 1 for the MAJOR version component. 586 For example, an initial module or submodule revision-label might be 587 either 0.0.1 or 1.0.0-alpha.1. If the authors choose to use the 0 588 MAJOR version component scheme, they MAY switch to the pre-release 589 scheme with a MAJOR version component of 1 when the module or 590 submodule is nearing initial release (e.g., a module's or submodule's 591 revision label may transition from 0.3.0 to 1.0.0-beta.1 to indicate 592 it is more mature and ready for testing). 594 When using pre-release notation, the format MUST include at least one 595 alphabetic component and MUST end with a '.' and then one or more 596 digits. These alphanumeric components will be used when deciding 597 pre-release precedence. The following are examples of valid pre- 598 release versions 600 1.0.0-alpha.1 602 1.0.0-alpha.3 604 2.1.0-beta.42 606 3.0.0-202007.rc.1 608 When developing a new revision of an existing module or submodule 609 using the YANG semver revision-label scheme, the intended target 610 semver version MUST be used along with pre-release notation. For 611 example, if a released module or submodule which has a current 612 revision-label of 1.0.0 is being modified with the intent to make 613 non-backwards-compatible changes, the first development MAJOR version 614 component must be 2 with some pre-release notation such as -alpha.1, 615 making the version 2.0.0-alpha.1. That said, every publicly 616 available release of a module or submodule MUST have a unique YANG 617 semver revision-label (where a publicly available release is one that 618 could be implemented by a vendor or consumed by an end user). 619 Therefore, it may be prudent to include the year or year and month 620 development began (e.g., 2.0.0-201907-alpha.1). As a module or 621 submodule undergoes development, it is possible that the original 622 intent changes. For example, a 1.0.0 version of a module or 623 submodule that was destined to become 2.0.0 after a development cycle 624 may have had a scope change such that the final version has no non- 625 backwards-compatible changes and becomes 1.1.0 instead. This change 626 is acceptable to make during the development phase so long as pre- 627 release notation is present in both versions (e.g., 2.0.0-alpha.3 628 becomes 1.1.0-alpha.4). However, on the next development cycle 629 (after 1.1.0 is released), if again the new target release is 2.0.0, 630 new pre-release components must be used such that every revision- 631 label for a given module or submodule MUST be unique throughout its 632 entire lifecycle (e.g., the first pre-release version might be 633 2.0.0-202005-alpha.1 if keeping the same year and month notation 634 mentioned above). 636 5.1. Pre-release Version Precedence 638 As a module or submodule is developed, the scope of the work may 639 change. That is, while a ratified module or submodule with revision- 640 label 1.0.0 is initially intended to become 2.0.0 in its next 641 ratified version, the scope of work may change such that the final 642 version is 1.1.0. During the development cycle, the pre-release 643 versions could move from 2.0.0-some-pre-release-tag to 1.1.0-some- 644 pre-release-tag. This downwards changing of version numbers makes it 645 difficult to evaluate semver rules between pre-release versions. 646 However, taken independently, each pre-release version can be 647 compared to the previously ratified version (e.g., 1.1.0-some-pre- 648 release-tag and 2.0.0-some-pre-release-tag can each be compared to 649 1.0.0). Module and submodule developers SHOULD maintain only one 650 revision statement in a pre-released module or submodule that 651 reflects the latest revision. IETF authors MAY choose to include an 652 appendix in the associated draft to track overall changes to the 653 module or submodule. 655 5.2. YANG Semver in IETF Modules 657 All published IETF modules and submodules MUST use YANG semantic 658 versions for their revision-labels. For IETF YANG modules and 659 submodules that have already been published, revision labels MUST be 660 retrospectively applied to all existing revisions when the next new 661 revision is created, starting at version "1.0.0" for the initial 662 published revision, and then incrementing according to the YANG 663 Semver version rules specified in Section 3.3 . 665 Net new module or submodule development within the IETF SHOULD begin 666 with the 0 MAJOR number scheme as described above. When revising an 667 existing IETF module or submodule, the revision-label MUST use the 668 target (i.e., intended) MAJOR and MINOR version components with a 0 669 PATCH version component. If the intended ratified release will be 670 non-backward-compatible with the current ratified release, the MINOR 671 version component MUST be 0. 673 All IETF modules and submodules in development MUST use the whole 674 document name as a pre-release version string, including the current 675 document revision. For example, if a module or submodule which is 676 currently released at version 1.0.0 is being revised to include non- 677 backwards-compatible changes in draft-user-netmod-foo, its 678 development revision-labels MUST include 2.0.0-draft-user-netmod-foo 679 followed by the document's revision (e.g., 2.0.0-draft-user-netmod- 680 foo-02). This will ensure each pre-release version is unique across 681 the lifecycle of the module or submodule. Even when using the 0 682 MAJOR version for initial module or submodule development (where 683 MINOR and PATCH can change), appending the draft name as a pre- 684 release component helps to ensure uniqueness when there are perhaps 685 multiple, parallel efforts creating the same module or submodule. 687 If a module or submodule is being revised and the original module or 688 submodule never had a revision-label (i.e., you wish to start using 689 YANG semver in future module or submodule revisions), choose a semver 690 value that makes the most sense based on the module's or submodule's 691 history. For example, if a module or submodule started out in the 692 pre-NMDA ([RFC8342] ) world, and then had NMDA support added without 693 removing any legacy "state" branches -- and you are looking to add 694 additional new features -- a sensible choice for the target YANG 695 semver would be 1.2.0 (since 1.0.0 would have been the initial, pre- 696 NMDA release, and 1.1.0 would have been the NMDA revision). 698 See Appendix A for a detailed example of IETF pre-release versions. 700 6. YANG Module 702 This YANG module contains the typedef for the YANG semantic version. 704 file "ietf-yang-semver@2020-06-30.yang" 705 module ietf-yang-semver { 706 yang-version 1.1; 707 namespace "urn:ietf:params:xml:ns:yang:ietf-yang-semver"; 708 prefix yangver; 709 rev:revision-label-scheme "yang-semver"; 711 import ietf-yang-revisions { 712 prefix rev; 713 } 715 organization 716 "IETF NETMOD (Network Modeling) Working Group"; 717 contact 718 "WG Web: 719 WG List: 721 Author: Joe Clarke 722 "; 723 description 724 "This module provides type and grouping definitions for YANG 725 packages. 727 Copyright (c) 2020 IETF Trust and the persons identified as 728 authors of the code. All rights reserved. 730 Redistribution and use in source and binary forms, with or 731 without modification, is permitted pursuant to, and subject 732 to the license terms contained in, the Simplified BSD License 733 set forth in Section 4.c of the IETF Trust's Legal Provisions 734 Relating to IETF Documents 735 (http://trustee.ietf.org/license-info). 737 This version of this YANG module is part of RFC XXXX; see 738 the RFC itself for full legal notices."; 740 // RFC Ed.: update the date below with the date of RFC publication 741 // and remove this note. 742 // RFC Ed.: replace XXXX with actual RFC number and remove this 743 // note. 745 revision 2020-06-30 { 746 rev:revision-label "1.0.0-draft-ietf-netmod-yang-semver-01"; 747 description 748 "Initial revision"; 749 reference 750 "RFC XXXX: YANG Semantic Versioning."; 751 } 753 /* 754 * Identities 755 */ 757 identity yang-semver { 758 base rev:revision-label-scheme-base-identity; 759 description 760 "The revision-label scheme corresponds to the YANG semver scheme 761 which is defined by the pattern in the 'version' typedef below. 762 The rules governing this revision-label scheme are defined in the 763 reference for this identity."; 764 reference 765 "RFC XXXX: YANG Semantic Versioning."; 766 } 768 /* 769 * Typedefs 770 */ 772 typedef version { 773 type string { 774 pattern '\d+[.]\d+[.]\d+(_(non_)?compatible)?(-[\w\d.]+)?([+][\w\d\.]+)?'; 775 } 776 description 777 "Represents a YANG semantic version number. The rules governing the 778 use of this revision label scheme are defined in the reference for 779 this typedef."; 780 reference 781 "RFC XXXX: YANG Semantic Versioning."; 782 } 783 } 784 786 7. Contributors 788 This document grew out of the YANG module versioning design team that 789 started after IETF 101. The design team consists of the following 790 members whom have worked on the YANG versioning project: 792 * Balazs Lengyel 794 * Benoit Claise 795 * Ebben Aries 797 * Jason Sterne 799 * Joe Clarke 801 * Juergen Schoenwaelder 803 * Mahesh Jethanandani 805 * Michael (Wangzitao) 807 * Qin Wu 809 * Reshad Rahman 811 * Rob Wilton 813 The initial revision of this document was refactored and built upon 814 [I-D.clacla-netmod-yang-model-update] . 816 Discussons on the use of Semver for YANG versioning has been held 817 with authors of the OpenConfig YANG models based on their own 818 [openconfigsemver] . We would like thank both Anees Shaikh and Rob 819 Shakir for their input into this problem space. 821 8. Security Considerations 823 The document does not define any new protocol or data model. There 824 are no security impacts. 826 9. IANA Considerations 828 9.1. YANG Module Registrations 830 The following YANG module is requested to be registred in the "IANA 831 Module Names" registry: 833 Name: ietf-yang-semver 835 XML Namespace: urn:ietf:params:xml:ns:yang:ietf-yang-semver 837 Prefix: yangver 839 Reference: [RFCXXXX] 841 9.2. Guidance for YANG Semver in IANA maintained YANG modules and 842 submodules 844 Note for IANA (to be removed by the RFC editor): Please check that 845 the registries and IANA YANG modules and submodules are referenced in 846 the appropriate way. 848 IANA is responsible for maintaining and versioning some YANG modules 849 and submodules, e.g., iana-if-types.yang [IfTypeYang] and iana- 850 routing-types.yang [RoutingTypesYang] . 852 In addition to following the rules specified in the IANA 853 Considerations section of [I-D.ietf-netmod-yang-module-versioning] , 854 IANA maintained YANG modules and submodules MUST also include a YANG 855 Semver revision label for all new revisions, as defined in Section 3 856 . 858 The YANG Semver version associated with the new revision MUST follow 859 the rules defined in Section 3.3 . 861 Note: For IANA maintained YANG modules and submodules that have 862 already been published, revision labels MUST be retrospectively 863 applied to all existing revisions when the next new revision is 864 created, starting at version "1.0.0" for the initial published 865 revision, and then incrementing according to the YANG Semver version 866 rules specified in Section 3.3 . 868 Most changes to IANA maintained YANG modules and submodules are 869 expected to be backwards-compatible changes and classified as MINOR 870 version changes. The PATCH version may be incremented instead when 871 only editorial changes are made, and the MAJOR version would be 872 incremented if non-backwards-compatible major changes are made. 874 Given that IANA maintained YANG modules and submodules are versioned 875 with a linear history, it is anticipated that it should not be 876 necessary to use the "_compatible" or "_non_compatible" modifiers to 877 the "Z_COMPAT" version element. 879 10. References 881 10.1. Normative References 883 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 884 Requirement Levels", BCP 14, RFC 2119, 885 DOI 10.17487/RFC2119, March 1997, 886 . 888 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 889 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 890 May 2017, . 892 [RFC8407] Bierman, A., "Guidelines for Authors and Reviewers of 893 Documents Containing YANG Data Models", BCP 216, RFC 8407, 894 DOI 10.17487/RFC8407, October 2018, 895 . 897 [I-D.ietf-netmod-yang-module-versioning] 898 Wilton, R., Rahman, R., Lengyel, B., Clarke, J., Sterne, 899 J., Claise, B., and K. D'Souza, "Updated YANG Module 900 Revision Handling", Work in Progress, Internet-Draft, 901 draft-ietf-netmod-yang-module-versioning-02, 22 February 902 2021, . 905 10.2. Informative References 907 [I-D.clacla-netmod-yang-model-update] 908 Claise, B., Clarke, J., Lengyel, B., and K. D'Souza, "New 909 YANG Module Update Procedure", Work in Progress, Internet- 910 Draft, draft-clacla-netmod-yang-model-update-06, 2 July 911 2018, . 914 [I-D.ietf-netmod-yang-packages] 915 Wilton, R., Rahman, R., Clarke, J., Sterne, J., and B. Wu, 916 "YANG Packages", Work in Progress, Internet-Draft, draft- 917 ietf-netmod-yang-packages-01, 2 November 2020, 918 . 921 [I-D.ietf-netmod-yang-schema-comparison] 922 Wilton, R., "YANG Schema Comparison", Work in Progress, 923 Internet-Draft, draft-ietf-netmod-yang-schema-comparison- 924 01, 2 November 2020, . 927 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 928 and R. Wilton, "Network Management Datastore Architecture 929 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 930 . 932 [openconfigsemver] 933 "Semantic Versioning for Openconfig Models", 934 . 936 [semver] "Semantic Versioning 2.0.0 (text from June 19, 2020)", 937 . 940 [IfTypeYang] 941 "iana-if-type YANG Module", 942 . 945 [RoutingTypesYang] 946 "iana-routing-types YANG Module", 947 . 950 Appendix A. Example IETF Module Development 952 Assume a new YANG module is being developed in the netmod working 953 group in the IETF. Initially, this module is being developed in an 954 individual internet draft, draft-jdoe-netmod-example-module. The 955 following represents the initial version tree (i.e., value of 956 revision-label) of the module as it's being initially developed. 958 Version lineage for initial module development: 960 0.0.1-draft-jdoe-netmod-example-module-00 961 | 962 0.1.0-draft-jdoe-netmod-example-module-01 963 | 964 0.2.0-draft-jdoe-netmod-example-module-02 965 | 966 0.2.1-draft-jdoe-netmod-example-module-03 968 At this point, development stabilizes, and the workgroup adopts the 969 draft. Thus now the draft becomes draft-ietf-netmod-example-module. 970 The initial pre-release lineage continues as follows. 972 Continued version lineage after adoption: 974 1.0.0-draft-ietf-netmod-example-module-00 975 | 976 1.0.0-draft-ietf-netmod-example-module-01 977 | 978 1.0.0-draft-ietf-netmod-example-module-02 980 At this point, the draft is ratified and becomes RFC12345 and the 981 YANG module version number becomes 1.0.0. 983 A time later, the module needs to be revised to add additional 984 capabilities. Development will be done in a backwards-compatible 985 way. Two new individual drafts are proposed to go about adding the 986 capabilities in different ways: draft-jdoe-netmod-exmod-enhancements 987 and draft-jadoe-netmod-exmod-changes. These are initially developed 988 in parallel with the following versions. 990 Parallel development for next module revision: 992 1.1.0-draft-jdoe-netmod-exmod-enhancements-00 || 1.1.0-draft-jadoe-netmod-exmod-changes-00 993 | | 994 1.1.0-draft-jdoe-netmod-exmod-enhancements-01 || 1.1.0-draft-jadoe-netmod-exmod-changes-01 996 At this point, the WG decides to merge some aspects of both and adopt 997 the work in jadoe's draft as draft-ietf-netmod-exmod-changes. A 998 single version lineage continues. 1000 1.1.0-draft-ietf-netmod-exmod-changes-00 1001 | 1002 1.1.0-draft-ietf-netmod-exmod-changes-01 1003 | 1004 1.1.0-draft-ietf-netmod-exmod-changes-02 1005 | 1006 1.1.0-draft-ietf-netmod-exmod-changes-03 1008 The draft is ratified, and the new module version becomes 1.1.0. 1010 Authors' Addresses 1012 Benoit Claise 1013 Huawei 1015 Email: benoit.claise@huawei.com 1017 Joe Clarke (editor) 1018 Cisco Systems, Inc. 1019 7200-12 Kit Creek Rd 1020 Research Triangle Park, North Carolina 1021 United States of America 1023 Phone: +1-919-392-2867 1024 Email: jclarke@cisco.com 1026 Reshad Rahman 1027 Cisco Systems, Inc. 1029 Email: rrahman@cisco.com 1031 Robert Wilton (editor) 1032 Cisco Systems, Inc. 1034 Email: rwilton@cisco.com 1036 Balazs Lengyel 1037 Ericsson 1038 1117 Budapest 1039 Magyar Tudosok Korutja 1040 Hungary 1042 Phone: +36-70-330-7909 1043 Email: balazs.lengyel@ericsson.com 1045 Jason Sterne 1046 Nokia 1048 Email: jason.sterne@nokia.com 1050 Kevin D'Souza 1051 AT&T 1052 200 S. Laurel Ave 1053 Middletown, NJ 1054 United States of America 1056 Email: kd6913@att.com