From 8f252dd284e1d6e6225ccf5736dad1c45a8fd8a6 Mon Sep 17 00:00:00 2001 From: rwilton Date: Wed, 23 Oct 2019 16:26:04 +0100 Subject: [PATCH] Minor updates to the solution overview draft --- .../draft-verdt-netmod-yang-solutions.txt | 248 +++++++----------- .../draft-verdt-netmod-yang-solutions.xml | 112 +++----- 2 files changed, 137 insertions(+), 223 deletions(-) diff --git a/yang-solutions/draft-verdt-netmod-yang-solutions.txt b/yang-solutions/draft-verdt-netmod-yang-solutions.txt index 6d1d510..23f69e4 100644 --- a/yang-solutions/draft-verdt-netmod-yang-solutions.txt +++ b/yang-solutions/draft-verdt-netmod-yang-solutions.txt @@ -2,14 +2,14 @@ -Network Working Group R. Wilton +Network Working Group R. Wilton, Ed. Internet-Draft Cisco Systems, Inc. -Intended status: Informational May 31, 2019 -Expires: December 2, 2019 +Intended status: Informational October 23, 2019 +Expires: April 25, 2020 YANG Versioning Solution Overview - draft-verdt-netmod-yang-solutions-02 + draft-verdt-netmod-yang-solutions-01 Abstract @@ -34,7 +34,7 @@ Status of This Memo time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." - This Internet-Draft will expire on December 2, 2019. + This Internet-Draft will expire on April 25, 2020. Copyright Notice @@ -53,45 +53,42 @@ Copyright Notice -Wilton Expires December 2, 2019 [Page 1] +Wilton Expires April 25, 2020 [Page 1] -Internet-Draft YANG Versioning Solution Overview May 2019 +Internet-Draft YANG Versioning Solution Overview October 2019 Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 - 2. Summary of requirements . . . . . . . . . . . . . . . . . . . 3 - 3. Solution Drafts . . . . . . . . . . . . . . . . . . . . . . . 4 - 3.1. Updated YANG Module Revision Handling . . . . . . . . . . 4 - 3.2. Module semantic version number scheme . . . . . . . . . . 5 - 3.3. Versioned YANG packages . . . . . . . . . . . . . . . . . 5 - 3.4. Protocol operations for package version selection . . . . 6 - 3.5. YANG schema comparison tooling . . . . . . . . . . . . . 6 - 4. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 7 - 5. Security Considerations . . . . . . . . . . . . . . . . . . . 7 - 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7 - 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 8 - 7.1. Normative References . . . . . . . . . . . . . . . . . . 8 - 7.2. Informative References . . . . . . . . . . . . . . . . . 8 - Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 8 + 2. Solution Drafts . . . . . . . . . . . . . . . . . . . . . . . 2 + 2.1. Updated YANG Module Revision Handling . . . . . . . . . . 3 + 2.2. Module semantic version number scheme . . . . . . . . . . 4 + 2.3. Versioned YANG packages . . . . . . . . . . . . . . . . . 4 + 2.4. Protocol operations for package version selection . . . . 5 + 2.5. YANG schema comparison tooling . . . . . . . . . . . . . 5 + 3. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 6 + 4. Security Considerations . . . . . . . . . . . . . . . . . . . 6 + 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7 + 6. References . . . . . . . . . . . . . . . . . . . . . . . . . 7 + 6.1. Normative References . . . . . . . . . . . . . . . . . . 7 + 6.2. Informative References . . . . . . . . . . . . . . . . . 7 + Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 7 1. Introduction - TODO - Fixup references to individual drafts. - [I-D.ietf-netmod-yang-versioning-reqs] documents the requirements for - any solution to the YANG versioning problem. Chapter 5 lists the - formal requirements that a complete solution requires. + any solution to the YANG [RFC7950] versioning problem. Chapter 5 + lists the formal requirements that a complete solution requires. The aim of this draft is to help readers understand how the different solution drafts fit together, and also which drafts contribute solutions to particular individual requirements. The overall solution comprises five individual drafts: - 1. Module revision extensions + 1. [I-D.verdt-netmod-yang-module-versioning] - 2. Module semantic version number scheme + 2. [I-D.verdt-netmod-yang-semver] 3. [I-D.rwilton-netmod-yang-packages] @@ -102,87 +99,30 @@ Table of Contents Open issues, across all of the solution drafts are tracked at . +2. Solution Drafts + The complete solution to the YANG versioning requirements comprises + five solution drafts, that are summarized below. -Wilton Expires December 2, 2019 [Page 2] - -Internet-Draft YANG Versioning Solution Overview May 2019 - - -2. Summary of requirements - - The requirements are formally documented in section 5 of - [I-D.ietf-netmod-yang-versioning-reqs]. A shortened, non normative, - summary of each of the requirements (using the same requirement - numbers) is provided below to help understand how the solutions - drafts address the particular requirements. - - Req 1.1 - MUST allow nbc updates to a module without breaking - imports. - - Req 1.2 - MUST allow nbc updates to a module without affecting - existing client code using only unchanged data nodes. - - Req 1.3 - MUST support import statement restricted to only some - revisions. - - Req 1.4 - MUST allow for fixes to non-latest published modules. - - Req 2.1 - MUST be able to determine if two arbitrary versions of - any module are backwards-compatible. - - Req 2.2 - SHOULD be able to determine if two arbitrary versions of - any data node are backwards-compatible. - - Req 3.1 - MUST allow servers to support existing clients. - - Req 3.2 - MUST allow simultaneously support of clients using - different (perhaps restricted) revisions. - - Req 3.3 - MAY assume clients can handle unexpected instance data - gracefully. - - Req 4.1 - MUST provide a way to indicate if deprecated nodes are - implemented. - - Req 4.2 - MUST be able to document the reason for data node - lifecycle changes, and possible alternative data nodes. - - Req 4.3 - MUST be able to forewarn of future data node lifecycle - changes. - - Req 5.1 - MUST provide guidance on how to use the new scheme. - - Req 5.2 - MUST provide, and document, an upgrade path from - existing YANG/protocols. - - Req 5.3 - MUST consider the impact of versioning on instance data. - - - -Wilton Expires December 2, 2019 [Page 3] +Wilton Expires April 25, 2020 [Page 2] -Internet-Draft YANG Versioning Solution Overview May 2019 +Internet-Draft YANG Versioning Solution Overview October 2019 -3. Solution Drafts +2.1. Updated YANG Module Revision Handling - The complete solution to the YANG versioning requirements comprises - five solution drafts, that are summarized below. - -3.1. Updated YANG Module Revision Handling - - In summary, [TODO - Insert draft ref] specifies minimal extensions - and updates to the YANG language, YANG Library, and YANG author - guidelines to provide more flexible YANG module revision handling. - The intent is that these changes and extensions could be folded into - future revisions of the updated specifications. The draft provides a - solution for all requirements except Req 2.2, Req 3.1 and Req 3.2. + In summary, [I-D.verdt-netmod-yang-module-versioning] specifies + minimal extensions and updates to the YANG language, YANG Library, + and YANG author guidelines to provide more flexible YANG module + revision handling. The intent is that these changes and extensions + could be folded into future revisions of the updated specifications. + The draft provides a solution for all requirements except Req 2.2, + Req 3.1 and Req 3.2. The extensions and changes in the draft can be summarized thus: @@ -218,26 +158,28 @@ Internet-Draft YANG Versioning Solution Overview May 2019 statement to be associated with a YANG status statement, providing more information about why the status has changed. + o It defines how versioning relates to YANG instance data. + -Wilton Expires December 2, 2019 [Page 4] - -Internet-Draft YANG Versioning Solution Overview May 2019 - o It defines how versioning relates to YANG instance data. +Wilton Expires April 25, 2020 [Page 3] + +Internet-Draft YANG Versioning Solution Overview October 2019 + o It refines the guidelines for updating modules, taking into consideration that non-backwards-compatible changes are sometimes necessary for various pragmatic reasons. -3.2. Module semantic version number scheme +2.2. Module semantic version number scheme - [TODO - Insert draft ref] defines a semantic versioning scheme + [I-D.verdt-netmod-yang-semver] defines a semantic versioning scheme derived from the semver.org 2.0.0 specification that can be used in conjunction with the revision label extension statement defined in - Section 3.1 to allow semantic version numbers to be used to manage + Section 2.1 to allow semantic version numbers to be used to manage the revision lifecycle of YANG modules. This draft provides an enhanced solution for Req 2.1, but organizations authoring modules are not obliged to use this specific versioning scheme, and could @@ -256,7 +198,7 @@ Internet-Draft YANG Versioning Solution Overview May 2019 To allow revision branches that contain fixes for published non- latest releases. -3.3. Versioned YANG packages +2.3. Versioned YANG packages The two previous drafts address version and revision management of individual modules. [I-D.rwilton-netmod-yang-packages] provides a @@ -277,9 +219,11 @@ Internet-Draft YANG Versioning Solution Overview May 2019 -Wilton Expires December 2, 2019 [Page 5] + + +Wilton Expires April 25, 2020 [Page 4] -Internet-Draft YANG Versioning Solution Overview May 2019 +Internet-Draft YANG Versioning Solution Overview October 2019 To provide an easier mechanism for clients to check conformance @@ -290,13 +234,13 @@ Internet-Draft YANG Versioning Solution Overview May 2019 The YANG packages draft does not address any of the versioning requirements directly, but provides the foundation building blocks - for the version selection solution, described in Section 3.4, that + for the version selection solution, described in Section 2.4, that addresses Reqs 3.1 and 3.2. -3.4. Protocol operations for package version selection +2.4. Protocol operations for package version selection [I-D.wilton-netmod-yang-ver-selection] specifies a solution for - requirements 3.1 and 3.2 is via the use of + requirements 3.1 and 3.2 via the use of [I-D.rwilton-netmod-yang-packages] and a protocol based version selection scheme that can be used by clients to choose a particular YANG datastore schema from the set of datastore schema that are @@ -312,7 +256,7 @@ Internet-Draft YANG Versioning Solution Overview May 2019 versions, with different clients able to concurrently access different packages and different package versions. -3.5. YANG schema comparison tooling +2.5. YANG schema comparison tooling A tooling based solution is proposed for Req 2.2, that allows two YANG schema versions to be algorithmically compared, with the @@ -333,9 +277,9 @@ Internet-Draft YANG Versioning Solution Overview May 2019 -Wilton Expires December 2, 2019 [Page 6] +Wilton Expires April 25, 2020 [Page 5] -Internet-Draft YANG Versioning Solution Overview May 2019 +Internet-Draft YANG Versioning Solution Overview October 2019 schema being used by the client. This would allow a tooling based @@ -344,12 +288,12 @@ Internet-Draft YANG Versioning Solution Overview May 2019 looking at the revision history, or comparing semantic version numbers. -4. Contributors +3. Contributors This document grew out of the YANG module versioning design team that - started after IETF 101. The following people are (or have been) + started after IETF 101. The following individuals are (or have been) members of that design team and have contributed to defining the - problem and specifying the requirements: + problem, specifying the requirements, and working on a solution: o Balazs Lengyel @@ -375,74 +319,74 @@ Internet-Draft YANG Versioning Solution Overview May 2019 o Susan Hares -5. Security Considerations + o Wu Bo + +4. Security Considerations The document does not define any new protocol or data model. There is no security impact. -6. IANA Considerations - None -Wilton Expires December 2, 2019 [Page 7] +Wilton Expires April 25, 2020 [Page 6] -Internet-Draft YANG Versioning Solution Overview May 2019 +Internet-Draft YANG Versioning Solution Overview October 2019 + +5. IANA Considerations + + None -7. References +6. References -7.1. Normative References +6.1. Normative References [I-D.ietf-netmod-yang-versioning-reqs] Clarke, J., "YANG Module Versioning Requirements", draft- - ietf-netmod-yang-versioning-reqs-00 (work in progress), - March 2019. + ietf-netmod-yang-versioning-reqs-01 (work in progress), + July 2019. + + [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", + RFC 7950, DOI 10.17487/RFC7950, August 2016, + . + +6.2. Informative References [I-D.rwilton-netmod-yang-packages] Wilton, R., "YANG Packages", draft-rwilton-netmod-yang- packages-01 (work in progress), March 2019. + [I-D.verdt-netmod-yang-module-versioning] + Claise, B., Clarke, J., Rahman, R., Wilton, R., Lengyel, + B., Sterne, J., and K. D'Souza, "Updated YANG Module + Revision Handling", draft-verdt-netmod-yang-module- + versioning-01 (work in progress), October 2019. + + [I-D.verdt-netmod-yang-semver] + Claise, B., Clarke, J., Rahman, R., Wilton, R., Lengyel, + B., Sterne, J., and K. D'Souza, "YANG Semantic + Versioning", draft-verdt-netmod-yang-semver-01 (work in + progress), October 2019. + [I-D.wilton-netmod-yang-ver-selection] Wilton, R. and R. Rahman, "YANG Schema Version Selection", draft-wilton-netmod-yang-ver-selection-00 (work in progress), March 2019. - [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate - Requirement Levels", BCP 14, RFC 2119, - DOI 10.17487/RFC2119, March 1997, - . - - [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", - RFC 7950, DOI 10.17487/RFC7950, August 2016, - . - -7.2. Informative References - - [RFC8049] Litkowski, S., Tomotaki, L., and K. Ogaki, "YANG Data - Model for L3VPN Service Delivery", RFC 8049, - DOI 10.17487/RFC8049, February 2017, - . - - [RFC8199] Bogdanovic, D., Claise, B., and C. Moberg, "YANG Module - Classification", RFC 8199, DOI 10.17487/RFC8199, July - 2017, . - - [RFC8299] Wu, Q., Ed., Litkowski, S., Tomotaki, L., and K. Ogaki, - "YANG Data Model for L3VPN Service Delivery", RFC 8299, - DOI 10.17487/RFC8299, January 2018, - . - Author's Address - Robert Wilton + Robert Wilton (editor) Cisco Systems, Inc. + Email: rwilton@cisco.com + + -Wilton Expires December 2, 2019 [Page 8] +Wilton Expires April 25, 2020 [Page 7] diff --git a/yang-solutions/draft-verdt-netmod-yang-solutions.xml b/yang-solutions/draft-verdt-netmod-yang-solutions.xml index 41304da..6395aee 100644 --- a/yang-solutions/draft-verdt-netmod-yang-solutions.xml +++ b/yang-solutions/draft-verdt-netmod-yang-solutions.xml @@ -19,13 +19,19 @@ - + YANG Versioning Solution Overview - - Cisco Systems, Inc. + + + Cisco Systems, Inc. + +
+ rwilton@cisco.com +
+ @@ -40,17 +46,16 @@
- TODO - Fixup references to individual drafts. documents the - requirements for any solution to the YANG versioning problem. Chapter 5 + requirements for any solution to the YANG versioning problem. Chapter 5 lists the formal requirements that a complete solution requires. The aim of this draft is to help readers understand how the different solution drafts fit together, and also which drafts contribute solutions to particular individual requirements. The overall solution comprises five individual drafts: - Module revision extensions - Module semantic version number scheme + + YANG schema comparison tooling (not yet published) @@ -61,55 +66,18 @@ target="https://github.com/netmod-wg/yang-ver-dt/issues"/>.
-
- The requirements are formally documented in section 5 of . A shortened, non - normative, summary of each of the requirements (using the same requirement - numbers) is provided below to help understand how the solutions drafts - address the particular requirements. - - - Req 1.1 - MUST allow nbc updates to a module without breaking - imports. - Req 1.2 - MUST allow nbc updates to a module without affecting - existing client code using only unchanged data nodes. - Req 1.3 - MUST support import statement restricted to only some - revisions. - Req 1.4 - MUST allow for fixes to non-latest published modules. - Req 2.1 - MUST be able to determine if two arbitrary versions of - any module are backwards-compatible. - Req 2.2 - SHOULD be able to determine if two arbitrary versions of - any data node are backwards-compatible. - Req 3.1 - MUST allow servers to support existing clients. - Req 3.2 - MUST allow simultaneously support of clients using - different (perhaps restricted) revisions. - Req 3.3 - MAY assume clients can handle unexpected instance data - gracefully. - Req 4.1 - MUST provide a way to indicate if deprecated nodes are - implemented. - Req 4.2 - MUST be able to document the reason for data node - lifecycle changes, and possible alternative data nodes. - Req 4.3 - MUST be able to forewarn of future data node lifecycle - changes. - Req 5.1 - MUST provide guidance on how to use the new scheme. - Req 5.2 - MUST provide, and document, an upgrade path from existing - YANG/protocols. - Req 5.3 - MUST consider the impact of versioning on instance - data. - - -
-
The complete solution to the YANG versioning requirements comprises five solution drafts, that are summarized below.
- In summary, [TODO - Insert draft ref] specifies minimal extensions and updates to - the YANG language, YANG Library, and YANG author guidelines to provide - more flexible YANG module revision handling. The intent is that these - changes and extensions could be folded into future revisions of the - updated specifications. The draft provides a solution for all - requirements except Req 2.2, Req 3.1 and Req 3.2. + In summary, specifies + minimal extensions and updates to the YANG language, YANG + Library, and YANG author guidelines to provide more flexible + YANG module revision handling. The intent is that these + changes and extensions could be folded into future revisions + of the updated specifications. The draft provides a solution + for all requirements except Req 2.2, Req 3.1 and Req 3.2. The extensions and changes in the draft can be summarized thus: It defines a YANG extension statement to indicate where @@ -143,15 +111,17 @@
- [TODO - Insert draft ref] defines a semantic versioning scheme derived from the - semver.org 2.0.0 specification that can be used in conjunction with the + defines a + semantic versioning scheme derived from the semver.org 2.0.0 + specification that can be used in conjunction with the revision label extension statement defined in to allow semantic version numbers to be - used to manage the revision lifecycle of YANG modules. This draft - provides an enhanced solution for Req 2.1, but organizations authoring - modules are not obliged to use this specific versioning scheme, and - could choose a different overlaid versioning scheme, or none at all and - rely solely on revision dates. + target="module_versioning"/> to allow semantic version numbers + to be used to manage the revision lifecycle of YANG modules. + This draft provides an enhanced solution for Req 2.1, but + organizations authoring modules are not obliged to use this + specific versioning scheme, and could choose a different + overlaid versioning scheme, or none at all and rely solely on + revision dates. The aims of the YANG semantic versioning scheme are: To generally allow clients to determine whether NBC @@ -196,7 +166,7 @@
- specifies a solution for requirements 3.1 and 3.2 is via the + specifies a solution for requirements 3.1 and 3.2 via the use of and a protocol based version selection scheme that can be used by clients to choose a particular YANG datastore schema from the @@ -235,10 +205,11 @@
- This document grew out of the YANG module versioning design team that - started after IETF 101. The following individuals are (or have been) members of - that design team and have contributed to defining the problem and specifying - the requirements: + This document grew out of the YANG module versioning design + team that started after IETF 101. The following individuals are + (or have been) members of that design team and have contributed to + defining the problem, specifying the requirements, and working on + a solution: Balazs Lengyel @@ -253,6 +224,7 @@ Reshad Rahman Rob Wilton Susan Hares + Wu Bo
@@ -271,15 +243,13 @@ - - - - - - + + + +