diff --git a/yang-semver/draft-verdt-netmod-yang-semver.xml b/yang-semver/draft-verdt-netmod-yang-semver.xml index 7b217ec..56f054f 100755 --- a/yang-semver/draft-verdt-netmod-yang-semver.xml +++ b/yang-semver/draft-verdt-netmod-yang-semver.xml @@ -143,9 +143,9 @@ I think that we should also (or perhaps alternatively) track these on Github.] -
- This document proposes updates to and - [TODO - YANGlib-bis] to address some of the requirements. It +
+
+ This document proposes updates to to address some of the requirements. It should be noted that there is also active WG discussion on the next steps towards an updated version of YANG, and potentially some of the functionality described here could be folded into an @@ -153,23 +153,40 @@ likely adversely impact when a standards based YANG module versioning solution is available for use. - - The sections listed below provide updates to . However, the design team does not believe any - of the will require a new version of the YANG language. It is - believed that the extensions as they are defined can coexist with - existing YANG 1.1 clients. - - which describes modification to - the Section 11 module update text to - advise the use of semantic versioning as described in this - document - which describes an extension to - do import by semantic version - defines an - extension that adds a child element to "status" - - + + The sections listed below provide updates to . However, the design team does not believe any + of the will require a new version of the YANG language. It is + believed that the extensions as they are defined can coexist with + existing YANG 1.1 clients. + + which describes modification to + the Section 11 module update text to + advise the use of semantic versioning as described in this + document + which describes an extension to + do import by semantic version + defines an + extension that adds a child element to "status" + + +
+
+ This document updates . defines how a datastore + schema of YANG library decides which version of an import-only + module is used for import when the definition is otherwise + ambiguous. + also augments YANG library with: + + a leaf to specify each module's YANG sema + allow each module's YANG semantic version number to + be provided. + two leaves to indicate how status 'deprecated' and status + 'obsolete' nodes are implemented by the server. + +
@@ -540,7 +557,7 @@ import example-module { semver:version 1.1.2; } - + The next example selects module versions that match, or are @@ -554,7 +571,7 @@ import example-module { import example-module { semver:version 1.1.0+; } - + The next example selects module versions that match, or are @@ -570,7 +587,7 @@ import example-module { semver:version 1.0.0-1.1.1; semver:version 1.2.0+; } - + The last example selects all module versions with a major @@ -584,7 +601,7 @@ import example-module { import example-module { semver:version 1.0.0-1.MAX.MAX; } - +
@@ -615,45 +632,79 @@ import example-module { Changes to published modules are allowed, even if they have some potential to cause interoperability problems, if the module-version YANG extension is used in the revision statement to clearly indicate the nature of the change." + TODO - Specify that changing status to "deprecated" is an BC change, and changing status to "obsolete" is an NBC change".
- The ietf-semver YANG module also specifies additional ietf-yang-library - leafs to be - added at the module and submodule levels. The first is module-version, which augments - /yanglib:yang-library/yanglib:module-set/yanglib:module. This specifies the current semantic version - of the associated module and revision in a given module-set. The related submodule-version leaf is added at - /yanglib:yang-library/yanglib:module-set/yanglib:module/yanglib:submodule to indicate the semantic version of - a submodule. - In order to satisfy the requirements 4.1 and 4.3 of that deprecated and obsolete node presence and operation are easily and clearly - known to clients, ietf-semver also augments the ietf-yang-library with two additional boolean leafs at - /yanglib:yang-library/yanglib:module-set/yanglib:module. A client can make one request of the ietf-yang-library and - know whether or a not a module that has deprecated or obsolete has those nodes implemented by the server, as opposed to - making multiple requests for each node in question. + YANG library is modified to support + semantic versioning in three ways. + + The ietf-semver YANG module augments the 'module' list in + ietf-yang-library with a 'version' leaf to optionally declare the + YANG semantic version of each module. + +
+ A YANG datastore schema, defined in + , can specify multiple + revisions of a YANG module in the schema using the 'import-only' + list, with the requirement from that only + a single revision of a YANG module may be implemented. + If a YANG module import statement does not specify a specific + version or revision withim the datastore schema then it could be + ambigous as to which module revision the import statement should + resolve to. Hence, a datastore schema constructed by a client + using the information contained in YANG library may not exactly + match the datastore schema actually used by the server. + The following rules remove the ambiguity: + If a module import statement could resolve to more than one + module revision defined in the datastore schema, and one of those + revisions is implemented (i.e., not an 'import-only' module), then + the import statement MUST resolve to the revision of the module + that is defined as being implemented by the datastore schema. + If a module import statement could resolve to more than one + module revision defined in the datastore schema, and none of those + revisions are implemented, but one of more modules revisions + specify a YANG semantic version, then the import MUST resolve to + the module with the greatest version number, according to the + rules in . + If a module import statement could resolve to more than one + module revision defined in the datastore schema, none of those + revisions are implemented, and none of the modules revisions have + a YANG semantic version number, then the import MUST resolve to + the module that has the most recent revision-date. +
+
+ The ietf-semver YANG module augments YANG library with two + leaves to allow a server to report how it handles status + 'deprecated' and status 'obsolete' nodes. The leaves are: - A boolean that indicates whether or not this server implements deprecated nodes. - The value of this leaf SHOULD be true; and if so, the server MUST implement nodes - within this module as they are documented. If specific deprecated nodes are not - implemented as documented, then they MUST be listed as deviations. This leaf defaults to true. - A boolean that indicates whether or not this server implements obsolete nodes. - The value of this leaf SHOULD be false; and if so, the server MUST NOT implement - nodes within this module. If this leaf is true, then all nodes in this module MUST - be implemented as documented in the module. Any variation of this MUST be listed as - deviations. This leaf defaults to false. + If present, this + leaf indicates that the server implements all status + 'deprecated' nodes, or otherwise uses deviations to explicitly + remove 'deprecated' nodes from the schema. If this leaf is + absent then the behavior is unspecified. + If present, this leaf + indicates that the server does not implement any status + 'obsolete' nodes, or otherwise uses devations to explicitly + add implemented 'obsolete' nodes back into the schema. If + this leaf is absent then the behaviour is unspecified. - - - If a module does not have any deprecated or obsolete nodes, the server SHOULD set the corresponding leaf above - to true. This is helpful to clients, such that if the MAJOR version number has not changed, and these booleans are - true, then a client does not have to check the status of any node for the module. - - Module compatibility can be affected if values other than the default are used for the leafs described here. - For example, if a server does - not implemennt deprecated nodes, then a given module revision may be incompatible with a previous revision where - the nodes were not deprecated. When calculating backward compatibility, the default values of these - leafs MUST be considered. From a client's point of view, if two module revisions have the same MAJOR version - but the run-time value of deprecated-nodes-present (as read from the ietf-yang-library) is false, then - compatibility MUST NOT be assumed based on the module-version alone. + + Implementations that implement the YANG semantic versioning + scheme defined in this document MUST set both the + 'deprecated-nodes-implemented' and 'obsolete-nodes-absent' leaves + because the refined module update rules in assume that this is how servers handle + 'deprecated' and 'obsolete' nodes to comply with YANG module + semantic versioning. + If a server does not set the 'deprecated-nodes-implemented' + leaf, then clients MUST NOT rely solely on the YANG module semantic + version number to determine whether two modules versions are + backwards compatible, and MUST also consider whether the status of + any nodes has changed to 'deprecated' and whether those nodes are + implemented by the server. +
diff --git a/yang-semver/ietf-semver.yang b/yang-semver/ietf-semver.yang index 63133ca..214d0a3 100644 --- a/yang-semver/ietf-semver.yang +++ b/yang-semver/ietf-semver.yang @@ -145,7 +145,7 @@ module ietf-semver { augment "/yanglib:yang-library/yanglib:module-set/yanglib:module" { description "Augmentations for the ietf-yang-library module to support semantic versioning."; - leaf module-version { + leaf version { type string { pattern '[0-9]+\.[0-9]+\.[0-9]+'; } @@ -176,17 +176,4 @@ module ietf-semver { leaf SHOULD be set to true."; } } - augment "/yanglib:yang-library/yanglib:module-set/yanglib:module/yanglib:submodule" { - description - "Augmentations for the ietf-yang-library module/submodule to support semantic versioning."; - leaf submodule-version { - type string { - pattern '[0-9]+\.[0-9]+\.[0-9]+'; - } - description - "The semantic version for this submodule in MAJOR.MINOR.PATCH format. This version - must match the semver:module-version value in specific revision of the submodule - loaded in this module-set."; - } - } }