idnits 2.17.1 draft-ietf-netmod-yang-semver-06.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 (30 November 2021) is 872 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 918, but not defined == Outdated reference: A later version (-11) exists of draft-ietf-netmod-yang-module-versioning-05 == 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: 3 June 2022 7 B. Lengyel 8 Ericsson 9 J. Sterne 10 Nokia 11 B. Claise 12 Huawei 13 30 November 2021 15 YANG Semantic Versioning 16 draft-ietf-netmod-yang-semver-06 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 3 June 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'. 230 * 'X' is the MAJOR version. Changes in the MAJOR version number 231 indicate changes that are non-backwards-compatible to versions 232 with a lower MAJOR version number. 234 * 'Y' is the MINOR version. Changes in the MINOR version number 235 indicate changes that are backwards-compatible to versions with 236 the same MAJOR version number, but a lower MINOR version number 237 and no PATCH "_compatible" or "_non_compatible" modifier. 239 * 'Z_COMPAT' is the PATCH version and modifier. Changes in the 240 PATCH version number can indicate editorial, backwards-compatible, 241 or non-backwards-compatible changes relative to versions with the 242 same MAJOR and MINOR version numbers, but lower PATCH version 243 number, depending on what form modifier '_COMPAT' takes: 245 - If the modifier string is absent, the change represents an 246 editorial change. An editorial change is defined to be a 247 change in the YANG artifact's content that does not affect the 248 semantic meaning or functionality provided by the artifact in 249 any way. Some examples include correcting a spelling mistake 250 in the description of a leaf within a YANG module or submodule, 251 non-significant whitespace changes (e.g., realigning 252 description statements or changing indendation), or changes to 253 YANG comments. Note: restructuring how a module uses, or does 254 not use, submodules is treated as an editorial level change on 255 the condition that there is no change in the module's semantic 256 behavior due to the restructuring. 258 - If, however, the modifier string is present, the meaning is 259 described below: 261 - "_compatible" - the change represents a backwards-compatible 262 change 264 - "_non_compatible" - the change represents a non-backwards- 265 compatible change 267 The '_COMPAT' modifier string is "sticky". Once a revision of a 268 module has a modifier in the revision label, then all descendants of 269 that revision with the same X.Y version digits will also have a 270 modifier. The modifier can change from "_compatible" to 271 "_non_compatible" in a descendant revision, but the modifier MUST NOT 272 change from "_non_compatible" to "_compatible" and MUST NOT be 273 removed. The persistence of the "_non_compatible" modifier ensures 274 that comparisions of revision labels do not give the false impression 275 of compatibility between two potentially non-compatible revisions. 276 If "_non_compatible" was removed, for example between revisions 277 "3.3.2_non_compatible" and "3.3.3" (where "3.3.3" was simply an 278 editorial change), then comparing revision labels of "3.3.3" back to 279 an ancestor "3.0.0" would look like they are backwards compatible 280 when they are not (since "3.3.2_non_compatible" was in the chain of 281 ancestors and introduced a non-backwards-compatible change). 283 The YANG artifact name and YANG semantic version uniquely identify a 284 revision of said artifact. There MUST NOT be multiple instances of a 285 YANG artifact definition with the same name and YANG semantic version 286 but different content (and in the case of modules and submodules, 287 different revision dates). 289 There MUST NOT be multiple versions of a YANG artifact that have the 290 same MAJOR, MINOR and PATCH version numbers, but different patch 291 modifier strings. E.g., artifact version "1.2.3_non_compatible" MUST 292 NOT be defined if artifact version "1.2.3" has already been defined. 294 3.2.1. YANG Semver with submodules 296 YANG Semver MAY be used to version submodules. Submodule version are 297 separate of any version on the including module, but if a submodule 298 has changed, then the version of the including module MUST also be 299 updated. 301 The rules for determining the version change of a submodule are the 302 same as those defined in Section 3.1 and Section 3.2 as applied to 303 YANG modules, except they only apply to the part of the module schema 304 defined within the submodule's file. 306 One interesting case is moving definitions from one submodule to 307 another in a way that does not change the resultant schema of the 308 including module. In this case: 310 1. The including module has editorial changes 312 2. The submodule with the schema definition removed has non- 313 backwards-compatible changes 315 3. The submodule with the schema definitions added has backwards- 316 compatible changes 318 Note that the meaning of a submodule may change drastically despite 319 having no changes in content or revision due to changes in other 320 submodules belonging to the same module (e.g. groupings and typedefs 321 declared in one submodule and used in another). 323 3.2.2. Examples for YANG semantic versions 325 The following diagram and explanation illustrate how YANG semantic 326 versions work. 328 YANG Semantic versions for an example module: 330 0.1.0 331 | 332 0.2.0 333 | 334 1.0.0 335 | 336 1.1.0 -> 1.1.1_compatible -> 1.1.2_non_compatible 337 | 338 1.2.0 -> 1.2.1_non_compatible -> 1.2.2_non_compatible 339 | \ 340 2.0.0 \ 341 | \--> 1.3.0 -> 1.3.1_non_compatible 342 3.0.0 | 343 | 1.4.0 344 3.1.0 346 The tree diagram above illustrates how the version history might 347 evolve for an example module. The tree diagram only shows the 348 parent/child ancestry relationships between the revisions. It does 349 not describe the chronology of the revisions (i.e. when in time each 350 revision was published relative to the other revisions). 352 The following description lists an example of what the chronological 353 order of the revisions could look like, from oldest revision to 354 newest: 356 0.1.0 - first pre-release module version 358 0.2.0 - second pre-release module version (with NBC changes) 360 1.0.0 - first release (may have NBC changes from 0.2.0) 362 1.1.0 - added new functionality, leaf "foo" (BC) 364 1.2.0 - added new functionality, leaf "baz" (BC) 366 2.0.0 - change existing model for performance reasons, e.g. re-key 367 list (NBC) 369 1.3.0 - improve existing functionality, added leaf "foo-64" (BC) 371 1.1.1_compatible - backport "foo-64" leaf to 1.1.x to avoid 372 implementing "baz" from 1.2.0. This revision was created after 373 1.2.0 otherwise it may have been released as 1.2.0. (BC) 375 3.0.0 - NBC bugfix, rename "baz" to "bar"; also add new BC leaf 376 "wibble"; (NBC) 377 1.3.1_non_compatible - backport NBC fix, rename "baz" to "bar" 378 (NBC) 380 1.2.1_non_compatible - backport NBC fix, rename "baz" to "bar" 381 (NBC) 383 1.1.2_non_compatible - NBC point bug fix, not required in 2.0.0 384 due to model changes (NBC) 386 1.4.0 - introduce new leaf "ghoti" (BC) 388 3.1.0 - introduce new leaf "wobble" (BC) 390 1.2.2_non_compatible - backport "wibble". This is a BC change but 391 "non_compatible" modifier is sticky. (BC) 393 The partial ancestry relationships based on the semantic versioning 394 numbers are as follows: 396 1.0.0 < 1.1.0 < 1.2.0 < 2.0.0 < 3.0.0 < 3.1.0 398 1.0.0 < 1.1.0 < 1.1.1_compatible < 1.1.2_non_compatible 400 1.0.0 < 1.1.0 < 1.2.0 < 1.2.1_non_compatible < 401 1.2.2_non_compatible 403 1.0.0 < 1.1.0 < 1.2.0 < 1.3.0 < 1.3.1_non_compatible 405 1.0.0 < 1.1.0 < 1.2.0 < 1.3.0 < 1.4.0 407 There is no ordering relationship between "1.1.1_non_compatible" and 408 either "1.2.0" or "1.2.1_non_compatible", except that they share the 409 common ancestor of "1.1.0". 411 Looking at the version number alone does not indicate ancestry. The 412 module definition in "2.0.0", for example, does not contain all the 413 contents of "1.3.0". Version "2.0.0" is not derived from "1.3.0". 415 3.3. YANG Semantic Version Update Rules 417 When a new revision of an artifact is produced, then the following 418 rules define how the YANG semantic version for the new artifact 419 revision is calculated, based on the changes between the two artifact 420 revisions, and the YANG semantic version of the base artifact 421 revision from which the changes are derived. 423 The following four rules specify the RECOMMENDED, and REQUIRED 424 minimum, update to a YANG semantic version: 426 1. If an artifact is being updated in a non-backwards-compatible 427 way, then the artifact version 428 "X.Y.Z[_compatible|_non_compatible]" SHOULD be updated to 429 "X+1.0.0" unless that version has already been used for this 430 artifact but with different content, in which case the artifact 431 version "X.Y.Z+1_non_compatible" SHOULD be used instead. 433 2. If an artifact is being updated in a backwards-compatible way, 434 then the next version number depends on the format of the current 435 version number: 437 i "X.Y.Z" - the artifact version SHOULD be updated to 438 "X.Y+1.0", unless that version has already been used for 439 this artifact but with different content, when the artifact 440 version SHOULD be updated to "X.Y.Z+1_compatible" instead. 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 3. If an artifact is being updated in an editorial way, then the 449 next version number depends on the format of the current version 450 number: 452 i "X.Y.Z" - the artifact version SHOULD be updated to 453 "X.Y.Z+1" 455 ii "X.Y.Z_compatible" - the artifact version SHOULD be updated 456 to "X.Y.Z+1_compatible". 458 iii "X.Y.Z_non_compatible" - the artifact version SHOULD be 459 updated to "X.Y.Z+1_non_compatible". 461 4. YANG artifact semantic version numbers beginning with 0, i.e., 462 "0.X.Y", are regarded as pre-release definitions and need not 463 follow the rules above. Either the MINOR or PATCH version 464 numbers may be updated, regardless of whether the changes are 465 non-backwards-compatible, backwards-compatible, or editorial. 466 See Section 5 for more details on using this notation during 467 module and submodule development. 469 5. Additional pre-release rules for modules that have had at least 470 one release are specified in Section 5 . 472 Although artifacts SHOULD be updated according to the rules above, 473 which specify the recommended (and minimum required) update to the 474 version number, the following rules MAY be applied when choosing a 475 new version number: 477 1. An artifact author MAY update the version number with a more 478 significant update than described by the rules above. For 479 example, an artifact could be given a new MAJOR version number 480 (i.e., X+1.0.0), even though no non-backwards-compatible changes 481 have occurred, or an artifact could be given a new MINOR version 482 number (i.e., X.Y+1.0) even if the changes were only editorial. 484 2. An artifact author MAY skip version numbers. That is, an 485 artifact's revision history could be 1.0.0, 1.1.0, and 1.3.0 486 where 1.2.0 is skipped. Note that skipping versions has an 487 impact when importing modules by revision-or-derived. See 488 Section 4 for more details on importing modules with revision- 489 label version gaps. 491 Although YANG Semver always indicates when a non-backwards- 492 compatible, or backwards-compatible change may have occurred to a 493 YANG artifact, it does not guarantee that such a change has occurred, 494 or that consumers of that YANG artifact will be impacted by the 495 change. Hence, tooling, e.g., 496 [I-D.ietf-netmod-yang-schema-comparison] , also plays an important 497 role for comparing YANG artifacts and calculating the likely impact 498 from changes. 500 [I-D.ietf-netmod-yang-module-versioning] defines the "rev:non- 501 backwards-compatible" extension statement to indicate where non- 502 backwards-compatible changes have occurred in the module revision 503 history. If a revision entry in a module's revision history includes 504 the "rev:non-backwards-compatible" statement then that MUST be 505 reflected in any YANG semantic version associated with that revision. 506 However, the reverse does not necessarily hold, i.e., if the MAJOR 507 version has been incremented it does not necessarily mean that a 508 "rev:non-backwards-compatible" statement would be present. 510 3.4. Examples of the YANG Semver Label 512 3.4.1. Example Module Using YANG Semver 514 Below is a sample YANG module that uses the YANG Semver revision- 515 label based on the rules defined in this document. 517 module example-versioned-module { 518 yang-version 1.1; 519 namespace "urn:example:versioned:module"; 520 prefix "exvermod"; 521 rev:revision-label-scheme "ysver:yang-semver"; 523 import ietf-yang-revisions { prefix "rev"; } 524 import ietf-yang-semver { prefix "ysver"; } 526 description 527 "to be completed"; 529 revision 2017-08-30 { 530 description "Backport 'wibble' leaf"; 531 rev:revision-label 1.2.2_non_compatible; 532 } 534 revision 2017-07-30 { 535 description "Rename 'baz' to 'bar'"; 536 rev:revision-label 1.2.1_non_compatible; 537 rev:non-backwards-compatible; 538 } 540 revision 2017-04-20 { 541 description "Add new functionality, leaf 'baz'"; 542 rev:revision-label 1.2.0; 543 } 545 revision 2017-04-03 { 546 description "Add new functionality, leaf 'foo'"; 547 rev:revision-label 1.1.0; 548 } 550 revision 2017-02-07 { 551 description "First release version."; 552 rev:revision-label 1.0.0; 553 } 555 // Note: semver rules do not apply to 0.X.Y labels. 556 // The following pre-release revision statements would not 557 // appear in any final published version of a module. They 558 // are removed when the final version is published. 559 // During the pre-release phase of development, only a 560 // single one of these revision statements would appear 562 // revision 2017-01-30 { 563 // description "NBC changes to initial revision"; 564 // rev:revision-label 0.2.0; 565 // rev:non-backwards-compatible; // optional 566 // // (theoretically no 567 // // 'previous released version') 568 // } 570 // revision 2017-01-26 { 571 // description "Initial module version"; 572 // rev:revision-label 0.1.0; 573 // } 575 //YANG module definition starts here 576 } 578 3.4.2. Example of Package Using YANG Semver 580 Below is an example YANG package that uses the semver revision label 581 based on the rules defined in this document. 583 { 584 "ietf-yang-instance-data:instance-data-set": { 585 "name": "example-yang-pkg", 586 "target-ptr": "TBD", 587 "timestamp": "2018-09-06T17:00:00Z", 588 "description": "Example IETF package definition", 589 "content-data": { 590 "ietf-yang-package:yang-package": { 591 "name": "example-yang-pkg", 592 "version": "1.3.1", 593 ... 594 } 596 4. Import Module by Semantic Version 598 [I-D.ietf-netmod-yang-module-versioning] allows for imports to be 599 done based on a module or a derived revision of a module. The 600 rev:revision-or-derived statement can specify either a revision date 601 or a revision label. The YANG Semver revision-label value can be 602 used as the argument to rev:revision-or-derived . When used as such, 603 any module that contains exactly the same YANG semantic version in 604 its revision history may be used to satisfy the import requirement. 605 For example: 607 import example-module { 608 rev:revision-or-derived 3.0.0; 609 } 611 Note: the import lookup does not stop when a non-backward-compatible 612 change is encountered. That is, if module B imports a module A at or 613 derived from version 2.0.0, resolving that import will pass through a 614 revision of module A with version "2.1.0_non_compatible" in order to 615 determine if the present instance of module A derives from "2.0.0". 617 If an import by revision-or-derived cannot locate the specified 618 revision-label in a given module's revision history, that import will 619 fail. This is noted in the case of version gaps. That is, if a 620 module's history includes "1.0.0", "1.1.0", and "1.3.0", an import 621 from revision-or-derived at "1.2.0" will be unable to locate the 622 specified revision entry and thus the import cannot be satisfied. 624 5. Guidelines for Using Semver During Module Development 626 This section and the IETF-specific sub-section below provides YANG 627 Semver-specific guidelines to consider when developing new YANG 628 modules. As such this section updates [RFC8407] . 630 Development of a brand new YANG module or submodule outside of the 631 IETF that uses YANG Semver as its revision-label scheme SHOULD begin 632 with a 0 for the MAJOR version component. This allows the module or 633 submodule to disregard strict semver rules with respect to non- 634 backwards-compatible changes during its initial development. 635 However, module or submodule developers MAY choose to use the semver 636 pre-release syntax instead with a 1 for the MAJOR version component. 637 For example, an initial module or submodule revision-label might be 638 either 0.0.1 or 1.0.0-alpha.1. If the authors choose to use the 0 639 MAJOR version component scheme, they MAY switch to the pre-release 640 scheme with a MAJOR version component of 1 when the module or 641 submodule is nearing initial release (e.g., a module's or submodule's 642 revision label may transition from 0.3.0 to 1.0.0-beta.1 to indicate 643 it is more mature and ready for testing). 645 When using pre-release notation, the format MUST include at least one 646 alphabetic component and MUST end with a '.' or '-' and then one or 647 more digits. These alphanumeric components will be used when 648 deciding pre-release precedence. The following are examples of valid 649 pre-release versions 651 1.0.0-alpha.1 653 1.0.0-alpha.3 655 2.1.0-beta.42 657 3.0.0-202007.rc.1 659 When developing a new revision of an existing module or submodule 660 using the YANG semver revision-label scheme, the intended target 661 semver version MUST be used along with pre-release notation. For 662 example, if a released module or submodule which has a current 663 revision-label of 1.0.0 is being modified with the intent to make 664 non-backwards-compatible changes, the first development MAJOR version 665 component must be 2 with some pre-release notation such as -alpha.1, 666 making the version 2.0.0-alpha.1. That said, every publicly 667 available release of a module or submodule MUST have a unique YANG 668 semver revision-label (where a publicly available release is one that 669 could be implemented by a vendor or consumed by an end user). 670 Therefore, it may be prudent to include the year or year and month 671 development began (e.g., 2.0.0-201907-alpha.1). As a module or 672 submodule undergoes development, it is possible that the original 673 intent changes. For example, a 1.0.0 version of a module or 674 submodule that was destined to become 2.0.0 after a development cycle 675 may have had a scope change such that the final version has no non- 676 backwards-compatible changes and becomes 1.1.0 instead. This change 677 is acceptable to make during the development phase so long as pre- 678 release notation is present in both versions (e.g., 2.0.0-alpha.3 679 becomes 1.1.0-alpha.4). However, on the next development cycle 680 (after 1.1.0 is released), if again the new target release is 2.0.0, 681 new pre-release components must be used such that every revision- 682 label for a given module or submodule MUST be unique throughout its 683 entire lifecycle (e.g., the first pre-release version might be 684 2.0.0-202005-alpha.1 if keeping the same year and month notation 685 mentioned above). 687 5.1. Pre-release Version Precedence 689 As a module or submodule is developed, the scope of the work may 690 change. That is, while a ratified module or submodule with revision- 691 label 1.0.0 is initially intended to become 2.0.0 in its next 692 ratified version, the scope of work may change such that the final 693 version is 1.1.0. During the development cycle, the pre-release 694 versions could move from 2.0.0-some-pre-release-tag to 1.1.0-some- 695 pre-release-tag. This downwards changing of version numbers makes it 696 difficult to evaluate semver rules between pre-release versions. 697 However, taken independently, each pre-release version can be 698 compared to the previously ratified version (e.g., 1.1.0-some-pre- 699 release-tag and 2.0.0-some-pre-release-tag can each be compared to 700 1.0.0). Module and submodule developers SHOULD maintain only one 701 revision statement in a pre-released module or submodule that 702 reflects the latest revision. IETF authors MAY choose to include an 703 appendix in the associated draft to track overall changes to the 704 module or submodule. 706 5.2. YANG Semver in IETF Modules 708 All published IETF modules and submodules MUST use YANG semantic 709 versions for their revision-labels. 711 Development of a new module or submodule within the IETF SHOULD begin 712 with the 0 MAJOR number scheme as described above. When revising an 713 existing IETF module or submodule, the revision-label MUST use the 714 target (i.e., intended) MAJOR and MINOR version components with a 0 715 PATCH version component. If the intended ratified release will be 716 non-backward-compatible with the current ratified release, the MINOR 717 version component MUST be 0. 719 All IETF modules and submodules in development MUST use the whole 720 document name as a pre-release version string, including the current 721 document revision. For example, if a module or submodule which is 722 currently released at version 1.0.0 is being revised to include non- 723 backwards-compatible changes in draft-user-netmod-foo, its 724 development revision-labels MUST include 2.0.0-draft-user-netmod-foo 725 followed by the document's revision (e.g., 2.0.0-draft-user-netmod- 726 foo-02). This will ensure each pre-release version is unique across 727 the lifecycle of the module or submodule. Even when using the 0 728 MAJOR version for initial module or submodule development (where 729 MINOR and PATCH can change), appending the draft name as a pre- 730 release component helps to ensure uniqueness when there are perhaps 731 multiple, parallel efforts creating the same module or submodule. 733 For IETF YANG modules and submodules that have already been 734 published, revision-labels MUST be retroactively applied to all 735 existing revisions when the next new revision is created, starting at 736 version "1.0.0" for the initial published revision, and then 737 incrementing according to the YANG Semver version rules specified in 738 Section 3.3 . For example, if a module or submodule started out in 739 the pre-NMDA ([RFC8342] ) world, and then had NMDA support added 740 without removing any legacy "state" branches -- and you are looking 741 to add additional new features -- a sensible choice for the target 742 YANG Semver would be 1.2.0 (since 1.0.0 would have been the initial, 743 pre-NMDA release, and 1.1.0 would have been the NMDA revision). 745 See Appendix A for a detailed example of IETF pre-release versions. 747 6. YANG Module 749 This YANG module contains the typedef for the YANG semantic version 750 and the identity to signal its use. 752 file "ietf-yang-semver@2021-11-04.yang" 753 module ietf-yang-semver { 754 yang-version 1.1; 755 namespace "urn:ietf:params:xml:ns:yang:ietf-yang-semver"; 756 prefix ysver; 757 rev:revision-label-scheme "yang-semver"; 759 import ietf-yang-revisions { 760 prefix rev; 761 } 763 organization 764 "IETF NETMOD (Network Modeling) Working Group"; 765 contact 766 "WG Web: 767 WG List: 769 Author: Joe Clarke 770 771 Author: Robert Wilton 772 773 Author: Reshad Rahman 774 775 Author: Balazs Lengyel 776 777 Author: Jason Sterne 778 779 Author: Benoit Claise 780 "; 781 description 782 "This module provides type and grouping definitions for YANG 783 packages. 785 Copyright (c) 2021 IETF Trust and the persons identified as 786 authors of the code. All rights reserved. 788 Redistribution and use in source and binary forms, with or 789 without modification, is permitted pursuant to, and subject 790 to the license terms contained in, the Simplified BSD License 791 set forth in Section 4.c of the IETF Trust's Legal Provisions 792 Relating to IETF Documents 793 (http://trustee.ietf.org/license-info). 795 This version of this YANG module is part of RFC XXXX; see 796 the RFC itself for full legal notices."; 798 // RFC Ed.: update the date below with the date of RFC publication 799 // and remove this note. 801 // RFC Ed.: replace XXXX with actual RFC number and remove this 802 // note. 803 // RFC Ed. update the rev:revision-label to "1.0.0". 805 revision 2021-11-04 { 806 rev:revision-label "1.0.0-draft-ietf-netmod-yang-semver-05"; 807 description 808 "Initial revision"; 809 reference 810 "RFC XXXX: YANG Semantic Versioning."; 811 } 813 /* 814 * Identities 815 */ 817 identity yang-semver { 818 base rev:revision-label-scheme-base; 819 description 820 "The revision-label scheme corresponds to the YANG Semver scheme 821 which is defined by the pattern in the 'version' typedef below. 822 The rules governing this revision-label scheme are defined in the 823 reference for this identity."; 824 reference 825 "RFC XXXX: YANG Semantic Versioning."; 826 } 828 /* 829 * Typedefs 830 */ 832 typedef version { 833 type rev:revision-label { 834 pattern '[0-9]+[.][0-9]+[.][0-9]+(_(non_)?compatible)?' 835 + '(-[A-Za-z0-9.-]+[.-][0-9]+)?([+][A-Za-z0-9.-]+)?'; 836 } 837 description 838 "Represents a YANG semantic version. The rules governing the 839 use of this revision label scheme are defined in the reference for 840 this typedef."; 841 reference 842 "RFC XXXX: YANG Semantic Versioning."; 843 } 844 } 845 847 7. Contributors 849 This document grew out of the YANG module versioning design team that 850 started after IETF 101. The design team consists of the following 851 members whom have worked on the YANG versioning project: 853 * Balazs Lengyel 855 * Benoit Claise 857 * Bo Wu 859 * Ebben Aries 861 * Jan Lindblad 863 * Jason Sterne 865 * Joe Clarke 867 * Juergen Schoenwaelder 869 * Mahesh Jethanandani 871 * Michael (Wangzitao) 873 * Qin Wu 875 * Reshad Rahman 877 * Rob Wilton 879 The initial revision of this document was refactored and built upon 880 [I-D.clacla-netmod-yang-model-update] . We would like the thank 881 Kevin D'Souza for his initial work in this problem space. 883 Discussons on the use of Semver for YANG versioning has been held 884 with authors of the OpenConfig YANG models based on their own 885 [openconfigsemver] . We would like thank both Anees Shaikh and Rob 886 Shakir for their input into this problem space. 888 8. Security Considerations 890 The document does not define any new protocol or data model. There 891 are no security impacts. 893 9. IANA Considerations 894 9.1. YANG Module Registrations 896 This document requests IANA to register a URI in the "IETF XML 897 Registry" [RFC3688] . Following the format in RFC 3688, the 898 following registration is requested. 900 URI: urn:ietf:params:xml:ns:yang:ietf-yang-semver 902 Registrant Contact: The IESG. 904 XML: N/A, the requested URI is an XML namespace. 906 The following YANG module is requested to be registred in the "IANA 907 Module Names" [RFC6020] . Following the format in RFC 6020, the 908 following registrations are requested: 910 The ietf-yang-semver module: 912 Name: ietf-yang-semver 914 XML Namespace: urn:ietf:params:xml:ns:yang:ietf-yang-semver 916 Prefix: yangver 918 Reference: [RFCXXXX] 920 9.2. Guidance for YANG Semver in IANA maintained YANG modules and 921 submodules 923 Note for IANA (to be removed by the RFC editor): Please check that 924 the registries and IANA YANG modules and submodules are referenced in 925 the appropriate way. 927 IANA is responsible for maintaining and versioning some YANG modules 928 and submodules, e.g., iana-if-types.yang [IfTypeYang] and iana- 929 routing-types.yang [RoutingTypesYang] . 931 In addition to following the rules specified in the IANA 932 Considerations section of [I-D.ietf-netmod-yang-module-versioning] , 933 IANA maintained YANG modules and submodules MUST also include a YANG 934 Semver revision label for all new revisions, as defined in Section 3 935 . 937 The YANG Semver version associated with the new revision MUST follow 938 the rules defined in Section 3.3 . 940 Note: For IANA maintained YANG modules and submodules that have 941 already been published, revision labels MUST be retroactively applied 942 to all existing revisions when the next new revision is created, 943 starting at version "1.0.0" for the initial published revision, and 944 then incrementing according to the YANG Semver rules specified in 945 Section 3.3 . 947 Most changes to IANA maintained YANG modules and submodules are 948 expected to be backwards-compatible changes and classified as MINOR 949 version changes. The PATCH version may be incremented instead when 950 only editorial changes are made, and the MAJOR version would be 951 incremented if non-backwards-compatible changes are made. 953 Given that IANA maintained YANG modules are versioned with a linear 954 history, it is anticipated that it should not be necessary to use the 955 "_compatible" or "_non_compatible" modifiers to the "Z_COMPAT" 956 version element. 958 10. References 960 10.1. Normative References 962 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 963 Requirement Levels", BCP 14, RFC 2119, 964 DOI 10.17487/RFC2119, March 1997, 965 . 967 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 968 DOI 10.17487/RFC3688, January 2004, 969 . 971 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 972 the Network Configuration Protocol (NETCONF)", RFC 6020, 973 DOI 10.17487/RFC6020, October 2010, 974 . 976 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 977 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 978 May 2017, . 980 [RFC8407] Bierman, A., "Guidelines for Authors and Reviewers of 981 Documents Containing YANG Data Models", BCP 216, RFC 8407, 982 DOI 10.17487/RFC8407, October 2018, 983 . 985 [I-D.ietf-netmod-yang-module-versioning] 986 Wilton, R., Rahman, R., Lengyel, B., Clarke, J., and J. 987 Sterne, "Updated YANG Module Revision Handling", Work in 988 Progress, Internet-Draft, draft-ietf-netmod-yang-module- 989 versioning-05, 8 November 2021, 990 . 993 10.2. Informative References 995 [I-D.clacla-netmod-yang-model-update] 996 Claise, B., Clarke, J., Lengyel, B., and K. D'Souza, "New 997 YANG Module Update Procedure", Work in Progress, Internet- 998 Draft, draft-clacla-netmod-yang-model-update-06, 2 July 999 2018, . 1002 [I-D.ietf-netmod-yang-packages] 1003 Wilton, R., Rahman, R., Clarke, J., Sterne, J., and B. Wu, 1004 "YANG Packages", Work in Progress, Internet-Draft, draft- 1005 ietf-netmod-yang-packages-02, 25 October 2021, 1006 . 1009 [I-D.ietf-netmod-yang-schema-comparison] 1010 Wilton, R., "YANG Schema Comparison", Work in Progress, 1011 Internet-Draft, draft-ietf-netmod-yang-schema-comparison- 1012 01, 2 November 2020, . 1015 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 1016 and R. Wilton, "Network Management Datastore Architecture 1017 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 1018 . 1020 [openconfigsemver] 1021 "Semantic Versioning for Openconfig Models", 1022 . 1024 [semver] "Semantic Versioning 2.0.0 (text from June 19, 2020)", 1025 . 1028 [IfTypeYang] 1029 "iana-if-type YANG Module", 1030 . 1033 [RoutingTypesYang] 1034 "iana-routing-types YANG Module", 1035 . 1038 Appendix A. Example IETF Module Development 1040 Assume a new YANG module is being developed in the netmod working 1041 group in the IETF. Initially, this module is being developed in an 1042 individual internet draft, draft-jdoe-netmod-example-module. The 1043 following represents the initial version tree (i.e., value of 1044 revision-label) of the module as it's being initially developed. 1046 Version lineage for initial module development: 1048 0.0.1-draft-jdoe-netmod-example-module-00 1049 | 1050 0.1.0-draft-jdoe-netmod-example-module-01 1051 | 1052 0.2.0-draft-jdoe-netmod-example-module-02 1053 | 1054 0.2.1-draft-jdoe-netmod-example-module-03 1056 At this point, development stabilizes, and the workgroup adopts the 1057 draft. Thus now the draft becomes draft-ietf-netmod-example-module. 1058 The initial pre-release lineage continues as follows. 1060 Continued version lineage after adoption: 1062 1.0.0-draft-ietf-netmod-example-module-00 1063 | 1064 1.0.0-draft-ietf-netmod-example-module-01 1065 | 1066 1.0.0-draft-ietf-netmod-example-module-02 1068 At this point, the draft is ratified and becomes RFC12345 and the 1069 YANG module version becomes 1.0.0. 1071 A time later, the module needs to be revised to add additional 1072 capabilities. Development will be done in a backwards-compatible 1073 way. Two new individual drafts are proposed to go about adding the 1074 capabilities in different ways: draft-jdoe-netmod-exmod-enhancements 1075 and draft-jadoe-netmod-exmod-changes. These are initially developed 1076 in parallel with the following versions. 1078 Parallel development for next module revision: 1080 1.1.0-draft-jdoe-netmod-exmod-enhancements-00 || 1.1.0-draft-jadoe-netmod-exmod-changes-00 1081 | | 1082 1.1.0-draft-jdoe-netmod-exmod-enhancements-01 || 1.1.0-draft-jadoe-netmod-exmod-changes-01 1084 At this point, the WG decides to merge some aspects of both and adopt 1085 the work in jadoe's draft as draft-ietf-netmod-exmod-changes. A 1086 single version lineage continues. 1088 1.1.0-draft-ietf-netmod-exmod-changes-00 1089 | 1090 1.1.0-draft-ietf-netmod-exmod-changes-01 1091 | 1092 1.1.0-draft-ietf-netmod-exmod-changes-02 1093 | 1094 1.1.0-draft-ietf-netmod-exmod-changes-03 1096 The draft is ratified, and the new module version becomes 1.1.0. 1098 Authors' Addresses 1100 Joe Clarke (editor) 1101 Cisco Systems, Inc. 1102 7200-12 Kit Creek Rd 1103 Research Triangle Park, North Carolina 1104 United States of America 1106 Phone: +1-919-392-2867 1107 Email: jclarke@cisco.com 1109 Robert Wilton (editor) 1110 Cisco Systems, Inc. 1112 Email: rwilton@cisco.com 1114 Reshad Rahman 1116 Email: reshad@yahoo.com 1118 Balazs Lengyel 1119 Ericsson 1120 1117 Budapest 1121 Magyar Tudosok Korutja 1122 Hungary 1124 Phone: +36-70-330-7909 1125 Email: balazs.lengyel@ericsson.com 1127 Jason Sterne 1128 Nokia 1130 Email: jason.sterne@nokia.com 1132 Benoit Claise 1133 Huawei 1135 Email: benoit.claise@huawei.com