Subject: Re: [Netmod-ver-dt] [netmod] mbj review of draft-verdt-netmod-yang-module-versioning-01

From: "Reshad Rahman (rrahman)" <[email-masked]>
Date: Wed, 18 Mar 2020 22:39:49 +0000

Hi all,

I just went through Martin's comments.  I will track all the comments below via issues, no objections I assume?

Inline.

On 2020-03-10, 3:31 PM, "netmod on behalf of Martin Björklund" <[email-masked] on behalf of [email-masked]> wrote:

    Hi,
    
    Here are my review comments of
    draft-verdt-netmod-yang-module-versioning-01.

    o  3.1.1
    
        o  In statements that have any data definition statements as
           substatements, those data definition substatements MAY be
           reordered, as long as they do not change the ordering or any "rpc"
           "input" substatements.
    
      I think this needs to capture that no descendant statements to
      "input" can be reordered.  Same for "output" (note, "input" and
      "output" in both "rpc" and "action").
<RR> Not sure about this, maybe not understanding 100%. I agree that input/output sub-elements can't be reordered (https://tools.ietf.org/html/rfc7950#section-7.5.7). But for one sub-element we reorder type and description, I don't see the issue.

    o  3.3
    
        All revision labels that match the pattern for the "version"
        typedef in the ietf-yang-semver YANG module MUST be interpreted as
        YANG semantic version numbers.
    
      I don't think this is a good idea.  Seems like a layer violation.
      What if my project use another dialect of semver, that wouldn't be
      possible with this rule.  I think this needs to be removed.
<RR> I can see the concern about ietf-yang-semver becoming the defacto versioning scheme.    
    
    o  3.3
    
        Submodules MUST NOT use revision label schemes that could be confused
        with the including module's revision label scheme.
    
      Hmm, how do I ensure that this MUST NOT is handled correctly?  What
      exactly does "could be confused with" mean?
