Subject: Re: [Netmod-ver-dt] YANG Module Semver doc updates

From: Robert Wilton <[email-masked]>
Date: Thu, 7 Mar 2019 14:40:57 +0000

Hi Reshad,

Sorry for the very tardy response :-)

Comments inline ...

On 23/01/2019 14:58, Reshad Rahman (rrahman) wrote:
> Hi Rob,
>
> I just went through section 3, looks good. Here are my comments/nits:
> - Section 3, add reference to semver. I realize you have it in 3.2 but I think it's worth bringing it forward.

This should now be covered in the into and abstract.

> - Section 3.1 1st paragraph . "reader" implies human to me, is that the intent? May need clarification there.

Fixed.  Balazs also made the same comment.

> - Section 3.1 s/two modules revisions/two module revisions/

Fixed.

> - Section 3.1 s/thoses/those/

Fixed.

> - Section 3.1. For your question on statement ordering, it's important for RPC/action input as per https://tools.ietf.org/html/rfc7950#section-7.5.7

Yes, tracked as an open issue for the moment.

> - s/artibrary/arbitrary/

Fixed.

> - s/comparision/comparison/

Fixed.

> - Section 3.3 below. If we're updating the latest module version "X.Y.ZM" in a backwards compatible way, the version should be updated to " X.Y+1.0M", i.e. the M is sticky? The 1st part of the paragraph below seems to indicate it'd be updated to "X.Y+1.0". If I'm misunderstanding this, let's discuss in the meeting tomorrow.
>        If the module is being updated in a backwards-compatible way, then
>        the module version "X.Y.Z[m|M]" SHOULD 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 "X.Y.Z+1m".

Yes, the current text is wrong/ambiguous.

I've tried reworking this section to:

    The following rules define how the value for the 'semver:version'
    argument in the new module revision is calculated:

       If a module is being updated in a non-backwards-compatible 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 a module is being updated in a backwards-compatible way, then
       the next version number depends on the format of the current
       version number:

          "X.Y.Z" - the module version MUST be updated to "X.Y+1.0",
          unless that module version has already been defined with
          different content, when the module version MUST be updated to
          "X.Y.Z+1m instead".

          "X.Y.Zm" - the module version MUST be updated to "X.Y.Z+1m".

          "X.Y.ZM" - the module version MUST be updated to "X.Y.Z+1M".

       If a module is being updated in an editorial way, then the next
       version number depends on the format of the current version
       number:

          "X.Y.Z" - the module version MUST be updated to "X.Y.Z+1"

          "X.Y.Zm" - the module version MUST be updated to "X.Y.Z+1m".

          "X.Y.ZM" - the module version MUST be updated to "X.Y.Z+1M".

       YANG module semantic version numbers beginning with 0, i.e "0.X.Y"
       are regarded as beta definitions and need not follow the rules
       above.  Either the MINOR or PATCH version numbers may be updated,
       regardless of whether the changes are non-backwards-compatible,
       backwards-compatible, or editorial.

> - Section 3.3 s/begining/beginning/

Fixed.

Thanks,
Rob

>
> Regards,
> Reshad.
>
> On 2019-01-14, 10:02 AM, "Netmod-ver-dt on behalf of Robert Wilton" <[email-masked] on behalf of [email-masked]> wrote:
>
>      Hi,
>      
>      Heads up that I have pushed an updated version of
>      draft-verdt-netmod-yang-semver-00.  Primarily, this contains my initial
>      updates to section 3 on YANG semantic versioning.  Adding some
>      examples/diagrams may help this section greatly, but otherwise comments
>      are welcome.
>      
>       From the meeting on Thursday, I think that the following updates were
>      agreed:
>      
>      a) Restructure the intro sections -  Joe[but I know you have already had
>      a first pass at this]
>      b) Define YANG semver rules - Rob
>      c) Update/simplify "imports by revision" - was this Joe or Balazs?
>      d) 5. Updates to YANG 1.1 Module Update Rules, 6. Updates to
>      ietf-yang-library, 7. Deprecated and Obsolete Reasons - Ebben was going
>      to take a look a these.
>      e) Guidelines 8.1. Guidelines to YANG model authors 8.2. Guidelines to
>      YANG model clients - Reshad
>      
>      Thanks,
>      Rob
>      
>      [A copy of the doc after my updates is attached]
>      
>      
>