idnits 2.17.1 draft-ietf-netmod-yang-semver-01.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 6 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 (July 13, 2020) is 1375 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) == Outdated reference: A later version (-11) exists of draft-ietf-netmod-yang-module-versioning-00 == Outdated reference: A later version (-03) exists of draft-ietf-netmod-yang-packages-00 Summary: 1 error (**), 0 flaws (~~), 3 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group B. Claise 3 Internet-Draft J. Clarke, Ed. 4 Updates: 8407 (if approved) R. Rahman 5 Intended status: Standards Track R. Wilton, Ed. 6 Expires: January 14, 2021 Cisco Systems, Inc. 7 B. Lengyel 8 Ericsson 9 J. Sterne 10 Nokia 11 K. D'Souza 12 AT&T 13 July 13, 2020 15 YANG Semantic Versioning 16 draft-ietf-netmod-yang-semver-01 18 Abstract 20 This document specifies a scheme and guidelines for applying a 21 modified set of semantic versioning rules to revisions of YANG 22 modules. Additionally, this document defines a revision-label for 23 this modified semver scheme. 25 Status of This Memo 27 This Internet-Draft is submitted in full conformance with the 28 provisions of BCP 78 and BCP 79. 30 Internet-Drafts are working documents of the Internet Engineering 31 Task Force (IETF). Note that other groups may also distribute 32 working documents as Internet-Drafts. The list of current Internet- 33 Drafts is at https://datatracker.ietf.org/drafts/current/. 35 Internet-Drafts are draft documents valid for a maximum of six months 36 and may be updated, replaced, or obsoleted by other documents at any 37 time. It is inappropriate to use Internet-Drafts as reference 38 material or to cite them other than as "work in progress." 40 This Internet-Draft will expire on January 14, 2021. 42 Copyright Notice 44 Copyright (c) 2020 IETF Trust and the persons identified as the 45 document authors. All rights reserved. 47 This document is subject to BCP 78 and the IETF Trust's Legal 48 Provisions Relating to IETF Documents 49 (https://trustee.ietf.org/license-info) in effect on the date of 50 publication of this document. Please review these documents 51 carefully, as they describe your rights and restrictions with respect 52 to this document. Code Components extracted from this document must 53 include Simplified BSD License text as described in Section 4.e of 54 the Trust Legal Provisions and are provided without warranty as 55 described in the Simplified BSD License. 57 Table of Contents 59 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 60 2. Terminology and Conventions . . . . . . . . . . . . . . . . . 3 61 3. YANG Semantic Versioning . . . . . . . . . . . . . . . . . . 3 62 3.1. YANG Semantic Versioning Pattern . . . . . . . . . . . . 3 63 3.2. Semantic Versioning Scheme for YANG Artifacts . . . . . . 4 64 3.2.1. Examples for YANG semantic version numbers . . . . . 6 65 3.3. YANG Semantic Version Update Rules . . . . . . . . . . . 8 66 3.4. Examples of the YANG Semver Label . . . . . . . . . . . . 9 67 3.4.1. Example Module Using YANG Semver . . . . . . . . . . 9 68 3.4.2. Example of Package Using YANG Semver . . . . . . . . 11 69 4. Import Module by Semantic Version . . . . . . . . . . . . . . 11 70 5. Guidelines for Using Semver During Module Development . . . . 11 71 5.1. Pre-release Version Precedence . . . . . . . . . . . . . 13 72 5.2. YANG Semver in IETF Modules . . . . . . . . . . . . . . . 13 73 6. YANG Module . . . . . . . . . . . . . . . . . . . . . . . . . 13 74 7. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 15 75 8. Security Considerations . . . . . . . . . . . . . . . . . . . 16 76 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16 77 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 16 78 10.1. Normative References . . . . . . . . . . . . . . . . . . 16 79 10.2. Informative References . . . . . . . . . . . . . . . . . 17 80 Appendix A. Example IETF Module Development . . . . . . . . . . 17 81 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 19 83 1. Introduction 85 [I-D.ietf-netmod-yang-module-versioning] puts forth a number of 86 concepts relating to modified rules for updating modules, a means to 87 signal when a new revision of a module has non-backwards-compatible 88 (NBC) changes compared to its previous revision, and a versioning 89 scheme that uses the revision history as a lineage for determining 90 from where a specific revision of a YANG module is derived. 91 Additionally, section 3.3 of [I-D.ietf-netmod-yang-module-versioning] 92 defines a revision label which can be used as an overlay or alias to 93 provide additional context or an additional way to refer to a 94 specific revision. 96 This document defines a revision-label scheme that uses modified 97 [semver] rules for YANG artifacts (i.e., YANG modules and YANG 98 packages [I-D.ietf-netmod-yang-packages]) as well as the revision 99 label definition for using this scheme. The goal of this is to add a 100 human readable version label that provides compatibility information 101 for the YANG artifact without one needing to compare or parse its 102 body. The label and rules defined herein represent the RECOMMENDED 103 revision label scheme for IETF YANG artifacts. 105 2. Terminology and Conventions 107 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 108 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 109 "OPTIONAL" in this document are to be interpreted as described in BCP 110 14 [RFC2119] [RFC8174] when, and only when, they appear in all 111 capitals, as shown here. 113 Additionally, this document uses the following terminology: 115 o YANG artifact: YANG modules, YANG packages 116 [I-D.ietf-netmod-yang-packages], and YANG schema elements are 117 examples of YANG artifacts for the purposes of this document. 119 3. YANG Semantic Versioning 121 This section defines YANG Semantic Versioning, explains how it is 122 used with YANG artifacts, and the rules associated with changing an 123 artifact's semantic version number when its contents are updated. 125 3.1. YANG Semantic Versioning Pattern 127 YANG artifacts that employ semantic versioning as defined in this 128 document MUST use a version string (e.g., in revision-label or as a 129 package version) that corresponds to the following pattern: 130 X.Y.Z_COMPAT. Where: 132 o X, Y and Z are mandatory non-negative integers that are each less 133 than 2147483647 (i.e., the maximum signed 32-bit integer value) 134 and MUST NOT contain leading zeroes 136 o The '.' is a literal period (ASCII character 0x2e) 138 o The '_' is an optional single literal underscore (ASCII character 139 0x5f) and MUST only present if the following COMPAT element is 140 included 142 o COMPAT, if it is specified, MUST be either the literal string 143 "compatible" or the literal string "non_compatible" 145 Additionally, [semver] defines two specific types of metadata that 146 may be appended to a semantic version string. Pre-release metadata 147 MAY be appended to a semver string after a trailing '-' character. 148 Build metadata MAY be appended after a trailing '+' character. If 149 both pre-release and build metadata are present, then build metadata 150 MUST follow pre-release metadata. While build metadata MUST be 151 ignored by YANG semver parsers, pre-release metadata MUST be used 152 during module development and MUST be considered base on Section 5. 153 Both pre-release and build metadata are allowed in order to support 154 all of the [semver] rules. Thus, a version lineage that follows 155 strict [semver] rules is allowed for a YANG artifact. 157 To signal the use of this versioning scheme, modules MUST set the 158 revision-label-scheme extension as defined in 159 [I-D.ietf-netmod-yang-module-versioning] to the identity "yang- 160 semver". That identity value is defined in the ietf-yang-semver 161 module below. 163 Additionally, this ietf-yang-semver module defines a typedef that 164 formally specifies the syntax of the YANG semver version string. 166 3.2. Semantic Versioning Scheme for YANG Artifacts 168 This document defines the YANG semantic versioning scheme that is 169 used for YANG artifacts that employ the YANG semver label. The 170 versioning scheme has the following properties: 172 The YANG semantic versioning scheme is extended from version 2.0.0 173 of the semantic versioning scheme defined at semver.org [semver] 174 to cover the additional requirements for the management of YANG 175 artifact lifecyles that cannot be addressed using the semver.org 176 2.0.0 versioning scheme alone. 178 Unlike the [semver] versioning scheme, the YANG semantic 179 versioning scheme supports limited updates to older versions of 180 YANG artifacts, to allow for bug fixes and enhancements to 181 artifact versions that are not the latest. However, it does not 182 provide for the unlimited branching and updating of older 183 revisions which are documented by the general rules in 184 [I-D.ietf-netmod-yang-module-versioning]. 186 YANG artifacts that follow the [semver] versioning scheme are 187 fully compatible with implementations that understand the YANG 188 semantic versioning scheme defined in this document. 190 If updates are always restricted to the latest revision of the 191 artifact only, then the version numbers used by the YANG semantic 192 versioning scheme are exactly the same as those defined by the 193 [semver] versioning scheme. 195 Every YANG module versioned using the YANG semantic versioning scheme 196 specifies the module's semantic version number as the argument to the 197 'rev:revision-label' statement. 199 Because the rules put forth in 200 [I-D.ietf-netmod-yang-module-versioning] are designed to work well 201 with existing versions of YANG and allow for artifact authors to 202 migrate to this scheme, it is not expected that all revisions of a 203 given YANG artifact will have a semantic version label. For example, 204 the first revision of a module may have been produced before this 205 scheme was available. 207 YANG packages that make use of this semantic versioning scheme will 208 have their semantic version as the value of the "revision_label" 209 property. 211 As stated above, the YANG semver version number is expressed as a 212 string of the form: 'X.Y.Z_COMPAT'; where X, Y, and Z each represent 213 non-negative integers smaller than 2147483647 without leading zeroes, 214 and _COMPAT represents an optional suffix of either "_compatible" or 215 "_non_compatible". 217 o 'X' is the MAJOR version. Changes in the major version number 218 indicate changes that are non-backwards-compatible to versions 219 with a lower major version number. 221 o 'Y' is the MINOR version. Changes in the minor version number 222 indicate changes that are backwards-compatible to versions with 223 the same major version number, but a lower minor version number 224 and no patch "_compatible" or "_non_compatible" modifier. 226 o 'Z_COMPAT' is the PATCH version and modifier. Changes in the 227 patch version number can indicate editorial, backwards-compatible, 228 or non-backwards-compatible changes relative to versions with the 229 same major and minor version numbers, but lower patch version 230 number, depending on what form modifier "_COMPAT" takes: 232 * If the modifier string is absent, the change represents an 233 editorial change. An editorial change is defined to be a 234 change in the YANG artifact's content that does not affect the 235 semantic meaning or functionality provided by the artifact in 236 any way. An example is correcting a spelling mistake in the 237 description of a leaf within a YANG module. Note: 238 restructuring how a module uses, or does not use, submodules is 239 treated as an editorial level change on the condition that 240 there is no change in the module's semantic behavior due to the 241 restructuring. 243 * If, however, the modifier string is present, the meaning is 244 described below: 246 * "_compatible" - the change represents a backwards-compatible 247 change 249 * "_non_compatible" - the change represents a non-backwards- 250 compatible change 252 The YANG artifact name and YANG semantic version number uniquely 253 identify a revision of said artifact. There MUST NOT be multiple 254 instances of a YANG artifact definition with the same name and YANG 255 semantic version number but different content (and in the case of 256 modules, different revision dates). 258 There MUST NOT be multiple versions of a YANG artifact that have the 259 same MAJOR, MINOR and PATCH version numbers, but different patch 260 modifier strings. E.g., artifact version "1.2.3_non_compatible" MUST 261 NOT be defined if artifact version "1.2.3" has already been defined. 263 3.2.1. Examples for YANG semantic version numbers 265 The following diagram and explanation illustrates how YANG semantic 266 version numbers work. 268 Example YANG semantic version numbers for an example artifact: 270 0.1.0 271 | 272 0.2.0 273 | 274 1.0.0 275 | \ 276 | 1.1.0 -> 1.1.1_compatible -> 1.1.2_non_compatible 277 | | 278 | 1.2.0 -> 1.2.1_non_compatible -> 1.2.2_non_compatible 279 | | 280 | 1.3.0 -> 1.3.1 281 | 282 2.0.0 283 | 284 3.0.0 285 \ 286 3.1.0 288 Assume the tree diagram above illustrates how an example YANG 289 module's version history might evolve. For example, the tree might 290 represent the following changes, listed in chronological order from 291 oldest revision to newest: 293 0.1.0 - first beta module version 295 0.2.0 - second beta module version (with NBC changes) 297 1.0.0 - first release (may have NBC changes from 0.2.0) 299 1.1.0 - added new functionality, leaf "foo" (BC) 301 1.2.0 - added new functionality, leaf "baz" (BC) 303 1.3.0 - improve existing functionality, added leaf "foo-64" (BC) 305 1.3.1 - improve description wording for "foo-64" (Editorial) 307 1.1.1_compatible - backport "foo-64" leaf to 1.1.x to avoid 308 implementing "baz" from 1.2.0 (BC) 310 2.0.0 - change existing model for performance reasons, e.g. re-key 311 list (NBC) 313 1.1.2_non_compatible - NBC point bug fix, not required in 2.0.0 314 due to model changes (NBC) 316 3.0.0 - NBC bugfix, rename "baz" to "bar"; also add new BC leaf 317 "wibble"; (NBC) 319 1.2.1_non_compatible - backport NBC fix, changing "baz" to "bar" 321 1.2.2_non_compatible - backport "wibble". This is a BC change but 322 "non_compatible" modifier is sticky. 324 3.1.0 - introduce new leaf "wobble" (BC) 326 The partial ordering relationships based on the semantic versioning 327 numbers can be defined as follows: 329 1.0.0 < 1.1.0 < 1.2.0 < 1.3.0 < 2.0.0 < 3.0.0 < 3.1.0 331 1.0.0 < 1.1.0 < 1.1.1_compatible < 1.1.2_non_compatible 333 1.0.0 < 1.1.0 < 1.2.0 < 1.2.1_non_compatible < 334 1.2.2_non_compatible 336 There is no ordering relationship between 1.1.1_non_compatible and 337 either 1.2.0 or 1.2.1_non_compatible, except that they share the 338 common ancestor of 1.1.0. 340 Looking at the version number alone, the module definition in 2.0.0 341 does not necessarily contain the contents of 1.3.0. However, the 342 module revision history in 2.0.0 may well indicate that it was edited 343 from module version 1.3.0. 345 3.3. YANG Semantic Version Update Rules 347 When a new revision of an artifact is produced, then the following 348 rules define how the YANG semantic version number for the new 349 artifact revision is calculated, based on the changes between the two 350 artifact revisions, and the YANG semantic version number of the base 351 artifact revision from which the changes are derived: 353 1. If an artifact is being updated in a non-backwards-compatible 354 way, then the artifact version 355 "X.Y.Z[_compatible|_non_compatible]" MUST be updated to "X+1.0.0" 356 unless that artifact version has already been defined with 357 different content, in which case the artifact version 358 "X.Y.Z+1_non_compatible" MUST be used instead. 360 2. Under some circumstances (e.g., to avoid adding a "_compatible" 361 modifier) an artifact author MAY also update the MAJOR version 362 when the only changes are backwards-compatible. This is where 363 tooling is important to highlight all changes. Because, while 364 avoiding the "_compatible" and "_non_compatible" modifiers have a 365 clear advantage, bumping a MAJOR version when changes are 366 entirely backwards-compatible may confuse end users. 368 3. If an artifact is being updated in a backwards-compatible way, 369 then the next version number depends on the format of the current 370 version number: 372 i "X.Y.Z" - the artifact version MUST be updated to 373 "X.Y+1.0", unless that artifact version has already been 374 defined with different content, when the artifact version 375 MUST be updated to "X.Y.Z+1_compatible"" instead. 377 ii "X.Y.Z_compatible" - the artifact version MUST be updated 378 to "X.Y.Z+1_compatible". 380 iii "X.Y.Z_non_compatible" - the artifact version MUST be 381 updated to "X.Y.Z+1_non_compatible". 383 4. If an artifact is being updated in an editorial way, then the 384 next version number depends on the format of the current version 385 number: 387 i "X.Y.Z" - the artifact version MUST be updated to "X.Y.Z+1" 389 ii "X.Y.Z_compatible" - the artifact version MUST be updated 390 to "X.Y.Z+1_compatible". 392 iii "X.Y.Z_non_compatible" - the artifact version MUST be 393 updated to "X.Y.Z+1_non_compatible". 395 5. YANG artifact semantic version numbers beginning with 0, i.e 396 "0.X.Y" are regarded as beta definitions and need not follow the 397 rules above. Either the MINOR or PATCH version numbers may be 398 updated, regardless of whether the changes are non-backwards- 399 compatible, backwards-compatible, or editorial. See Section 5 400 for more details on using this notation during module 401 development. 403 3.4. Examples of the YANG Semver Label 405 3.4.1. Example Module Using YANG Semver 407 Below is a sample YANG module that uses the YANG semver revision 408 label based on the rules defined in this document. 410 module example-versioned-module { 411 yang-version 1.1; 412 namespace "urn:example:versioned:module"; 413 prefix "exvermod"; 414 rev:revision-label-scheme "yangver:yang-semver"; 416 import ietf-yang-revisions { prefix "rev"; } 417 import ietf-yang-semver { prefix "yangver"; } 419 description 420 "to be completed"; 422 revision 2018-02-28 { 423 description "Added leaf 'wobble'"; 424 rev:revision-label "3.1.0"; 425 } 427 revision 2017-12-31 { 428 description "Rename 'baz' to 'bar', added leaf 'wibble'"; 429 rev:revision-label "3.0.0"; 430 rev:nbc-changes; 432 } 434 revision 2017-10-30 { 435 description "Change the module structure"; 436 rev:revision-label "2.0.0"; 437 rev:nbc-changes; 438 } 440 revision 2017-08-30 { 441 description "Clarified description of 'foo-64' leaf"; 442 rev:revision-label "1.3.1"; 443 } 445 revision 2017-07-30 { 446 description "Added leaf foo-64"; 447 rev:revision-label "1.3.0"; 448 } 450 revision 2017-04-20 { 451 description "Add new functionality, leaf 'baz'"; 452 rev:revision-label "1.2.0"; 453 } 455 revision 2017-04-03 { 456 description "Add new functionality, leaf 'foo'"; 457 rev:revision-label "1.1.0"; 458 } 460 revision 2017-04-03 { 461 description "First release version."; 462 rev:revision-label "1.0.0"; 463 } 465 // Note: semver rules do not apply to 0.X.Y labels. 467 revision 2017-01-30 { 468 description "NBC changes to initial revision"; 469 semver:module-version "0.2.0"; 470 } 472 revision 2017-01-26 { 473 description "Initial module version"; 474 semver:module-version "0.1.0"; 475 } 477 //YANG module definition starts here 479 3.4.2. Example of Package Using YANG Semver 481 Below is an example YANG package that uses the semver revision label 482 based on the rules defined in this document. 484 { 485 "ietf-yang-instance-data:instance-data-set": { 486 "name": "example-yang-pkg", 487 "target-ptr": "TBD", 488 "timestamp": "2018-09-06T17:00:00Z", 489 "description": "Example IETF package definition", 490 "content-data": { 491 "ietf-yang-package:yang-package": { 492 "name": "example-yang-pkg", 493 "version": "1.3.1", 494 ... 495 } 497 4. Import Module by Semantic Version 499 [I-D.ietf-netmod-yang-module-versioning] allows for imports to be 500 done based on a module or a derived revision of a module. The 501 rev:revision-or-derived statement can specify either a revision date 502 or a revision label. When importing by semver, the YANG semver 503 revision label value MAY be used as an argument to rev:revision-or- 504 derived. In so, any module which has that semver label as its latest 505 revision label or has that label in its revision history can be used 506 to satisfy the import requirement. For example: 508 import example-module { 509 rev:revision-or-derived "3.0.0"; 510 } 512 Note: the import lookup does not stop when a non-backward-compatible 513 change is encountered. That is, if module B imports a module A at or 514 derived from version 2.0.0, resolving that import will pass through a 515 revision of module A with version 2.1.0_non_compatible in order to 516 determine if the present instance of module A derives from 2.0.0. 518 5. Guidelines for Using Semver During Module Development 520 This section and the IETF-specific sub-section below provides YANG 521 semver-specific guidelines to consider when developing new YANG 522 modules. As such this section updates [RFC8407]. 524 Development of a brand new YANG module outside of the IETF that uses 525 YANG semver as its revision-label scheme SHOULD begin with a 0 for 526 the MAJOR version component. This allows the module to disregard 527 strict semver rules with respect to non-backwards-compatible changes 528 during its initial development. However, module developers MAY 529 choose to use the semver pre-release syntax instead with a 1 for the 530 MAJOR version component. For example, an initial module revision- 531 label might be either 0.0.1 or 1.0.0-alpha.1. If the authors choose 532 to use the 0 MAJOR version component scheme, they MAY switch to the 533 pre-release scheme with a MAJOR version component of 1 when the 534 module is nearing initial release (e.g., a module's revision label 535 may transition from 0.3.0 to 1.0.0-beta.1 to indicate it is more 536 mature and ready for testing). 538 When using pre-release notation, the format MUST include at least one 539 alphabetic component and MUST end with a '.' and then one or more 540 digits. These alphanumeric components will be used when deciding 541 pre-release precedence. The following are examples of valid pre- 542 release versions 544 1.0.0-alpha.1 546 1.0.0-alpha.3 548 2.1.0-beta.42 550 3.0.0-202007.rc.1 552 When developing a new revision of an existing module using the YANG 553 semver revision-label scheme, the intended target semver version MUST 554 be used along with pre-release notation. For example, if a released 555 module which has a current revision-label of 1.0.0 is being modified 556 with the intent to make non-backwards-compatible changes, the first 557 development MAJOR version component must be 2 with some pre-release 558 notation such as -alpha.1, making the version 2.0.0-alpha.1. That 559 said, every publicly available release of a module MUST have a unique 560 YANG semver revision-label (where a publicly available release is one 561 that could be implemented by a vendor or consumed by an end user). 562 Therefore, it may be prudent to include the year or year and month 563 development began (e.g., 2.0.0-201907-alpha.1). As a module 564 undergoes development, it is possible that the original intent 565 changes. For example, a 1.0.0 version of a module that was destined 566 to become 2.0.0 after a development cycle may have had a scope change 567 such that the final version has no non-backwards-compatible changes 568 and becomes 1.1.0 instead. This change is acceptable to make during 569 the development phase so long as pre-release notation is present in 570 both versions (e.g., 2.0.0-alpha.3 becomes 1.1.0-alpha.4). However, 571 on the next development cycle (after 1.1.0 is released), if again the 572 new target release is 2.0.0, new pre-release components must be used 573 such that every revision-label for a given module MUST be unique 574 throughout its entire lifecycle (e.g., the first pre-release version 575 might be 2.0.0-202005-alpha.1 if keeping the same year and month 576 notation mentioned above). 578 5.1. Pre-release Version Precedence 580 [TODO: Describe precedence considering there could be changes during 581 development and parallel development tracks.] 583 5.2. YANG Semver in IETF Modules 585 Net new module development within the IETF SHOULD begin with the 0 586 MAJOR number scheme as described above. When revising an existing 587 IETF module, the revision-label MUST use the target (i.e., intended) 588 MAJOR and MINOR version components with a 0 patch version component. 589 If the intended ratified release will be non-backward-compatible with 590 the current ratified release, the MINOR version component MUST be 0. 592 All IETF modules in development MUST use the whole document name as a 593 pre-release version string, including the current document revision. 594 For example, if a module which is currently released at version 1.0.0 595 is being revised to include non-backwards-compatible changes in 596 draft-user-netmod-foo, its development revision-labels MUST include 597 2.0.0-draft-user-netmod-foo followed by the document's revision 598 (e.g., 2.0.0-draft-user-netmod-foo-02). This will ensure each pre- 599 release version is unique across the lifecycle of the module. Even 600 when using the 0 MAJOR version for initial module development (where 601 MINOR and PATCH can change), appending the draft name as a pre- 602 release component helps to ensure uniqueness when there are perhaps 603 multiple, parallel efforts creating the same module. 605 If a module is being revised and the original module never had a 606 revision-label (i.e., you wish to start using YANG semver in future 607 module revisions), choose a semver value that makes the most sense 608 based on the module's history. For example, if a module started out 609 in the pre-NMDA ([RFC8342]) world, and then had NMDA support added 610 without removing any legacy "state" branches -- and you are looking 611 to add additional new features -- a sensible choice for the target 612 YANG semver would be 1.2.0 (since 1.0.0 would have been the initial, 613 pre-NMDA release, and 1.1.0 would have been the NMDA revision). 615 See Appendix A for a detailed example of IETF pre-release versions. 617 6. YANG Module 619 This YANG module contains the typedef for the YANG semantic version. 621 file "ietf-yang-semver@2019-09-06.yang" 622 module ietf-yang-semver { 623 yang-version 1.1; 624 namespace "urn:ietf:params:xml:ns:yang:ietf-yang-semver"; 625 prefix yangver; 626 rev:revision-label-scheme "yang-semver"; 628 import ietf-yang-revisions { 629 prefix rev; 630 } 632 organization 633 "IETF NETMOD (Network Modeling) Working Group"; 634 contact 635 "WG Web: 636 WG List: 638 Author: Joe Clarke 639 "; 640 description 641 "This module provides type and grouping definitions for YANG 642 packages. 644 Copyright (c) 2020 IETF Trust and the persons identified as 645 authors of the code. All rights reserved. 647 Redistribution and use in source and binary forms, with or 648 without modification, is permitted pursuant to, and subject 649 to the license terms contained in, the Simplified BSD License 650 set forth in Section 4.c of the IETF Trust's Legal Provisions 651 Relating to IETF Documents 652 (http://trustee.ietf.org/license-info). 654 This version of this YANG module is part of RFC XXXX; see 655 the RFC itself for full legal notices."; 657 // RFC Ed.: update the date below with the date of RFC publication 658 // and remove this note. 659 // RFC Ed.: replace XXXX with actual RFC number and remove this 660 // note. 662 revision 2020-06-30 { 663 rev:revision-label "1.0.0-draft-ietf-netmod-yang-semver-01"; 664 description 665 "Initial revision"; 666 reference 667 "RFC XXXX: YANG Semantic Versioning."; 668 } 669 /* 670 * Identities 671 */ 673 identity yang-semver { 674 base rev:revision-label-scheme-base-identity; 675 description 676 "The revision-label scheme corresponds to the YANG semver scheme 677 which is defined by the pattern in the 'version' typedef below. 678 The rules governing this revision-label scheme are defined in the 679 reference for this identity."; 680 reference 681 "RFC XXXX: YANG Semantic Versioning."; 682 } 684 /* 685 * Typedefs 686 */ 688 typedef version { 689 type string { 690 pattern '\d+[.]\d+[.]\d+(_(non_)?compatible)?(-[\w\d.]+)?([+][\w\d\.]+)?'; 691 } 692 description 693 "Represents a YANG semantic version number. The rules governing the 694 use of this revision label scheme are defined in the reference for 695 this typedef."; 696 reference 697 "RFC XXXX: YANG Semantic Versioning."; 698 } 699 } 700 702 7. Contributors 704 This document grew out of the YANG module versioning design team that 705 started after IETF 101. The design team consists of the following 706 members whom have worked on the YANG versioning project: 708 o Balazs Lengyel 710 o Benoit Claise 712 o Ebben Aries 714 o Jason Sterne 715 o Joe Clarke 717 o Juergen Schoenwaelder 719 o Mahesh Jethanandani 721 o Michael (Wangzitao) 723 o Qin Wu 725 o Reshad Rahman 727 o Rob Wilton 729 The initial revision of this document was refactored and built upon 730 [I-D.clacla-netmod-yang-model-update]. 732 Discussons on the use of Semver for YANG versioning has been held 733 with authors of the OpenConfig YANG models based on their own 734 [openconfigsemver]. We would like thank both Anees Shaikh and Rob 735 Shakir for their input into this problem space. 737 8. Security Considerations 739 The document does not define any new protocol or data model. There 740 are no security impacts. 742 9. IANA Considerations 744 None. 746 10. References 748 10.1. Normative References 750 [I-D.ietf-netmod-yang-module-versioning] 751 Claise, B., Clarke, J., Rahman, R., Wilton, R., Lengyel, 752 B., Sterne, J., and K. D'Souza, "Updated YANG Module 753 Revision Handling", draft-ietf-netmod-yang-module- 754 versioning-00 (work in progress), March 2020. 756 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 757 Requirement Levels", BCP 14, RFC 2119, 758 DOI 10.17487/RFC2119, March 1997, 759 . 761 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 762 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 763 May 2017, . 765 [RFC8407] Bierman, A., "Guidelines for Authors and Reviewers of 766 Documents Containing YANG Data Models", BCP 216, RFC 8407, 767 DOI 10.17487/RFC8407, October 2018, 768 . 770 10.2. Informative References 772 [I-D.clacla-netmod-yang-model-update] 773 Claise, B., Clarke, J., Lengyel, B., and K. D'Souza, "New 774 YANG Module Update Procedure", draft-clacla-netmod-yang- 775 model-update-06 (work in progress), July 2018. 777 [I-D.ietf-netmod-yang-packages] 778 Wilton, R., Rahman, R., Clarke, J., Sterne, J., and W. Bo, 779 "YANG Packages", draft-ietf-netmod-yang-packages-00 (work 780 in progress), March 2020. 782 [openconfigsemver] 783 "Semantic Versioning for Openconfig Models", 784 . 786 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 787 and R. Wilton, "Network Management Datastore Architecture 788 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 789 . 791 [semver] "Semantic Versioning 2.0.0", . 793 Appendix A. Example IETF Module Development 795 Assume a new YANG module is being developed in the netmod working 796 group in the IETF. Initially, this module is being developed in an 797 individual internet draft, draft-jdoe-netmod-example-module. The 798 following represents the initial version tree (i.e., value of 799 revision-label) of the module as it's being initially developed. 801 Version lineage for initial module development: 803 0.0.1-draft-jdoe-netmod-example-module-00 804 | 805 0.1.0-draft-jdoe-netmod-example-module-01 806 | 807 0.2.0-draft-jdoe-netmod-example-module-02 808 | 809 0.2.1-draft-jdoe-netmod-example-module-03 811 At this point, development stabilizes, and the workgroup adopts the 812 draft. Thus now the draft becomes draft-ietf-netmod-example-module. 813 The initial pre-release lineage continues as follows. 815 Continued version lineage after adoption: 817 1.0.0-draft-ietf-netmod-example-module-00 818 | 819 1.0.0-draft-ietf-netmod-example-module-01 820 | 821 1.0.0-draft-ietf-netmod-example-module-02 823 At this point, the draft is ratified and becomes RFC12345 and the 824 YANG module version number becomes 1.0.0. 826 A time later, the module needs to be revised to add additional 827 capabilities. Development will be done in a backwards-compatible 828 way. Two new individual drafts are proposed to go about adding the 829 capabilities in different ways: draft-jdoe-netmod-exmod-enhancements 830 and draft-jadoe-netmod-exmod-changes. These are initially developed 831 in parallel with the following versions. 833 Parallel development for next module revision: 835 1.1.0-draft-jdoe-netmod-exmod-enhancements-00 || 1.1.0-draft-jadoe-netmod-exmod-changes-00 836 | | 837 1.1.0-draft-jdoe-netmod-exmod-enhancements-01 || 1.1.0-draft-jadoe-netmod-exmod-changes-01 839 At this point, the WG decides to merge some aspects of both and adopt 840 the work in jadoe's draft as draft-ietf-netmod-exmod-changes. A 841 single version lineage continues. 843 1.1.0-draft-ietf-netmod-exmod-changes-00 844 | 845 1.1.0-draft-ietf-netmod-exmod-changes-01 846 | 847 1.1.0-draft-ietf-netmod-exmod-changes-02 848 | 849 1.1.0-draft-ietf-netmod-exmod-changes-03 851 The draft is ratified, and the new module version becomes 1.1.0. 853 Authors' Addresses 855 Benoit Claise 856 Cisco Systems, Inc. 857 De Kleetlaan 6a b1 858 1831 Diegem 859 Belgium 861 Phone: +32 2 704 5622 862 Email: bclaise@cisco.com 864 Joe Clarke (editor) 865 Cisco Systems, Inc. 866 7200-12 Kit Creek Rd 867 Research Triangle Park, North Carolina 868 United States of America 870 Phone: +1-919-392-2867 871 Email: jclarke@cisco.com 873 Reshad Rahman 874 Cisco Systems, Inc. 876 Email: rrahman@cisco.com 878 Robert Wilton (editor) 879 Cisco Systems, Inc. 881 Email: rwilton@cisco.com 882 Balazs Lengyel 883 Ericsson 884 Magyar Tudosok Korutja 885 1117 Budapest 886 Hungary 888 Phone: +36-70-330-7909 889 Email: balazs.lengyel@ericsson.com 891 Jason Sterne 892 Nokia 894 Email: jason.sterne@nokia.com 896 Kevin D'Souza 897 AT&T 898 200 S. Laurel Ave 899 Middletown, NJ 900 United States of America 902 Email: kd6913@att.com