<RR> Can be removed? I can't recall the purpose of this paragraph. The previous paragraph seems sufficient:
   The revision date and revision label within a submodule's revision
   history have no effect on the including module's revision.    
    
    o  3.3
    
          In the filename of a YANG module, where it takes the form: module-
          or-submodule-name ['@' revision-label] ( '.yang' / '.yin' )
    
      Should this section update 5.2 of RFC 7950?  I know that 5.2 just
      says "SHOULD".  But existing tools implement this SHOULD, and they
      need to be updated to handle this new convention.
    
      But I wonder if this a good idea.  It means that a tool that looks
      for a module with a certain revision date cannot simply check the
      filenames, but need to parse all available modules (wijust to find the 
<RR> If we don't do this we'll have the same problem to look for a revision label. Should we look for another convention than @ for revision-label?    

    o  3.4
    
         leaf imperial-temperature {
           type int64;
           units "degrees Fahrenheit";
           status deprecated {
             rev:status-description
               "Imperial measurements are being phased out in favor
                of their metric equivalents.  Use metric-temperature
                instead.";
           }
           description
             "Temperature in degrees Fahrenheit.";
         }
    
      I don't think rev:status-description is necessary / worth it.  This
      can easily be written with the normal description statement instead:
    
         leaf imperial-temperature {
           type int64;
           units "degrees Fahrenheit";
           status deprecated;
           description
               "Imperial measurements are being phased out in favor
                of their metric equivalents.  Use metric-temperature
                instead.
    
                Temperature in degrees Fahrenheit.";
         }
    
<RR> Strictly speaking not needed. Don't recall why we decided to add it, is it to prevent having to change the description?
    
    o  3.5
    
      The example modules should be legal YANG modules.  Use e.g. 
      "urn:example:module" as namespace.
    
      Also, the modules are missing the last "}", which confuses the
      "rfcstrip" tool.
<RR> Ack.    
    
    o 4.1.1
    
        Alternatively, the first example could have used the revision label
        "1.0.0" instead, which selects the same set of revisions/versions.
    
        import example-module {
          rev:revision-or-derived 1.0.0;
        }
    
      Shouldn't this be s/1.0.0/2.0.0/g ?
<RR> 2019-02-01 does correspond to 2.0.0

    o  5
    
      I think the module name "ietf-yl-revisions" should be changed to
      "ietf-yang-library-revisions".   "yl" is not a well-known acronym.
<RR> Good with me.    
    
    o  5.2.2
    
      Wouldn't it be better if the leaf "deprecated-nodes-implemented" and
      "obsolete-nodes-absent" were of type "boolean" rather than type
      "empty"?
<RR> The bool v/s empty philosophical battle. I think we had that discussion. I prefer Boolean, but I know others prefer empty. 
    o  7.1
    
      The text says:
    
        All IETF YANG modules MUST include revision-label statements for all
        newly published YANG modules, and all newly published revisions of
        existing YANG modules.  The revision-label MUST take the form of a
        YANG semantic version number [I-D.verdt-netmod-yang-semver].
    
      I strongly disagree with this new rule.  IETF modules use a linear
      history, so there are no reasons to use "modified semver".
<RR> Jason made the good point that semantic versioning doesn't prevent linear history.
     
      It is ok to use rev:nbc-changes if needed, though.

    o 7.1.1
    
      There is a missing " in:
    
       4.  For status "obsolete", it is RECOMMENDED to keep the "status-
           description" information, from when the node had status
           "deprecated, which is still relevant.
     HERE  -----------^
<RR> Ack.

    o  8
    
      s/CODE ENDS>/<CODE ENDS>/
    
<RR> Ack
    
    o Both YANG modules
    
      All extensions should specify the grammar; i.e., in which statements
      they can be present and which substatements they can have.
 <RR> Ack for 1st part. For substatements, isn't this specified in https://tools.ietf.org/html/rfc7950#section-7.19.1?   

Regards,
Reshad.

    /martin
    
    _______________________________________________
    netmod mailing list
    [email-masked]
    https://www.ietf.org/mailman/listinfo/netmod

---

From: "Rob Wilton (rwilton)" <[email-masked]>
Date: Thu, 19 Mar 2020 10:18:01 +0000

Hi Reshad,

Just some thoughts inline ...

> -----Original Message-----
> From: Netmod-ver-dt <[email-masked]> On Behalf Of Reshad
> Rahman (rrahman)
> Sent: 18 March 2020 22:40
> To: [email-masked]
> Subject: Re: [Netmod-ver-dt] [netmod] mbj review of draft-verdt-netmod-
> yang-module-versioning-01
> 
> Hi all,
> 
> I just went through Martin's comments.  I will track all the comments
> below via issues, no objections I assume?
[RW] 
No, tracking them as issues sounds good.

I wonder whether it might also be worth splitting the replies into separate threads for each of the issues that will require further discussion.

> 
> Inline.
> 
> On 2020-03-10, 3:31 PM, "netmod on behalf of Martin Björklund" <netmod-
> [email-masked] on behalf of [email-masked]> wrote:
> 
>     Hi,
> 
> <RR> Not sure about this, maybe not understanding 100%. I agree that
> input/output sub-elements can't be reordered
> (https://tools.ietf.org/html/rfc7950#section-7.5.7). But for one sub-
> element we reorder type and description, I don't see the issue.
[RW] 

It would be worth checking, but he might mean recursive data-definition statements (and is probably concerned about RFC 7950 section 7.14.3.1.

However, I think that there is a meta question here as to why an ordering for RPC input/output parameters actually matters, since the fields are also identified by name.

> <RR> I can see the concern about ietf-yang-semver becoming the defacto
[RW] 

I might be useful to point why we did this:

Without this, applications cannot know what versioning scheme is being used, or they have to guess (not robust), or the module would need another statement to declare what versioning scheme is being used.

>    history have no effect on the including module's revision.
[RW] 
The concern here is that a module might be version "1.0.1" and the submodule might also have version "1.0.1", and reader might assume that there is some relationship between the module and submodule version numbers, when in reality there is no relationship.  E.g. the module could be "1.0.1" and the submodule could be "4.2.1".

> <RR> If we don't do this we'll have the same problem to look for a
> revision label. Should we look for another convention than @ for revision-
> label?
[RW] 

Yes, the problem swings both ways.  If the import is by a revision label then the same issue arises.  I suspect that this will work out okay.  Modules that use a revision label, should be imported by their revision label rather than their revision date.

Putting both in the name I think would be ugly and overkill.

> <RR> Strictly speaking not needed. Don't recall why we decided to add it,
> is it to prevent having to change the description?
[RW] 

Eventually, I hope that we will change YANG to allow description under status, but until that time I think having a new statement is cleaner.

E.g. when doing a tree comparison, tooling cannot understand how the data node description changes, but could ignore the status-description. 

> <RR> The bool v/s empty philosophical battle. I think we had that
> discussion. I prefer Boolean, but I know others prefer empty.
[RW] 
I'm not sure that I care too much as long as the default behaviour is "undefined" if the leaves are not provided so that we don't break existing implementations that don't provide these leaves.

> <RR> Jason made the good point that semantic versioning doesn't prevent
[RW] 
+1

>  <RR> Ack for 1st part. For substatements, isn't this specified in
> https://tools.ietf.org/html/rfc7950#section-7.19.1?
> 
> Regards,
> Reshad.
[RW] 
Regards,
Rob

> Netmod-ver-dt mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/netmod-ver-dt

---

From: "Joe Clarke (jclarke)" <[email-masked]>
Date: Thu, 19 Mar 2020 15:09:42 +0000

> <RR> I can see the concern about ietf-yang-semver becoming the defacto versioning scheme.    

As a DT we recognized this and said that other server-like schemes would need to not match the defined pattern.  This could mean prepending another identifier.  Maybe Cisco would do IOSXE-17.2.1 as an example.  Even if we don’t standardize YANG semver, I think there needs to be a way to unambiguously know how to interpret a revision-label.

>   history have no effect on the including module's revision.    

I think that’s fine.

> <RR> If we don't do this we'll have the same problem to look for a revision label. Should we look for another convention than @ for revision-label?    

Yeah.  We raised this up when we first talked about semver for YANG modules.  I had mentioned a ‘%’.  I think others proposed a ‘#’.  I don’t have a strong preference either way, but having @FOO where FOO can either be a date or an arbitrary revision-label seems problematic.

> <RR> Strictly speaking not needed. Don't recall why we decided to add it, is it to prevent having to change the description?

With the former rev:status-description solution we make things easier to parse for a machine.  The machine/tooling can highlight specifically why a node is being deprecated vs. surfacing a lot of description text that may or may not be relevant.

Joe

---

From: "Sterne, Jason (Nokia - CA/Ottawa)" <[email-masked]>
Date: Thu, 26 Mar 2020 21:30:52 +0000

Hi guys,

We started discussing these below before Reshad raised issues for them. Should we get some of these thoughts into the GitHub issues? There are valuable points in here about *why* we proposed certain approaches in the drafts.

Jason

> From: Netmod-ver-dt <[email-masked]> On Behalf Of Rob
> Wilton (rwilton)
> Sent: Thursday, March 19, 2020 6:18 AM
> To: Reshad Rahman (rrahman) <rrahman=[email-masked]>;
> [email-masked]
> I wonder whether it might also be worth splitting the replies into separate
> threads for each of the issues that will require further discussion.
> 
> >
> > Inline.
> >
> It would be worth checking, but he might mean recursive data-definition
> statements (and is probably concerned about RFC 7950 section 7.14.3.1.
> 
> However, I think that there is a meta question here as to why an ordering for
> RPC input/output parameters actually matters, since the fields are also
> identified by name.
> 
> 
> >
> >
> >     o  3.3
> >
> Without this, applications cannot know what versioning scheme is being used,
> or they have to guess (not robust), or the module would need another
> statement to declare what versioning scheme is being used.
> 
> 
> >
> >     o  3.3
> >
> The concern here is that a module might be version "1.0.1" and the submodule
> might also have version "1.0.1", and reader might assume that there is some
> relationship between the module and submodule version numbers, when in
> reality there is no relationship.  E.g. the module could be "1.0.1" and the
> submodule could be "4.2.1".
> 
> >     o  3.3
> >
> Yes, the problem swings both ways.  If the import is by a revision label then the
> same issue arises.  I suspect that this will work out okay.  Modules that use a
> revision label, should be imported by their revision label rather than their
> revision date.
> 
> Eventually, I hope that we will change YANG to allow description under status,
> but until that time I think having a new statement is cleaner.
> 
> E.g. when doing a tree comparison, tooling cannot understand how the data
> node description changes, but could ignore the status-description.
> 
> 
> >
> >     o  3.5
> >
> I'm not sure that I care too much as long as the default behaviour is
> "undefined" if the leaves are not provided so that we don't break existing
> implementations that don't provide these leaves.
> 
> >     o  7.1
> >
> >       The text says:
> >

---

From: "Reshad Rahman (rrahman)" <[email-masked]>
Date: Thu, 26 Mar 2020 21:35:57 +0000

Jason, yes we should. I was intending on updating them after kicking off the threads with mbj.

On 2020-03-26, 5:31 PM, "Sterne, Jason (Nokia - CA/Ottawa)" <[email-masked]> wrote:

    Hi guys,

    Jason

---

From: "Sterne, Jason (Nokia - CA/Ottawa)" <[email-masked]>
Date: Thu, 26 Mar 2020 21:37:48 +0000

OK.  I was going to reply to you guys about some of the items below, but will that just create more work trying to port all this into GitHub after?  Should I hold off?

> From: Reshad Rahman (rrahman) <[email-masked]>
> Sent: Thursday, March 26, 2020 5:36 PM
> To: Sterne, Jason (Nokia - CA/Ottawa) <[email-masked]>; Rob Wilton
> (rwilton) <[email-masked]>; [email-masked]
> Subject: Re: [netmod] mbj review of draft-verdt-netmod-yang-module-
> versioning-01
> 
> 
>     We started discussing these below before Reshad raised issues for them.
> Should we get some of these thoughts into the GitHub issues? There are
> valuable points in here about *why* we proposed certain approaches in the
> drafts.
> 
>     Jason
> 
>     > > <RR> Jason made the good point that semantic versioning doesn't
> prevent
>     > > linear history.
>     > [RW]
>     > +1
>     >
>     >
>     > >

---

From: "Reshad Rahman (rrahman)" <[email-masked]>
Date: Thu, 26 Mar 2020 21:51:34 +0000

I don't mind. Up to you.

On 2020-03-26, 5:37 PM, "Sterne, Jason (Nokia - CA/Ottawa)" <[email-masked]> wrote:

---

From: "Reshad Rahman (rrahman)" <[email-masked]>
Date: Fri, 27 Mar 2020 21:05:24 +0000

FYI I am replying to Martin today. Feel free to respond to add/clarify if needed.

Regarding github issues, for now I'd rather have the discussions on the mailing lists and we update github accordingly. Do github issue updates go to WG alias? 

Regards,
Reshad.

---

From: "Sterne, Jason (Nokia - CA/Ottawa)" <[email-masked]>
Date: Fri, 27 Mar 2020 22:44:19 +0000

OK - it sounds like we won't put all the back-and-forth into GitHub anyways (just conclusions / updates after WG discussions). So I'll go ahead with some input.

Please see inline.  Where Joe commented on an issue in another fork I've pulled in his comment as well.

Jason

> statement to declare what versioning scheme is being used.

[JTS] From Joe C:

[JTS] I think it *would* be good to standardize. Yes it does remove some flexibility for other schemes. But sometimes removing flexibility is good for interop and worth it to have a common interpretation and single primary approach used in the industry. As Joe says, other schemes can exist by using prefixes or other slight differences but yang semver should "reserve" the basic pattern.

> >    history have no effect on the including module's revision.

[JTS] From Joe C:
I think that’s fine.

> submodule could be "4.2.1".

[JTS] I don't think we should preclude submodules from using yang semver when their module is using semver. We should probably adjust that paragraph that Reshad quotes to say the following:

The revision date and revision label within a submodule's revision
history are independent of the including module's revision. The module
revision information can change completely independently from the
submodules' revision information.

Then we could just remove this from the doc:
    Submodules MUST NOT use revision label schemes that could be
    confused with the including module's revision label scheme.

> Putting both in the name I think would be ugly and overkill.

[JTS] From Joe C:

[JTS] I agree we don't want both in the name. 

Our DT has been swimming in this stuff for many years so we're all comfortable with the new revision label (yang semver) and ready for it to replace revision date everywhere. I do think that long term we should move away from date and prefer yang semver. It may be hard for others to swallow in the short term though. 

If we reuse '@' I am a little worried about older tools. They would assume what comes afterwards is a date.

If we find another char or char sequence (which, as we've discussed, is not at all obvious to identify) then at least older implementations would just treat the whole name as if it was a module name without a date. Current implementations should be able to handle yang files that don't add the "@date" as a suffix (that is recommended but optional).

> node description changes, but could ignore the status-description.

[JTS] From Joe C:

[JTS] I'd lean towards just leaving this out as Martin suggests. It is probably "good enough" to just allow people to put that info into the leaf description for now. Adding that description would often correlate with a change of the status of that leaf anyways - so tools are going to flag the change. And if the status of the leaf didn't change, then we probably do want to flag the change of the description for a human to go and look into anyways.

> > <RR> 2019-02-01 does correspond to 2.0.0

[JTS] I think Martin is correct. I think we need to change the last part of section 1 to the following:

   Alternatively, the first example could have used the revision label
   "2.0.0" instead, which selects the same set of revisions/versions.

   import example-module {
     rev:revision-or-derived 2.0.0;
   }

> >       "ietf-yang-library-revisions".   "yl" is not a well-known acronym.
[JTS] Agree
> implementations that don't provide these leaves.

[JTS] I generally prefer Booleans as well.