< draft-verdt-netmod-yang-module-versioning.txt   draft-verdt-netmod-yang-module-versioning.txt >
Network Working Group B. Claise Network Working Group B. Claise
Internet-Draft J. Clarke Internet-Draft J. Clarke
Updates: 7950 (if approved) R. Rahman Updates: 7950 (if approved) R. Rahman
Intended status: Standards Track R. Wilton, Ed. Intended status: Standards Track R. Wilton, Ed.
Expires: December 12, 2019 Cisco Systems, Inc. Expires: December 14, 2019 Cisco Systems, Inc.
B. Lengyel B. Lengyel
Ericsson Ericsson
J. Sterne J. Sterne
Nokia Nokia
K. D'Souza K. D'Souza
AT&T AT&T
June 10, 2019 June 12, 2019
Updated YANG Module Revision Handling Updated YANG Module Revision Handling
draft-verdt-netmod-yang-module-versioning-00 draft-verdt-netmod-yang-module-versioning-00
Abstract Abstract
This document specifies a new YANG module update procedure that can This document specifies a new YANG module update procedure that can
document when non-backwards-compatible changes have occurred during document when non-backwards-compatible changes have occurred during
the evolution of a YANG module. It provides a variant to the YANG the evolution of a YANG module. It provides a variant to the YANG
import statement to better represent inter-module dependencies. It import statement to better represent inter-module dependencies. It
skipping to change at page 1, line 44 skipping to change at page 1, line 44
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/. Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on December 12, 2019. This Internet-Draft will expire on December 14, 2019.
Copyright Notice Copyright Notice
Copyright (c) 2019 IETF Trust and the persons identified as the Copyright (c) 2019 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(https://trustee.ietf.org/license-info) in effect on the date of (https://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 2, line 44 skipping to change at page 2, line 44
4.1. Module import examples . . . . . . . . . . . . . . . . . 11 4.1. Module import examples . . . . . . . . . . . . . . . . . 11
5. Updates to ietf-yang-library . . . . . . . . . . . . . . . . 13 5. Updates to ietf-yang-library . . . . . . . . . . . . . . . . 13
5.1. Advertising revision-label . . . . . . . . . . . . . . . 13 5.1. Advertising revision-label . . . . . . . . . . . . . . . 13
5.2. Resolving ambiguous module imports . . . . . . . . . . . 13 5.2. Resolving ambiguous module imports . . . . . . . . . . . 13
5.3. Reporting how deprecated and obsolete nodes are handled . 14 5.3. Reporting how deprecated and obsolete nodes are handled . 14
6. Versioning of YANG instance data . . . . . . . . . . . . . . 14 6. Versioning of YANG instance data . . . . . . . . . . . . . . 14
7. Guidelines for using the YANG module update rules . . . . . . 15 7. Guidelines for using the YANG module update rules . . . . . . 15
7.1. Guidelines for YANG module authors . . . . . . . . . . . 15 7.1. Guidelines for YANG module authors . . . . . . . . . . . 15
7.1.1. Making non-backwards-compatible changes to a YANG 7.1.1. Making non-backwards-compatible changes to a YANG
module . . . . . . . . . . . . . . . . . . . . . . . 15 module . . . . . . . . . . . . . . . . . . . . . . . 15
7.2. Versioning Considerations for Clients . . . . . . . . . . 16 7.2. Versioning Considerations for Clients . . . . . . . . . . 17
8. Module Versioning Extension YANG Modules . . . . . . . . . . 17 8. Module Versioning Extension YANG Modules . . . . . . . . . . 17
9. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 23 9. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 23
10. Security Considerations . . . . . . . . . . . . . . . . . . . 23 10. Security Considerations . . . . . . . . . . . . . . . . . . . 24
11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 23 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 24
11.1. YANG Module Registrations . . . . . . . . . . . . . . . 23 11.1. YANG Module Registrations . . . . . . . . . . . . . . . 24
12. References . . . . . . . . . . . . . . . . . . . . . . . . . 24 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 24
12.1. Normative References . . . . . . . . . . . . . . . . . . 24 12.1. Normative References . . . . . . . . . . . . . . . . . . 24
12.2. Informative References . . . . . . . . . . . . . . . . . 25 12.2. Informative References . . . . . . . . . . . . . . . . . 25
Appendix A. Appendix . . . . . . . . . . . . . . . . . . . . . . 25 Appendix A. Appendix . . . . . . . . . . . . . . . . . . . . . . 26
A.1. Examples of guidelines for making NBC changes to a YANG A.1. Examples of guidelines for making NBC changes to a YANG
module . . . . . . . . . . . . . . . . . . . . . . . . . 25 module . . . . . . . . . . . . . . . . . . . . . . . . . 26
A.1.1. Removing a data node . . . . . . . . . . . . . . . . 26 A.1.1. Removing a data node . . . . . . . . . . . . . . . . 26
A.1.2. Changing the type of a leaf node . . . . . . . . . . 26 A.1.2. Changing the type of a leaf node . . . . . . . . . . 27
A.1.3. Reducing the range of a leaf node . . . . . . . . . . 27 A.1.3. Reducing the range of a leaf node . . . . . . . . . . 28
A.1.4. Changing the key of a list . . . . . . . . . . . . . 28 A.1.4. Changing the key of a list . . . . . . . . . . . . . 28
A.1.5. Renaming a node . . . . . . . . . . . . . . . . . . . 29 A.1.5. Renaming a node . . . . . . . . . . . . . . . . . . . 29
A.1.6. Changing a default value . . . . . . . . . . . . . . 30 A.1.6. Changing a default value . . . . . . . . . . . . . . 30
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 30 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 30
1. Introduction 1. Introduction
This document defines a solution to the YANG module lifecycle This document defines a solution to the YANG module lifecycle
problems described in [I-D.verdt-netmod-yang-versioning-reqs]. problems described in [I-D.verdt-netmod-yang-versioning-reqs].
Complementary documents provide a complete solution to the YANG Complementary documents provide a complete solution to the YANG
skipping to change at page 15, line 10 skipping to change at page 15, line 10
instance data set, may help a client to determine whether the instance data set, may help a client to determine whether the
instance data could also be used in conjunction with other revisions instance data could also be used in conjunction with other revisions
of the YANG schema, or other revisions of the modules that define the of the YANG schema, or other revisions of the modules that define the
schema. schema.
7. Guidelines for using the YANG module update rules 7. Guidelines for using the YANG module update rules
7.1. Guidelines for YANG module authors 7.1. Guidelines for YANG module authors
NBC changes to YANG modules may cause problems to clients, who are NBC changes to YANG modules may cause problems to clients, who are
consumers of YANG models, and SHOULD be avoided. YANG module authors consumers of YANG models, and hence YANG module authors are
are recommended to minimize NBC changes and keep changes BC whenever RECOMMENDED to minimize NBC changes and keep changes BC whenever
possible. possible.
When NBC changes are introduced, consideration should be given to the When NBC changes are introduced, consideration should be given to the
impact on clients and YANG module authors SHOULD try to mitigate that impact on clients and YANG module authors SHOULD try to mitigate that
impact. impact.
[Moved from section 4.] Using the "revision-date" statement causes [Moved from section 4.] Using the "revision-date" statement causes
overly strict import dependencies between modules and SHOULD NOT be overly strict import dependencies between modules and SHOULD NOT be
used. used.
A "rev:nbc-changes" statement SHOULD be added only if there are NBC
changes relative to the previous revision.
The YANG semantic versioning scheme applies only to YANG modules.
YANG submodules are not independently versioned by the YANG semantic
versioning scheme. Instead, if a versioned module includes one or
more submodules then those submodules are implicitly versioned as
part of the module's 'rev:revision-label' statements, and all the
module's 'include' statements MUST specify the revision-date for each
of the included submodules if any grouping from the submodules is
used by the module.
Removing old revision statements from a module's revision history
could break import by revision, and hence it is RECOMMENDED to retain
them. If all depencencies have been updated to not import specific
revisions of a module, then the corresponding revision statements can
be removed from that module. An alternative solution, if the
revision section is too long, would be remove, or curtail, the older
description statements associated with the previous revisions.
7.1.1. Making non-backwards-compatible changes to a YANG module 7.1.1. Making non-backwards-compatible changes to a YANG module
There are various valid situations where a YANG module has to be There are various valid situations where a YANG module has to be
modified in an NBC way. Here are the different ways in which this modified in an NBC way. Here are the different ways in which this
can be done: can be done:
o NBC changes can be done incrementally using the "deprecated" o NBC changes can be sometimes be done incrementally using the
status to provide clients time to adapt to NBC changes. "deprecated" status to provide clients time to adapt to NBC
changes.
o NBC changes are done at once, i.e. without using "status" o NBC changes are done at once, i.e. without using "status"
statements. This has a big impact on clients. statements. Depending on the change, this may have a big impact
on clients.
o If the server can support multiple versions of the YANG module or o If the server can support multiple versions of the YANG module or
of YANG packages(as specified in of YANG packages(as specified in
[I-D.rwilton-netmod-yang-packages]), and allows the client to [I-D.rwilton-netmod-yang-packages]), and allows the client to
select the version (as per select the version (as per
[I-D.wilton-netmod-yang-ver-selection]), then NBC changes MAY be [I-D.wilton-netmod-yang-ver-selection]), then NBC changes MAY be
done without using "status" statements. Clients would be required done without using "status" statements. Clients would be required
to select the version which they support and the NBC change would to select the version which they support and the NBC change would
have no impact on them have no impact on them
Here are some guidelines on how NBC changes can be made Here are some guidelines on how non-backwards-compatible changes can
incrementally: be made incrementally, with the assumption that deprecated nodes are
implemented by the server, and obsolete nodes are not:
1. The changes should be made gradually, e.g. a data node's status 1. The changes should be made gradually, e.g. a data node's status
SHOULD NOT be changed directly from "current" to "obsolete" (see SHOULD NOT be changed directly from "current" to "obsolete" (see
Section 4.7 of [RFC8407]), instead the status SHOULD first be Section 4.7 of [RFC8407]), instead the status SHOULD first be
marked "deprecated" and then when support is removed its status marked "deprecated" and then when support is removed its status
MUST be changed to "obsolete". Instead of using the "obsolete" MUST be changed to "obsolete". Instead of using the "obsolete"
status, the data node MAY be removed from the model but this has status, the data node MAY be removed from the model but this has
the risk of breaking modules which import the modified module. the risk of breaking modules which import the modified module.
2. A node with status "deprecated" MUST be supported for the 2. The new extension "status-description" SHOULD be used for nodes
solution described here to function properly.
3. A node with status "deprecated" SHOULD be available for at least
one year before its status is changed to "obsolete", see
Section 4.7 of [RFC8407].
4. Support for a node which is "obsolete" is indicated by the node
"obsolete-nodes-present, see Section 5.
5. The new extension "status-description" SHOULD be used for nodes
which are "obsolete" or "deprecated". which are "obsolete" or "deprecated".
6. For status "deprecated", the "status-description" SHOULD also 3. For status "deprecated", the "status-description" SHOULD also
indicate until when support for the node is guaranteed. If there indicate until when support for the node is guaranteed (if
is a replacement data node, rpc, action or notification for the known). If there is a replacement data node, rpc, action or
deprecated node, this SHOULD be stated in the "status- notification for the deprecated node, this SHOULD be stated in
description". the "status-description". The reason for deprecating the node
can also be included in the "status-description" if it is deemed
to be of potential interest to the user.
7. When obsoleting or deprecating data nodes, the "deprecated" or 4. For status "obsolete", it is RECOMMENDED to keep the "status-
description" information, from when the node had status
"deprecated, which is still relevant.
5. When obsoleting or deprecating data nodes, the "deprecated" or
"obsolete" status SHOULD be applied at the highest possible level "obsolete" status SHOULD be applied at the highest possible level
in the data tree. For example, when deprecating all data nodes in the data tree with an appropriate "status-description"
in a container, the "deprecated" status SHOULD be applied to the statement. For clarity, the "status" statement SHOULD also be
container. For clarity, the status MAY be added in all the applied to all descendent data nodes, but the "status-
affected nodes but the status-description SHOULD be added only at description" statement does not need to be repeated if it does
the highest level in the tree. not introduce any additional information.
See Appendix A.1 for examples on how NBC changes can be made. See Appendix A.1 for examples on how NBC changes can be made.
7.2. Versioning Considerations for Clients 7.2. Versioning Considerations for Clients
Guidelines for clients of modules using the new module revision Guidelines for clients of modules using the new module revision
update procedure: update procedure:
o Clients SHOULD be liberal when processing data received from a o Clients SHOULD be liberal when processing data received from a
server. For example, the server may have increased the range of server. For example, the server may have increased the range of
an operational node causing the client to receive a value which is an operational node causing the client to receive a value which is
outside the range of the YANG model revision it was coded against. outside the range of the YANG model revision it was coded against.
o Clients SHOULD monitor changes to published YANG modules through o Clients SHOULD monitor changes to published YANG modules through
their revision history, and use appropriate tooling to understand their revision history, and use appropriate tooling to understand
the specific changes between module revision. In particular, the specific changes between module revision. In particular,
clients SHOULD NOT migrate to NBC revisions of a module without clients SHOULD NOT migrate to NBC revisions of a module without
considering the specific NBC changes. understanding any potential impact of the specific NBC changes.
o Clients SHOULD plan to make changes to match published status o Clients SHOULD plan to make changes to match published status
changes. When a node's status changes from "current" to changes. When a node's status changes from "current" to
"deprecated", clients SHOULD plan to stop using that node in a "deprecated", clients SHOULD plan to stop using that node in a
timely fashion. When a node's status changes to "obsolete", timely fashion. When a node's status changes to "obsolete",
clients MUST stop using that node. clients MUST stop using that node.
8. Module Versioning Extension YANG Modules 8. Module Versioning Extension YANG Modules
YANG module with extensions for defining a module's YANG semantic YANG module with extensions for defining a module's YANG semantic
 End of changes. 18 change blocks. 
41 lines changed or deleted 60 lines changed or added

This html diff was produced by rfcdiff 1.47. The latest version is available from http://tools.ietf.org/tools/rfcdiff/