Subject: [Netmod-ver-dt] mbj review of ang-module-versioning-01. Order in input and output.

From: "Sterne, Jason (Nokia - CA/Ottawa)" <[email-masked]>
Date: Tue, 24 Mar 2020 13:41:08 +0000

Hi guys,

About this one:
#######################################
>     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.
[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.
#######################################

I don't think 'type' and 'description' are what is meant here. It is only "data definition statements" like containers, leafs, lists, leaf-lists, etc. The order of YANG statements (like type and description) within an element is a separate issue (and reordering of those is always allowed I believe, although I vaguely remember some guidelines about it, or some canonical order exists somewhere).

I'm not sure what Rob means by "recursive". Do you simply mean all descendants ?  (children, grandchildren and so on)

Good thought on the meta-question (it was probably discussed during development of the original YANG spec).

Jason 

> -----Original Message-----
> 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]
> Subject: Re: [Netmod-ver-dt] [netmod] mbj review of draft-verdt-netmod-
> yang-module-versioning-01
> 
> 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,
> >
> >     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.
> [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.
> 
> 
> >
> >
> >     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.
> [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.
> 
> 
> >
> >     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.
> >
> [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".
> 
> >     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?
> [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.
> 
> >
> >
> >     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?
> [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.
> 
> 
> >
> >     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.
> [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.
> 
> >     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.
> [RW]
> +1
> 
> 
> >
> >       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.
> [RW]
> Regards,
> Rob
> 
> 
> >
> >
> >     /martin
> >
> >     _______________________________________________
> >     netmod mailing list
> >     [email-masked]
> >     https://www.ietf.org/mailman/listinfo/netmod
> >
> >
> > _______________________________________________
> > Netmod-ver-dt mailing list
> > [email-masked]
> > https://www.ietf.org/mailman/listinfo/netmod-ver-dt
> _______________________________________________
> Netmod-ver-dt mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/netmod-ver-dt

---

From: "Rob Wilton (rwilton)" <[email-masked]>
Date: Tue, 24 Mar 2020 22:51:37 +0000

> From: Sterne, Jason (Nokia - CA/Ottawa) <[email-masked]>
> Sent: 24 March 2020 13:41
> To: Rob Wilton (rwilton) <[email-masked]>; Reshad Rahman (rrahman)
> <[email-masked]>; [email-masked]
> Subject: mbj review of ang-module-versioning-01. Order in input and
> output.
> 
> Hi guys,
> 
> About this one:
> >            reordered, as long as they do not change the ordering or
> > any "rpc"
> >            "input" substatements.
> >
> 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.
> I don't think 'type' and 'description' are what is meant here. It is only
> "data definition statements" like containers, leafs, lists, leaf-lists,
> etc. The order of YANG statements (like type and description) within an
> element is a separate issue (and reordering of those is always allowed I
> believe, although I vaguely remember some guidelines about it, or some
> canonical order exists somewhere).
> 
> I'm not sure what Rob means by "recursive". Do you simply mean all
> descendants ?  (children, grandchildren and so on)
[RW] 
Yes, sorry, I just meant descendants.

Thanks,
Rob

> > > I just went through Martin's comments.  I will track all the
> > > comments below via issues, no objections I assume?
> > [RW]
> > 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,
> > >
> > >            reordered, as long as they do not change the ordering or
> > > any "rpc"
> > >            "input" substatements.
> > >
> > > (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.
> >
> >
> > >
> > >
> > >     o  3.3
> > >
> > > <RR> I can see the concern about ietf-yang-semver becoming the
> > > defacto versioning scheme.
> > [RW]
> >
> > 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
> > >
> > > <RR> Can be removed? I can't recall the purpose of this paragraph.
> > > The previous paragraph seems sufficient:
> > 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
> > >
> > >       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?
> > [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.
> >
> > > <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.
> >
> >
> > >
> > >     o  3.5
> > >
> > >         Alternatively, the first example could have used the
> > > revision label
> > "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:
> > >
> > >         All IETF YANG modules MUST include revision-label statements
> > > for all
> > > <RR> Jason made the good point that semantic versioning doesn't
> > > prevent linear history.
> > [RW]
> > +1
> >
> >
> > >