From 3d3c42a94e0c67bb321ffc7e13a2205bfed05bec Mon Sep 17 00:00:00 2001 From: rwilton Date: Thu, 7 Mar 2019 11:35:29 +0000 Subject: [PATCH] Apply markup comments from Balazs --- .../draft-verdt-netmod-yang-semver.xml | 103 +++++++++++------- yang-semver/ietf-semver.yang | 13 ++- 2 files changed, 68 insertions(+), 48 deletions(-) diff --git a/yang-semver/draft-verdt-netmod-yang-semver.xml b/yang-semver/draft-verdt-netmod-yang-semver.xml index eb288af..13239c6 100755 --- a/yang-semver/draft-verdt-netmod-yang-semver.xml +++ b/yang-semver/draft-verdt-netmod-yang-semver.xml @@ -246,23 +246,23 @@
- The first part of the solution introduces and defines YANG Semantic - Versioning, explains how it is used with YANG modules, and the rules - associated with changing a module's semantic version number when the - module definitions are updated. + The chapter defines YANG Semantic Versioning, explains how it is + used with YANG modules, and the rules associated with changing a + module's semantic version number when the module definitions are + updated. 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 'semver:version' statement, and all 'include' + of the module's 'semver:version' statements, and all 'include' statements MUST specify the revision-date for each of the included submodules.
- The principle aim of YANG semantic versioning is to allow a - reader of a module to understand the overall significance of any + The principle aim of YANG semantic versioning is to allow a user + of a YANG module to understand the overall significance of any changes between two module revisions solely based on the semantic version number. @@ -286,23 +286,15 @@ A 'backwards-compatible' module semantic version change is where some syntax or semantic changes exists between the two - module revisions, but all changes follow the rules of "Updating a - Module" of [RFC7950], except that no elements have been changed to - status 'obsolete', and re-ordering of statements is allowed. + module revisions, but all changes follow the rules specified in + . A 'non-backwards-compatible' module semantic version change is where some syntax or semantic changes exists between the two - module revisions, and those changes do not follow the rules of - "Updating a Module", or one or more schema nodes have been changed - to status 'obsolete'. + module revisions, and those changes do not follow the rules + specified in . - - Q: Should revision-date history and semantic version be excluded - from the comparision? RW: I've assumed yes. - - Q. Does statement ordering need to be considered as part of the - comparision? RW: I think the answer should be no. RR: ordering matters for RPC/action input as per https://tools.ietf.org/html/rfc7950#section-7.5.7
@@ -331,14 +323,23 @@ by the semver.org 2.0.0 versioning scheme. - Every YANG module SHOULD include a top-level 'semver:version' - statement that specifies the YANG semantic version number for each - revision of the module. - - All 'revision' statements in YANG modules SHOULD include a - 'semver:version' substatement that specifies the YANG semantic - version number associated with that particular revision of the - module. + Every YANG module versioned using a YANG semantic versioning + scheme specifies the module's semantic version number by including + the 'semver:module-version' statement according to the following + rules: + + The module MUST include at least one revision statement. + The most recent module revision statement MUST include a + 'semver:module-version' sub-statement, that defines the module's + YANG semantic version. + The preceding module revision statement SHOULD also include a + 'semver:module-version' sub-statement, to allow the module's + semantic version history to be derived. + All other revision statements MAY include a + 'semver:module-version' sub-statement if they have an associated + YANG semantic version. + + "The YANG semver version number is expressed as a string of the @@ -353,8 +354,9 @@ 'Y' is the MINOR version. Changes in the minor version number indicate changes that are backwards-compatible to versions with - the same major version number, but a lower minor version - number. + the same major version number, but a lower minor version number, + unless either version has a patch version with an 'm' or 'M' + modifier. 'Zv' is the PATCH version and modifier. Changes in the patch version number can indicate editorial, backwards-compatible, or @@ -362,14 +364,21 @@ same major and minor version numbers, but lower patch version number, depending on what form modifier 'v' takes: - 'M' - the change represents a non-backwards-compatible change - 'm' - the change represents a backwards-compatible change If the modifier letter is absent, the change represents an editorial change + 'm' - the change represents a backwards-compatible change + 'M' - the change represents a non-backwards-compatible change + A module MUST NOT have two revisions with the same MAJOR, MINOR + and PATCH numerical values but with different patch modifier + letters. E.g., it is not allowed for a module to have both version + '1.0.0' and also '1.0.0m'. + A modules semantic version number uniquely identifies a YANG + module. Two revisions of a module that have the same semantic + version numbers MUST have the same non-whitespace content.
@@ -393,13 +402,13 @@ argument in the new module revision is calculated: If the module is being updated in a non-backwards-compatible - way, then the module version "X.Y.Z[m|M]" SHOULD be updated to + way, then the module version "X.Y.Z[m|M]" MUST be updated to "X+1.0.0" unless that module version has already been defined with different content, in which case the module version "X.Y.Z+1M MUST be used instead. If the module is being updated in a backwards-compatible way, - then the module version "X.Y.Z[m|M]" SHOULD be updated to + then the module version "X.Y.Z[m|M]" MUST be updated to "X.Y+1.0" unless that module version has already been defined with different content, in which case if the current module version is "X.Y.ZM" then it MUST be updated to "X.Y.Z+1M", or otherwise @@ -451,8 +460,6 @@ description "to be completed"; - semver:module-version "2.0.0"; - revision 2017-10-30 { description "Change the module structure"; @@ -638,7 +645,8 @@ import example-module {
-
+
+TODO - This section should just specify what the rules are RFC 7950 section 11, must be updated to allow for non-backward changes provided they follow the semantic versioning guidelines and increase the MAJOR version number when a backward incompatible @@ -651,6 +659,16 @@ import example-module { 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". + A 'backwards-compatible' module semantic version change is + where some syntax or semantic changes exists between the two + module revisions, but all changes follow the rules specified in + of "Updating a + Module" of [RFC7950], except that no elements have been changed to + status 'obsolete', and re-ordering of statements is allowed. + + Q: Should revision-date history and semantic version be excluded + from the comparision? RW: I've assumed yes. +
@@ -939,8 +957,6 @@ module ietf-semver { "This module contains a definition for a YANG 1.1 extension to express the semantic version of YANG modules."; - semver:module-version "0.3.0"; - revision 2019-02-27 { description "* Move YANG library augmentations into a separate module. @@ -1034,10 +1050,13 @@ module ietf-semver { module the updated status and update rules as this described in RFC XXXX are used. - The statement MUST only be a substatement of the 'module' and - 'revision' statementa. Zero or one module-version statement - is allowed per parent statement. No substatements are allowed. - "; + The statement MUST only be a substatement of the 'revision' + statements. Zero or one module-version statement is allowed + per parent statement. No substatements are allowed. + + 'revision' statements in submodule MAY contain a + 'module-version' statement for documentation purposes, but it + has no effect on the including module's semantic version."; reference "draft-verdt-netmod-yang-semver: YANG Semantic Versioning for Modules"; diff --git a/yang-semver/ietf-semver.yang b/yang-semver/ietf-semver.yang index a83777f..6efd5e8 100644 --- a/yang-semver/ietf-semver.yang +++ b/yang-semver/ietf-semver.yang @@ -33,8 +33,6 @@ module ietf-semver { "This module contains a definition for a YANG 1.1 extension to express the semantic version of YANG modules."; - semver:module-version "0.3.0"; - revision 2019-02-27 { description "* Move YANG library augmentations into a separate module. @@ -128,10 +126,13 @@ module ietf-semver { module the updated status and update rules as this described in RFC XXXX are used. - The statement MUST only be a substatement of the 'module' and - 'revision' statementa. Zero or one module-version statement - is allowed per parent statement. No substatements are allowed. - "; + The statement MUST only be a substatement of the 'revision' + statements. Zero or one module-version statement is allowed + per parent statement. No substatements are allowed. + + 'revision' statements in submodule MAY contain a + 'module-version' statement for documentation purposes, but it + has no effect on the including module's semantic version."; reference "draft-verdt-netmod-yang-semver: YANG Semantic Versioning for Modules";