idnits 2.17.1 draft-ietf-netmod-yang-semver-04.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 8 instances of too long lines in the document, the longest one being 31 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 (25 October 2021) is 907 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 896, but not defined == Outdated reference: A later version (-11) exists of draft-ietf-netmod-yang-module-versioning-03 == 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 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: 28 April 2022 7 B. Lengyel 8 Ericsson 9 J. Sterne 10 Nokia 11 B. Claise 12 Huawei 13 25 October 2021 15 YANG Semantic Versioning 16 draft-ietf-netmod-yang-semver-04 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 28 April 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 . . . . . . . . . . . . . . . 15 74 6. YANG Module . . . . . . . . . . . . . . . . . . . . . . . . . 16 75 7. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 18 76 8. Security Considerations . . . . . . . . . . . . . . . . . . . 19 77 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 19 78 9.1. YANG Module Registrations . . . . . . . . . . . . . . . . 19 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 . . . . . . . . . . . . . . . . . 21 84 Appendix A. Example IETF Module Development . . . . . . . . . . 22 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 number as the argument to the 'rev:revision-label' statement. 216 Because the rules put forth in 217 [I-D.ietf-netmod-yang-module-versioning] are designed to work well 218 with existing versions of YANG and allow for artifact authors to 219 migrate to this scheme, it is not expected that all revisions of a 220 given YANG artifact will have a semantic version label. For example, 221 the first revision of a module or submodule may have been produced 222 before this scheme was available. 224 YANG packages that make use of this YANG Semver will reflect that in 225 the package metadata. 227 As stated above, the YANG semantic version is expressed as a string 228 of the form: 'X.Y.Z_COMPAT'; where X, Y, and Z each represent non- 229 negative integers less than or equal to 2147483647 without leading 230 zeroes, and _COMPAT represents an optional suffix of either 231 "_compatible" or "_non_compatible". 233 * 'X' is the MAJOR version. Changes in the MAJOR version number 234 indicate changes that are non-backwards-compatible to versions 235 with a lower MAJOR version number. 237 * 'Y' is the MINOR version. Changes in the MINOR version number 238 indicate changes that are backwards-compatible to versions with 239 the same MAJOR version number, but a lower MINOR version number 240 and no PATCH "_compatible" or "_non_compatible" modifier. 242 * 'Z_COMPAT' is the PATCH version and modifier. Changes in the 243 PATCH version number can indicate editorial, backwards-compatible, 244 or non-backwards-compatible changes relative to versions with the 245 same MAJOR and MINOR version numbers, but lower PATCH version 246 number, depending on what form modifier "_COMPAT" takes: 248 - If the modifier string is absent, the change represents an 249 editorial change. An editorial change is defined to be a 250 change in the YANG artifact's content that does not affect the 251 semantic meaning or functionality provided by the artifact in 252 any way. Some examples include correcting a spelling mistake 253 in the description of a leaf within a YANG module or submodule, 254 non-significant whitespace changes (e.g., realigning 255 description statements or changing indendation), or changes to 256 YANG comments. Note: restructuring how a module uses, or does 257 not use, submodules is treated as an editorial level change on 258 the condition that there is no change in the module's semantic 259 behavior due to the restructuring. 261 - If, however, the modifier string is present, the meaning is 262 described below: 264 - "_compatible" - the change represents a backwards-compatible 265 change 267 - "_non_compatible" - the change represents a non-backwards- 268 compatible change 270 The YANG artifact name and YANG semantic version uniquely identify a 271 revision of said artifact. There MUST NOT be multiple instances of a 272 YANG artifact definition with the same name and YANG semantic version 273 but different content (and in the case of modules and submodules, 274 different revision dates). 276 There MUST NOT be multiple versions of a YANG artifact that have the 277 same MAJOR, MINOR and PATCH version numbers, but different patch 278 modifier strings. E.g., artifact version "1.2.3_non_compatible" MUST 279 NOT be defined if artifact version "1.2.3" has already been defined. 281 3.2.1. YANG Semver with submodules 283 YANG Semver MAY be used to version submodules. Submodule version are 284 separate of any version on the including module, but if a submodule 285 has changed, then the version of the including module MUST also be 286 updated. 288 The rules for determining the version change of a submodule are the 289 same as those defined in Section 3.1 and Section 3.2 as applied to 290 YANG modules, except they only apply to the part of the module schema 291 defined within the submodule's file. 293 One interesting case is moving definitions from one submodule to 294 another in a way that does not change the resultant schema of the 295 including module. In this case: 297 1. The including module has editorial changes 299 2. The submodule with the schema definition removed has non- 300 backwards-compatible changes 302 3. The submodule with the schema definitions added has backwards- 303 compatible changes 305 Note that the meaning of a submodule may change drastically despite 306 having no changes in content or revision due to changes in other 307 submodules belonging to the same module (e.g. groupings and typedefs 308 declared in one submodule and used in another). 310 3.2.2. Examples for YANG semantic versions 312 The following diagram and explanation illustrate how YANG semantic 313 versions work. 315 Example YANG semantic versions for an example artifact: 317 0.1.0 318 | 319 0.2.0 320 | 321 1.0.0 322 | \ 323 | 1.1.0 -> 1.1.1_compatible -> 1.1.2_non_compatible 324 | | 325 | 1.2.0 -> 1.2.1_non_compatible -> 1.2.2_non_compatible 326 | | 327 | 1.3.0 -> 1.3.1 328 | 329 2.0.0 330 | 331 3.0.0 332 \ 333 3.1.0 335 Assume the tree diagram above illustrates how an example YANG 336 module's version history might evolve. For example, the tree might 337 represent the following changes, listed in chronological order of 338 when the revisions were published, from oldest revision to newest: 340 0.1.0 - first pre-release module version 342 0.2.0 - second pre-release module version (with NBC changes) 344 1.0.0 - first release (may have NBC changes from 0.2.0) 346 1.1.0 - added new functionality, leaf "foo" (BC) 348 1.2.0 - added new functionality, leaf "baz" (BC) 350 1.3.0 - improve existing functionality, added leaf "foo-64" (BC) 352 1.3.1 - improve description wording for "foo-64" (Editorial) 354 1.1.1_compatible - backport "foo-64" leaf to 1.1.x to avoid 355 implementing "baz" from 1.2.0 (BC) 357 2.0.0 - change existing model for performance reasons, e.g. re-key 358 list (NBC) 360 1.1.2_non_compatible - NBC point bug fix, not required in 2.0.0 361 due to model changes (NBC) 363 3.0.0 - NBC bugfix, rename "baz" to "bar"; also add new BC leaf 364 "wibble"; (NBC) 365 1.2.1_non_compatible - backport NBC fix, changing "baz" to "bar" 367 1.2.2_non_compatible - backport "wibble". This is a BC change but 368 "non_compatible" modifier is sticky. 370 3.1.0 - introduce new leaf "wobble" (BC) 372 The partial ordering relationships based on the semantic versioning 373 numbers are as follows: 375 1.0.0 < 1.1.0 < 1.2.0 < 1.3.0 < 2.0.0 < 3.0.0 < 3.1.0 377 1.0.0 < 1.1.0 < 1.1.1_compatible < 1.1.2_non_compatible 379 1.0.0 < 1.1.0 < 1.2.0 < 1.2.1_non_compatible < 380 1.2.2_non_compatible 382 There is no ordering relationship between 1.1.1_non_compatible and 383 either 1.2.0 or 1.2.1_non_compatible, except that they share the 384 common ancestor of 1.1.0. 386 Looking at the version number alone, the module definition in 2.0.0 387 does not necessarily contain the contents of 1.3.0. However, the 388 module revision history in 2.0.0 may well indicate that it was edited 389 from module version 1.3.0. 391 3.3. YANG Semantic Version Update Rules 393 When a new revision of an artifact is produced, then the following 394 rules define how the YANG semantic version number for the new 395 artifact revision is calculated, based on the changes between the two 396 artifact revisions, and the YANG semantic version number of the base 397 artifact revision from which the changes are derived. 399 The following four rules specify the RECOMMENDED, and REQUIRED 400 minimum, update to a YANG semantic version number: 402 1. If an artifact is being updated in a non-backwards-compatible 403 way, then the artifact version 404 "X.Y.Z[_compatible|_non_compatible]" SHOULD be updated to 405 "X+1.0.0" unless that version has already been used for this 406 artifact but with different content, in which case the artifact 407 version "X.Y.Z+1_non_compatible" SHOULD be used instead. 409 2. If an artifact is being updated in a backwards-compatible way, 410 then the next version number depends on the format of the current 411 version number: 413 i "X.Y.Z" - the artifact version SHOULD be updated to 414 "X.Y+1.0", unless that version has already been used for 415 this artifact but with different content, when the artifact 416 version SHOULD be updated to "X.Y.Z+1_compatible"" instead. 418 ii "X.Y.Z_compatible" - the artifact version SHOULD be updated 419 to "X.Y.Z+1_compatible". 421 iii "X.Y.Z_non_compatible" - the artifact version SHOULD be 422 updated to "X.Y.Z+1_non_compatible". 424 3. If an artifact is being updated in an editorial way, then the 425 next version number depends on the format of the current version 426 number: 428 i "X.Y.Z" - the artifact version SHOULD be updated to 429 "X.Y.Z+1" 431 ii "X.Y.Z_compatible" - the artifact version SHOULD be updated 432 to "X.Y.Z+1_compatible". 434 iii "X.Y.Z_non_compatible" - the artifact version SHOULD be 435 updated to "X.Y.Z+1_non_compatible". 437 4. YANG artifact semantic version numbers beginning with 0, i.e., 438 "0.X.Y", are regarded as pre-release definitions and need not 439 follow the rules above. Either the MINOR or PATCH version 440 numbers may be updated, regardless of whether the changes are 441 non-backwards-compatible, backwards-compatible, or editorial. 442 See Section 5 for more details on using this notation during 443 module and submodule development. 445 5. Additional pre-release rules for modules that have had at least 446 one release are specified in Section 5 . 448 Although artifacts SHOULD be updated according to the rules above, 449 which specify the recommended (and minimum required) update to the 450 version number, the following rules MAY be applied when choosing a 451 new version number: 453 1. An artifact author MAY update the version number with a more 454 significant update than described by the rules above. For 455 example, an artifact could be given a new MAJOR version number 456 (i.e., X+1.0.0), even though no non-backwards-compatible changes 457 have occurred, or an artifact could be given a new MINOR version 458 number (i.e., X.Y+1.0) even if the changes were only editorial. 460 2. An artifact author MAY skip version numbers. That is, an 461 artifact's revision history could be 1.0.0, 1.1.0, and 1.3.0 462 where 1.2.0 is skipped. Note that skipping versions has an 463 impact when importing modules by revision-or-derived. See 464 Section 4 for more details on importing modules with revision- 465 label version gaps. 467 Although YANG Semver always indicates when a non-backwards- 468 compatible, or backwards-compatible change may have occurred to a 469 YANG artifact, it does not guarantee that such a change has occurred, 470 or that consumers of that YANG artifact will be impacted by the 471 change. Hence, tooling, e.g., 472 [I-D.ietf-netmod-yang-schema-comparison] , also plays an important 473 role for comparing YANG artifacts and calculating the likely impact 474 from changes. 476 [I-D.ietf-netmod-yang-module-versioning] defines the "rev:nbc- 477 changes" extension statement to indicate where non-backwards- 478 compatible changes have occurred in the module revision history. If 479 a revision entry in a module's revision history includes the 480 "rev:nbc-changes" statement then that MUST be reflected in any YANG 481 semantic version associated with that revision. However, the reverse 482 does not necessarily hold, i.e., if the MAJOR version has been 483 incremented it does not necessarily mean that a "rev:nbc-changes" 484 statement would be present. 486 3.4. Examples of the YANG Semver Label 488 3.4.1. Example Module Using YANG Semver 490 Below is a sample YANG module that uses the YANG Semver revision- 491 label based on the rules defined in this document. 493 module example-versioned-module { 494 yang-version 1.1; 495 namespace "urn:example:versioned:module"; 496 prefix "exvermod"; 497 rev:revision-label-scheme "yangver:yang-semver"; 499 import ietf-yang-revisions { prefix "rev"; } 500 import ietf-yang-semver { prefix "ysver"; } 502 description 503 "to be completed"; 505 revision 2018-02-28 { 506 description "Added leaf 'wobble'"; 507 rev:revision-label 3.1.0; 509 } 511 revision 2017-12-31 { 512 description "Rename 'baz' to 'bar', added leaf 'wibble'"; 513 rev:revision-label 3.0.0; 514 rev:nbc-changes; 515 } 517 revision 2017-10-30 { 518 description "Change the module structure"; 519 rev:revision-label 2.0.0; 520 rev:nbc-changes; 521 } 523 revision 2017-08-30 { 524 description "Clarified description of 'foo-64' leaf"; 525 rev:revision-label 1.3.1; 526 } 528 revision 2017-07-30 { 529 description "Added leaf foo-64"; 530 rev:revision-label 1.3.0; 531 } 533 revision 2017-04-20 { 534 description "Add new functionality, leaf 'baz'"; 535 rev:revision-label 1.2.0; 536 } 538 revision 2017-04-03 { 539 description "Add new functionality, leaf 'foo'"; 540 rev:revision-label 1.1.0; 541 } 543 revision 2017-02-07 { 544 description "First release version."; 545 rev:revision-label 1.0.0; 546 } 548 // Note: semver rules do not apply to 0.X.Y labels. 550 revision 2017-01-30 { 551 description "NBC changes to initial revision"; 552 semver:module-version 0.2.0; 553 } 555 revision 2017-01-26 { 556 description "Initial module version"; 557 semver:module-version 0.1.0; 558 } 560 //YANG module definition starts here 561 } 563 3.4.2. Example of Package Using YANG Semver 565 Below is an example YANG package that uses the semver revision label 566 based on the rules defined in this document. 568 { 569 "ietf-yang-instance-data:instance-data-set": { 570 "name": "example-yang-pkg", 571 "target-ptr": "TBD", 572 "timestamp": "2018-09-06T17:00:00Z", 573 "description": "Example IETF package definition", 574 "content-data": { 575 "ietf-yang-package:yang-package": { 576 "name": "example-yang-pkg", 577 "version": "1.3.1", 578 ... 579 } 581 4. Import Module by Semantic Version 583 [I-D.ietf-netmod-yang-module-versioning] allows for imports to be 584 done based on a module or a derived revision of a module. The 585 rev:revision-or-derived statement can specify either a revision date 586 or a revision label. The YANG Semver revision-label value can be 587 used as the argument to rev:revision-or-derived . When used as such, 588 any module that contains exactly the same YANG semantic version in 589 its revision history may be used to satisfy the import requirement. 590 For example: 592 import example-module { 593 rev:revision-or-derived 3.0.0; 594 } 596 Note: the import lookup does not stop when a non-backward-compatible 597 change is encountered. That is, if module B imports a module A at or 598 derived from version 2.0.0, resolving that import will pass through a 599 revision of module A with version 2.1.0_non_compatible in order to 600 determine if the present instance of module A derives from 2.0.0. 602 If an import by revision-or-derived cannot locate the specified 603 revision-label in a given module's revision history, that import will 604 fail. This is noted in the case of version gaps. That is, if a 605 module's history includes 1.0.0, 1.1.0, and 1.3.0, an import from 606 revision-or-derived at 1.2.0 will be unable to locate the specified 607 revision entry and thus the import cannot be satisfied. 609 5. Guidelines for Using Semver During Module Development 611 This section and the IETF-specific sub-section below provides YANG 612 Semver-specific guidelines to consider when developing new YANG 613 modules. As such this section updates [RFC8407] . 615 Development of a brand new YANG module or submodule outside of the 616 IETF that uses YANG Semver as its revision-label scheme SHOULD begin 617 with a 0 for the MAJOR version component. This allows the module or 618 submodule to disregard strict semver rules with respect to non- 619 backwards-compatible changes during its initial development. 620 However, module or submodule developers MAY choose to use the semver 621 pre-release syntax instead with a 1 for the MAJOR version component. 622 For example, an initial module or submodule revision-label might be 623 either 0.0.1 or 1.0.0-alpha.1. If the authors choose to use the 0 624 MAJOR version component scheme, they MAY switch to the pre-release 625 scheme with a MAJOR version component of 1 when the module or 626 submodule is nearing initial release (e.g., a module's or submodule's 627 revision label may transition from 0.3.0 to 1.0.0-beta.1 to indicate 628 it is more mature and ready for testing). 630 When using pre-release notation, the format MUST include at least one 631 alphabetic component and MUST end with a '.' or '-' and then one or 632 more digits. These alphanumeric components will be used when 633 deciding pre-release precedence. The following are examples of valid 634 pre-release versions 636 1.0.0-alpha.1 638 1.0.0-alpha.3 640 2.1.0-beta.42 642 3.0.0-202007.rc.1 644 When developing a new revision of an existing module or submodule 645 using the YANG semver revision-label scheme, the intended target 646 semver version MUST be used along with pre-release notation. For 647 example, if a released module or submodule which has a current 648 revision-label of 1.0.0 is being modified with the intent to make 649 non-backwards-compatible changes, the first development MAJOR version 650 component must be 2 with some pre-release notation such as -alpha.1, 651 making the version 2.0.0-alpha.1. That said, every publicly 652 available release of a module or submodule MUST have a unique YANG 653 semver revision-label (where a publicly available release is one that 654 could be implemented by a vendor or consumed by an end user). 655 Therefore, it may be prudent to include the year or year and month 656 development began (e.g., 2.0.0-201907-alpha.1). As a module or 657 submodule undergoes development, it is possible that the original 658 intent changes. For example, a 1.0.0 version of a module or 659 submodule that was destined to become 2.0.0 after a development cycle 660 may have had a scope change such that the final version has no non- 661 backwards-compatible changes and becomes 1.1.0 instead. This change 662 is acceptable to make during the development phase so long as pre- 663 release notation is present in both versions (e.g., 2.0.0-alpha.3 664 becomes 1.1.0-alpha.4). However, on the next development cycle 665 (after 1.1.0 is released), if again the new target release is 2.0.0, 666 new pre-release components must be used such that every revision- 667 label for a given module or submodule MUST be unique throughout its 668 entire lifecycle (e.g., the first pre-release version might be 669 2.0.0-202005-alpha.1 if keeping the same year and month notation 670 mentioned above). 672 5.1. Pre-release Version Precedence 674 As a module or submodule is developed, the scope of the work may 675 change. That is, while a ratified module or submodule with revision- 676 label 1.0.0 is initially intended to become 2.0.0 in its next 677 ratified version, the scope of work may change such that the final 678 version is 1.1.0. During the development cycle, the pre-release 679 versions could move from 2.0.0-some-pre-release-tag to 1.1.0-some- 680 pre-release-tag. This downwards changing of version numbers makes it 681 difficult to evaluate semver rules between pre-release versions. 682 However, taken independently, each pre-release version can be 683 compared to the previously ratified version (e.g., 1.1.0-some-pre- 684 release-tag and 2.0.0-some-pre-release-tag can each be compared to 685 1.0.0). Module and submodule developers SHOULD maintain only one 686 revision statement in a pre-released module or submodule that 687 reflects the latest revision. IETF authors MAY choose to include an 688 appendix in the associated draft to track overall changes to the 689 module or submodule. 691 5.2. YANG Semver in IETF Modules 693 All published IETF modules and submodules MUST use YANG semantic 694 versions for their revision-labels. 696 Development of a new module or submodule within the IETF SHOULD begin 697 with the 0 MAJOR number scheme as described above. When revising an 698 existing IETF module or submodule, the revision-label MUST use the 699 target (i.e., intended) MAJOR and MINOR version components with a 0 700 PATCH version component. If the intended ratified release will be 701 non-backward-compatible with the current ratified release, the MINOR 702 version component MUST be 0. 704 All IETF modules and submodules in development MUST use the whole 705 document name as a pre-release version string, including the current 706 document revision. For example, if a module or submodule which is 707 currently released at version 1.0.0 is being revised to include non- 708 backwards-compatible changes in draft-user-netmod-foo, its 709 development revision-labels MUST include 2.0.0-draft-user-netmod-foo 710 followed by the document's revision (e.g., 2.0.0-draft-user-netmod- 711 foo-02). This will ensure each pre-release version is unique across 712 the lifecycle of the module or submodule. Even when using the 0 713 MAJOR version for initial module or submodule development (where 714 MINOR and PATCH can change), appending the draft name as a pre- 715 release component helps to ensure uniqueness when there are perhaps 716 multiple, parallel efforts creating the same module or submodule. 718 For IETF YANG modules and submodules that have already been 719 published, revision-labels MUST be retroactively applied to all 720 existing revisions when the next new revision is created, starting at 721 version "1.0.0" for the initial published revision, and then 722 incrementing according to the YANG Semver version rules specified in 723 Section 3.3 . For example, if a module or submodule started out in 724 the pre-NMDA ([RFC8342] ) world, and then had NMDA support added 725 without removing any legacy "state" branches -- and you are looking 726 to add additional new features -- a sensible choice for the target 727 YANG Semver would be 1.2.0 (since 1.0.0 would have been the initial, 728 pre-NMDA release, and 1.1.0 would have been the NMDA revision). 730 See Appendix A for a detailed example of IETF pre-release versions. 732 6. YANG Module 734 This YANG module contains the typedef for the YANG semantic version 735 and the identity to signal its use. 737 file "ietf-yang-semver@2021-10-20.yang" 738 module ietf-yang-semver { 739 yang-version 1.1; 740 namespace "urn:ietf:params:xml:ns:yang:ietf-yang-semver"; 741 prefix ysver; 742 rev:revision-label-scheme "yang-semver"; 743 import ietf-yang-revisions { 744 prefix rev; 745 } 747 organization 748 "IETF NETMOD (Network Modeling) Working Group"; 749 contact 750 "WG Web: 751 WG List: 753 Author: Joe Clarke 754 755 Author: Benoit Claise 756 757 Author: Reshad Rahman 758 759 Author: Robert Wilton 760 761 Author: Balazs Lengyel 762 763 Author: Jason Sterne 764 "; 765 description 766 "This module provides type and grouping definitions for YANG 767 packages. 769 Copyright (c) 2021 IETF Trust and the persons identified as 770 authors of the code. All rights reserved. 772 Redistribution and use in source and binary forms, with or 773 without modification, is permitted pursuant to, and subject 774 to the license terms contained in, the Simplified BSD License 775 set forth in Section 4.c of the IETF Trust's Legal Provisions 776 Relating to IETF Documents 777 (http://trustee.ietf.org/license-info). 779 This version of this YANG module is part of RFC XXXX; see 780 the RFC itself for full legal notices."; 782 // RFC Ed.: update the date below with the date of RFC publication 783 // and remove this note. 784 // RFC Ed.: replace XXXX with actual RFC number and remove this 785 // note. 786 // RFC Ed. update the rev:revision-label to "1.0.0". 788 revision 2021-10-20 { 789 rev:revision-label "1.0.0-draft-ietf-netmod-yang-semver-04"; 790 description 791 "Initial revision"; 792 reference 793 "RFC XXXX: YANG Semantic Versioning."; 794 } 796 /* 797 * Identities 798 */ 800 identity yang-semver { 801 base rev:revision-label-scheme-base; 802 description 803 "The revision-label scheme corresponds to the YANG Semver scheme 804 which is defined by the pattern in the 'version' typedef below. 805 The rules governing this revision-label scheme are defined in the 806 reference for this identity."; 807 reference 808 "RFC XXXX: YANG Semantic Versioning."; 809 } 811 /* 812 * Typedefs 813 */ 815 typedef version { 816 type string { 817 pattern '[0-9]+[.][0-9]+[.][0-9]+(_(non_)?compatible)?(-[A-Za-z0-9.-]+)?([+][A-Za-z0-9.-]+)?'; 818 } 819 description 820 "Represents a YANG semantic version number. The rules governing the 821 use of this revision label scheme are defined in the reference for 822 this typedef."; 823 reference 824 "RFC XXXX: YANG Semantic Versioning."; 825 } 826 } 827 829 7. Contributors 831 This document grew out of the YANG module versioning design team that 832 started after IETF 101. The design team consists of the following 833 members whom have worked on the YANG versioning project: 835 * Balazs Lengyel 837 * Benoit Claise 838 * Ebben Aries 840 * Jason Sterne 842 * Joe Clarke 844 * Juergen Schoenwaelder 846 * Mahesh Jethanandani 848 * Michael (Wangzitao) 850 * Qin Wu 852 * Reshad Rahman 854 * Rob Wilton 856 The initial revision of this document was refactored and built upon 857 [I-D.clacla-netmod-yang-model-update] . We would like the thank 858 Kevin D'Souza for his initial work in this problem space. 860 Discussons on the use of Semver for YANG versioning has been held 861 with authors of the OpenConfig YANG models based on their own 862 [openconfigsemver] . We would like thank both Anees Shaikh and Rob 863 Shakir for their input into this problem space. 865 8. Security Considerations 867 The document does not define any new protocol or data model. There 868 are no security impacts. 870 9. IANA Considerations 872 9.1. YANG Module Registrations 874 This document requests IANA to register a URI in the "IETF XML 875 Registry" [RFC3688] . Following the format in RFC 3688, the 876 following registration is requested. 878 URI: urn:ietf:params:xml:ns:yang:ietf-yang-semver 880 Registrant Contact: The IESG. 882 XML: N/A, the requested URI is an XML namespace. 884 The following YANG module is requested to be registred in the "IANA 885 Module Names" [RFC6020] . Following the format in RFC 6020, the 886 following registrations are requested: 888 The ietf-yang-semver module: 890 Name: ietf-yang-semver 892 XML Namespace: urn:ietf:params:xml:ns:yang:ietf-yang-semver 894 Prefix: yangver 896 Reference: [RFCXXXX] 898 9.2. Guidance for YANG Semver in IANA maintained YANG modules and 899 submodules 901 Note for IANA (to be removed by the RFC editor): Please check that 902 the registries and IANA YANG modules and submodules are referenced in 903 the appropriate way. 905 IANA is responsible for maintaining and versioning some YANG modules 906 and submodules, e.g., iana-if-types.yang [IfTypeYang] and iana- 907 routing-types.yang [RoutingTypesYang] . 909 In addition to following the rules specified in the IANA 910 Considerations section of [I-D.ietf-netmod-yang-module-versioning] , 911 IANA maintained YANG modules and submodules MUST also include a YANG 912 Semver revision label for all new revisions, as defined in Section 3 913 . 915 The YANG Semver version associated with the new revision MUST follow 916 the rules defined in Section 3.3 . 918 Note: For IANA maintained YANG modules and submodules that have 919 already been published, revision labels MUST be retroactively applied 920 to all existing revisions when the next new revision is created, 921 starting at version "1.0.0" for the initial published revision, and 922 then incrementing according to the YANG Semver rules specified in 923 Section 3.3 . 925 Most changes to IANA maintained YANG modules and submodules are 926 expected to be backwards-compatible changes and classified as MINOR 927 version changes. The PATCH version may be incremented instead when 928 only editorial changes are made, and the MAJOR version would be 929 incremented if non-backwards-compatible changes are made. 931 Given that IANA maintained YANG modules are versioned with a linear 932 history, it is anticipated that it should not be necessary to use the 933 "_compatible" or "_non_compatible" modifiers to the "Z_COMPAT" 934 version element. 936 10. References 938 10.1. Normative References 940 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 941 Requirement Levels", BCP 14, RFC 2119, 942 DOI 10.17487/RFC2119, March 1997, 943 . 945 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 946 DOI 10.17487/RFC3688, January 2004, 947 . 949 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 950 the Network Configuration Protocol (NETCONF)", RFC 6020, 951 DOI 10.17487/RFC6020, October 2010, 952 . 954 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 955 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 956 May 2017, . 958 [RFC8407] Bierman, A., "Guidelines for Authors and Reviewers of 959 Documents Containing YANG Data Models", BCP 216, RFC 8407, 960 DOI 10.17487/RFC8407, October 2018, 961 . 963 [I-D.ietf-netmod-yang-module-versioning] 964 Wilton, R., Rahman, R., Lengyel, B., Clarke, J., and J. 965 Sterne, "Updated YANG Module Revision Handling", Work in 966 Progress, Internet-Draft, draft-ietf-netmod-yang-module- 967 versioning-03, 12 July 2021, 968 . 971 10.2. Informative References 973 [I-D.clacla-netmod-yang-model-update] 974 Claise, B., Clarke, J., Lengyel, B., and K. D'Souza, "New 975 YANG Module Update Procedure", Work in Progress, Internet- 976 Draft, draft-clacla-netmod-yang-model-update-06, 2 July 977 2018, . 980 [I-D.ietf-netmod-yang-packages] 981 Wilton, R., Rahman, R., Clarke, J., Sterne, J., and B. Wu, 982 "YANG Packages", Work in Progress, Internet-Draft, draft- 983 ietf-netmod-yang-packages-01, 2 November 2020, 984 . 987 [I-D.ietf-netmod-yang-schema-comparison] 988 Wilton, R., "YANG Schema Comparison", Work in Progress, 989 Internet-Draft, draft-ietf-netmod-yang-schema-comparison- 990 01, 2 November 2020, 991 . 994 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 995 and R. Wilton, "Network Management Datastore Architecture 996 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 997 . 999 [openconfigsemver] 1000 "Semantic Versioning for Openconfig Models", 1001 . 1003 [semver] "Semantic Versioning 2.0.0 (text from June 19, 2020)", 1004 . 1007 [IfTypeYang] 1008 "iana-if-type YANG Module", 1009 . 1012 [RoutingTypesYang] 1013 "iana-routing-types YANG Module", 1014 . 1017 Appendix A. Example IETF Module Development 1019 Assume a new YANG module is being developed in the netmod working 1020 group in the IETF. Initially, this module is being developed in an 1021 individual internet draft, draft-jdoe-netmod-example-module. The 1022 following represents the initial version tree (i.e., value of 1023 revision-label) of the module as it's being initially developed. 1025 Version lineage for initial module development: 1027 0.0.1-draft-jdoe-netmod-example-module-00 1028 | 1029 0.1.0-draft-jdoe-netmod-example-module-01 1030 | 1031 0.2.0-draft-jdoe-netmod-example-module-02 1032 | 1033 0.2.1-draft-jdoe-netmod-example-module-03 1035 At this point, development stabilizes, and the workgroup adopts the 1036 draft. Thus now the draft becomes draft-ietf-netmod-example-module. 1037 The initial pre-release lineage continues as follows. 1039 Continued version lineage after adoption: 1041 1.0.0-draft-ietf-netmod-example-module-00 1042 | 1043 1.0.0-draft-ietf-netmod-example-module-01 1044 | 1045 1.0.0-draft-ietf-netmod-example-module-02 1047 At this point, the draft is ratified and becomes RFC12345 and the 1048 YANG module version number becomes 1.0.0. 1050 A time later, the module needs to be revised to add additional 1051 capabilities. Development will be done in a backwards-compatible 1052 way. Two new individual drafts are proposed to go about adding the 1053 capabilities in different ways: draft-jdoe-netmod-exmod-enhancements 1054 and draft-jadoe-netmod-exmod-changes. These are initially developed 1055 in parallel with the following versions. 1057 Parallel development for next module revision: 1059 1.1.0-draft-jdoe-netmod-exmod-enhancements-00 || 1.1.0-draft-jadoe-netmod-exmod-changes-00 1060 | | 1061 1.1.0-draft-jdoe-netmod-exmod-enhancements-01 || 1.1.0-draft-jadoe-netmod-exmod-changes-01 1063 At this point, the WG decides to merge some aspects of both and adopt 1064 the work in jadoe's draft as draft-ietf-netmod-exmod-changes. A 1065 single version lineage continues. 1067 1.1.0-draft-ietf-netmod-exmod-changes-00 1068 | 1069 1.1.0-draft-ietf-netmod-exmod-changes-01 1070 | 1071 1.1.0-draft-ietf-netmod-exmod-changes-02 1072 | 1073 1.1.0-draft-ietf-netmod-exmod-changes-03 1075 The draft is ratified, and the new module version becomes 1.1.0. 1077 Authors' Addresses 1079 Joe Clarke (editor) 1080 Cisco Systems, Inc. 1081 7200-12 Kit Creek Rd 1082 Research Triangle Park, North Carolina 1083 United States of America 1085 Phone: +1-919-392-2867 1086 Email: jclarke@cisco.com 1088 Robert Wilton (editor) 1089 Cisco Systems, Inc. 1091 Email: rwilton@cisco.com 1093 Reshad Rahman 1095 Email: reshad@yahoo.com 1097 Balazs Lengyel 1098 Ericsson 1099 1117 Budapest 1100 Magyar Tudosok Korutja 1101 Hungary 1103 Phone: +36-70-330-7909 1104 Email: balazs.lengyel@ericsson.com 1106 Jason Sterne 1107 Nokia 1109 Email: jason.sterne@nokia.com 1111 Benoit Claise 1112 Huawei 1114 Email: benoit.claise@huawei.com