idnits 2.17.1 draft-verdt-netmod-yang-solutions-02.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (November 3, 2019) is 1634 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Outdated reference: A later version (-09) exists of draft-ietf-netmod-yang-versioning-reqs-01 == Outdated reference: A later version (-03) exists of draft-rwilton-netmod-yang-packages-02 == Outdated reference: A later version (-02) exists of draft-wilton-netmod-yang-ver-selection-01 Summary: 0 errors (**), 0 flaws (~~), 4 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group R. Wilton, Ed. 3 Internet-Draft Cisco Systems, Inc. 4 Intended status: Informational November 3, 2019 5 Expires: May 6, 2020 7 YANG Versioning Solution Overview 8 draft-verdt-netmod-yang-solutions-02 10 Abstract 12 This document gives a brief overview of the different drafts that 13 comprise a full solution to the YANG versioning requirements draft. 14 The purpose of this draft is to help readers understand how the 15 discrete parts of the YANG versioning solution fit together during 16 working group development of the solution drafts. 18 Status of This Memo 20 This Internet-Draft is submitted in full conformance with the 21 provisions of BCP 78 and BCP 79. 23 Internet-Drafts are working documents of the Internet Engineering 24 Task Force (IETF). Note that other groups may also distribute 25 working documents as Internet-Drafts. The list of current Internet- 26 Drafts is at https://datatracker.ietf.org/drafts/current/. 28 Internet-Drafts are draft documents valid for a maximum of six months 29 and may be updated, replaced, or obsoleted by other documents at any 30 time. It is inappropriate to use Internet-Drafts as reference 31 material or to cite them other than as "work in progress." 33 This Internet-Draft will expire on May 6, 2020. 35 Copyright Notice 37 Copyright (c) 2019 IETF Trust and the persons identified as the 38 document authors. All rights reserved. 40 This document is subject to BCP 78 and the IETF Trust's Legal 41 Provisions Relating to IETF Documents 42 (https://trustee.ietf.org/license-info) in effect on the date of 43 publication of this document. Please review these documents 44 carefully, as they describe your rights and restrictions with respect 45 to this document. Code Components extracted from this document must 46 include Simplified BSD License text as described in Section 4.e of 47 the Trust Legal Provisions and are provided without warranty as 48 described in the Simplified BSD License. 50 Table of Contents 52 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 53 2. Solution Drafts . . . . . . . . . . . . . . . . . . . . . . . 2 54 2.1. Updated YANG Module Revision Handling . . . . . . . . . . 3 55 2.2. Module semantic version number scheme . . . . . . . . . . 4 56 2.3. Versioned YANG packages . . . . . . . . . . . . . . . . . 4 57 2.4. Protocol operations for package version selection . . . . 5 58 2.5. YANG schema comparison tooling . . . . . . . . . . . . . 5 59 3. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 6 60 4. Security Considerations . . . . . . . . . . . . . . . . . . . 6 61 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7 62 6. References . . . . . . . . . . . . . . . . . . . . . . . . . 7 63 6.1. Normative References . . . . . . . . . . . . . . . . . . 7 64 6.2. Informative References . . . . . . . . . . . . . . . . . 7 65 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 7 67 1. Introduction 69 [I-D.ietf-netmod-yang-versioning-reqs] documents the requirements for 70 any solution to the YANG [RFC7950] versioning problem. Chapter 5 71 lists the formal requirements that a complete solution requires. 73 The aim of this draft is to help readers understand how the different 74 solution drafts fit together, and also which drafts contribute 75 solutions to particular individual requirements. The overall 76 solution comprises five individual drafts: 78 1. [I-D.verdt-netmod-yang-module-versioning] 80 2. [I-D.verdt-netmod-yang-semver] 82 3. [I-D.rwilton-netmod-yang-packages] 84 4. [I-D.wilton-netmod-yang-ver-selection] 86 5. YANG schema comparison tooling (not yet published) 88 Open issues, across all of the solution drafts are tracked at 89 . 91 2. Solution Drafts 93 The complete solution to the YANG versioning requirements comprises 94 five solution drafts, that are summarized below. 96 2.1. Updated YANG Module Revision Handling 98 In summary, [I-D.verdt-netmod-yang-module-versioning] specifies 99 minimal extensions and updates to the YANG language, YANG Library, 100 and YANG author guidelines to provide more flexible YANG module 101 revision handling. The intent is that these changes and extensions 102 could be folded into future revisions of the updated specifications. 103 The draft provides a solution for all requirements except Req 2.2, 104 Req 3.1 and Req 3.2. 106 The extensions and changes in the draft can be summarized thus: 108 o It defines a YANG extension statement to indicate where non- 109 backwards-compatible changes have occurred in a module's revision 110 history. 112 o It relaxes the rules for the module revision history to allow for 113 a non-linear module revision history. I.e., any given module 114 revision may have multiple revisions directly derived from it. 116 o It defines a new import extension statement that restricts the 117 allowed module revisions that satisfy the import to only those 118 derived from a specified module revision. 120 o It defines a revision label extension statement to allow an 121 informative name to be associated with a particular revision date, 122 and to be used in import statements, YANG module filenames, and is 123 available in YANG library. One example of how the revision label 124 could be used is to associate a semantic versioning scheme to YANG 125 module revisions. 127 o It updates the YANG rules for changes between module revisions 128 that are allowed to be classified as backwards-compatible. In 129 particular, marking a node as obsolete is no longer classified as 130 a backwards compatible change. 132 o It provides updated guidance on how servers handle deprecated and 133 obsolete YANG nodes and augments YANG library with additional 134 leaves to report the server's behavior to clients. 136 o It provides an extension statement to allow a description 137 statement to be associated with a YANG status statement, providing 138 more information about why the status has changed. 140 o It defines how versioning relates to YANG instance data. 142 o It refines the guidelines for updating modules, taking into 143 consideration that non-backwards-compatible changes are sometimes 144 necessary for various pragmatic reasons. 146 2.2. Module semantic version number scheme 148 [I-D.verdt-netmod-yang-semver] defines a semantic versioning scheme 149 derived from the semver.org 2.0.0 specification that can be used in 150 conjunction with the revision label extension statement defined in 151 Section 2.1 to allow semantic version numbers to be used to manage 152 the revision lifecycle of YANG modules. This draft provides an 153 enhanced solution for Req 2.1, but organizations authoring modules 154 are not obliged to use this specific versioning scheme, and could 155 choose a different overlaid versioning scheme, or none at all and 156 rely solely on revision dates. 158 The aims of the YANG semantic versioning scheme are: 160 To generally allow clients to determine whether NBC changes have 161 occurred between two revisions from the version number alone, 162 without having to check the full revision history. 164 To give a more informative identifier for a branched revision 165 history over revision dates alone. 167 To allow revision branches that contain fixes for published non- 168 latest releases. 170 2.3. Versioned YANG packages 172 The two previous drafts address version and revision management of 173 individual modules. [I-D.rwilton-netmod-yang-packages] provides a 174 mechanism to group a set of related YANG modules revisions together, 175 into a construct called a YANG package, and to apply a version scheme 176 to the group. 178 The core part of this draft are YANG module definitions that define a 179 YANG package, that are used as an augmentation to YANG library, and 180 also in YANG instance data documents for offline access. 182 The principle aims of the packages draft are: 184 To provide an alternative simpler mechanism to manage conformance 185 of modules. Rather than checking conformance against a set of 186 individual YANG module revisions, it should be easier to check for 187 conformance against a much smaller set of YANG package versions. 189 To provide an easier mechanism for clients to check conformance 190 with a server. Rather that downloading and comparing all 191 individual module revisions, the client can just check whether the 192 package version is compatible. The package definition could be 193 retrieved and cached from multiple sources. 195 The YANG packages draft does not address any of the versioning 196 requirements directly, but provides the foundation building blocks 197 for the version selection solution, described in Section 2.4, that 198 addresses Reqs 3.1 and 3.2. 200 2.4. Protocol operations for package version selection 202 [I-D.wilton-netmod-yang-ver-selection] specifies a solution for 203 requirements 3.1 and 3.2 via the use of 204 [I-D.rwilton-netmod-yang-packages] and a protocol based version 205 selection scheme that can be used by clients to choose a particular 206 YANG datastore schema from the set of datastore schema that are 207 supported by the server. 209 The version selection optionally allows: 211 Servers to support a single, selectable YANG package at a 212 particular version, that is used for all NETCONF/RESTCONF 213 interactions. 215 Servers to support multiple selectable YANG packages and package 216 versions, with different clients able to concurrently access 217 different packages and different package versions. 219 2.5. YANG schema comparison tooling 221 A tooling based solution is proposed for Req 2.2, that allows two 222 YANG schema versions to be algorithmically compared, with the 223 algorithm reporting the list of differences between the two YANG 224 schema and whether each change is regarded as being backwards- 225 compatible, or non-backwards-compatible. Annotations to the YANG 226 modules, via the use of extension statements, may help improve the 227 accuracy of the comparison algorithm, particularly for statements 228 that are very hard to algorithmically classify the scope of any 229 differences (e.g., a change in the semantic behaviour of a data node 230 defined via modifications to the associated YANG description 231 statement). Given that Req 2.2 is a softer requirement, and 232 practical experience with the tooling is required, it is proposed 233 that this work is deferred at this time. 235 When comparing a module schema, a tool would also be able to take 236 into account enabled features, deviations, and the subset of the 237 schema being used by the client. This would allow a tooling based 238 approach to give a more accurate answer as to whether a client would 239 be affected when upgrading between two software versions, than 240 looking at the revision history, or comparing semantic version 241 numbers. 243 3. Contributors 245 This document grew out of the YANG module versioning design team that 246 started after IETF 101. The following individuals are (or have been) 247 members of that design team and have contributed to defining the 248 problem, specifying the requirements, and working on a solution: 250 o Balazs Lengyel 252 o Benoit Claise 254 o Ebben Aries 256 o Jason Sterne 258 o Joe Clarke 260 o Juergen Schoenwaelder 262 o Mahesh Jethanandani 264 o Michael (Wangzitao) 266 o Qin Wu 268 o Reshad Rahman 270 o Rob Wilton 272 o Susan Hares 274 o Wu Bo 276 4. Security Considerations 278 The document does not define any new protocol or data model. There 279 is no security impact. 281 5. IANA Considerations 283 None 285 6. References 287 6.1. Normative References 289 [I-D.ietf-netmod-yang-versioning-reqs] 290 Clarke, J., "YANG Module Versioning Requirements", draft- 291 ietf-netmod-yang-versioning-reqs-01 (work in progress), 292 July 2019. 294 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 295 RFC 7950, DOI 10.17487/RFC7950, August 2016, 296 . 298 6.2. Informative References 300 [I-D.rwilton-netmod-yang-packages] 301 Wilton, R., "YANG Packages", draft-rwilton-netmod-yang- 302 packages-02 (work in progress), October 2019. 304 [I-D.verdt-netmod-yang-module-versioning] 305 Claise, B., Clarke, J., Rahman, R., Wilton, R., Lengyel, 306 B., Sterne, J., and K. D'Souza, "Updated YANG Module 307 Revision Handling", draft-verdt-netmod-yang-module- 308 versioning-01 (work in progress), October 2019. 310 [I-D.verdt-netmod-yang-semver] 311 Claise, B., Clarke, J., Rahman, R., Wilton, R., Lengyel, 312 B., Sterne, J., and K. D'Souza, "YANG Semantic 313 Versioning", draft-verdt-netmod-yang-semver-01 (work in 314 progress), October 2019. 316 [I-D.wilton-netmod-yang-ver-selection] 317 Wilton, R., Rahman, R., and J. Clarke, "YANG Schema 318 Version Selection", draft-wilton-netmod-yang-ver- 319 selection-01 (work in progress), November 2019. 321 Author's Address 323 Robert Wilton (editor) 324 Cisco Systems, Inc. 326 Email: rwilton@cisco.com