Subject: [Netmod-ver-dt] Use of modified semver

From: "Reshad Rahman (rrahman)" <[email-masked]>
Date: Mon, 30 Mar 2020 17:26:14 +0000

I am in the process of replying but Im not sure I'm getting Martin's point:
1) Don't use revision-labels
OR
2) Use revision-label but not modified semver
OR
???

============================================================

> We believe some IETF models may not follow linear history, this was
> brought up (I think) for IDR. Modified semver allows for non-linear
> history and also doesn't preclude linear history. So even if we end up
> having no IETF modules using branching, modified semver still works.

With the clarifiactions and updates in
draft-verdt-netmod-yang-module-versioning, non-linear versioning
works without modified semver.  So there is no technical reason to use
modified semver in IETF modules.

I can reluctantly accept that modified smever is published as
Experimental.  But that doesn't mean that IETF modules should use it.

On 2020-03-19, 6:18 AM, "Rob Wilton (rwilton)" <rwilton=[email-masked]> wrote:

    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

---

From: "Joe Clarke (jclarke)" <[email-masked]>
Date: Mon, 30 Mar 2020 17:46:51 +0000

> On Mar 30, 2020, at 13:26, Reshad Rahman (rrahman) <rrahman=[email-masked]> wrote:
> 

I think he’s saying that IETF should not use revision-labels.

Joe

---

From: "Sterne, Jason (Nokia - CA/Ottawa)" <[email-masked]>
Date: Mon, 30 Mar 2020 18:09:27 +0000

I'd have to think about whether he is correct that non-linear versioning works without any revision labels.  We discussed having a "parent-revision" statement at some point but dropped it. Did we make keeping the entire revision history mandatory?

Even if it is possible to track non-linear history without a revision label, having a revision-label is certainly a useful short hand summary to see how 2 different versions are different and related.

Jason

> From: Netmod-ver-dt <[email-masked]> On Behalf Of Joe
> Clarke (jclarke)
> Sent: Monday, March 30, 2020 1:47 PM
> To: Reshad Rahman (rrahman) <rrahman=[email-masked]>
> Cc: [email-masked]; Rob Wilton (rwilton)
> <rwilton=[email-masked]>
> Subject: Re: [Netmod-ver-dt] Use of modified semver
> 
> 
> 
> > On Mar 30, 2020, at 13:26, Reshad Rahman (rrahman)
> <rrahman=[email-masked]> wrote:
> >
> > On 2020-03-19, 6:18 AM, "Rob Wilton (rwilton)"
> <rwilton=[email-masked]> wrote:
> >
> >    Hi Reshad,
> >
> >    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: "Sterne, Jason (Nokia - CA/Ottawa)" <[email-masked]>
Date: Mon, 30 Mar 2020 19:51:46 +0000

Thinking about this some more, it seems fairly complicated to get a quick idea if module version X is backwards compatible with module version Y.

Take the example from our draft (and assume there is NO revision label)

          Module revision date        Revision label

            2019-01-01                 <- 1.0.0

                |

            2019-02-01                 <- 2.0.0

                |      \

            2019-03-01  \              <- 3.0.0

                |        \

                |       2019-04-01     <- 2.1.0

                |           |

                |       2019-05-01     <- 2.2.0

                |

            2019-06-01                 <- 3.1.0

If I want to know if 2019-06-01 is BC with 2019-05-01 I'd have to do the following:

1) check the revision statements the two docs to find a common ancestor.  That would be 2019-02-01 in this case. But that can only be done if all the revision history is kept (and we don't mandate that).

2) check the revision history in both docs for NBC changes (i.e. the rev:nbc-changes; statement in the revision containers) up to that common ancestor. Again relies on complete history.

Am I missing something? Is there an easier way without the revision label?

Jason

> From: Netmod-ver-dt <[email-masked]> On Behalf Of Sterne,

> Jason (Nokia - CA/Ottawa)

> Sent: Monday, March 30, 2020 2:09 PM

> To: Joe Clarke (jclarke) <jclarke=[email-masked]>; Reshad

> Rahman (rrahman) <rrahman=[email-masked]>

> I'd have to think about whether he is correct that non-linear versioning works

> without any revision labels.  We discussed having a "parent-revision"

> statement at some point but dropped it. Did we make keeping the entire

> revision history mandatory?

> Even if it is possible to track non-linear history without a revision label, having

> a revision-label is certainly a useful short hand summary to see how 2 different

> versions are different and related.

> > From: Netmod-ver-dt <[email-masked]<mailto:[email-masked]>> On Behalf Of Joe

> > To: Reshad Rahman (rrahman) <rrahman=[email-masked]<mailto:rrahman=[email-masked]>>

> > Cc: [email-masked]<mailto:[email-masked]>; Rob Wilton (rwilton)

> > <rwilton=[email-masked]<mailto:rwilton=[email-masked]>>

> > <rrahman=[email-masked]<mailto:rrahman=[email-masked]>> wrote:

> > <rwilton=[email-masked]<mailto:rwilton=[email-masked]>> wrote:

> > >> From: Netmod-ver-dt <[email-masked]<mailto:[email-masked]>> On Behalf Of

> > Reshad

> > >> To: [email-masked]<mailto:[email-masked]>

> > >> On 2020-03-10, 3:31 PM, "netmod on behalf of Martin Björklund"

> <netmod-

> > >> [email-masked]<mailto:[email-masked]> on behalf of [email-masked]<mailto:[email-masked]>> wrote:

> > >    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

> > >> <RR> Jason made the good point that semantic versioning doesn't

> prevent

> > >>    [email-masked]<mailto:[email-masked]>

> > >> [email-masked]<mailto:[email-masked]>

> > > [email-masked]<mailto:[email-masked]>

> > [email-masked]<mailto:[email-masked]>

> [email-masked]<mailto:[email-masked]>

---

From: "Joe Clarke (jclarke)" <[email-masked]>
Date: Mon, 30 Mar 2020 20:00:00 +0000

On Mar 30, 2020, at 15:51, Sterne, Jason (Nokia - CA/Ottawa) <[email-masked]<mailto:[email-masked]>> wrote:

Not that I see.  This is why I feel the label makes sense for humans.  The counter-argument is that with proper tooling, we wouldn’t need this.  Plus, IETF modules should never be non-backwards compatible.  Again, those are what I think are counter-arguments, but not great reasons why we wouldn’t want to have a way to quickly clue in a consumer as to whether or not two modules are compatible with each other.

Joe

Jason

> From: Netmod-ver-dt <[email-masked]<mailto:[email-masked]>> On Behalf Of Sterne,
> To: Joe Clarke (jclarke) <jclarke=[email-masked]<mailto:jclarke=[email-masked]>>; Reshad
> Rahman (rrahman) <rrahman=[email-masked]<mailto:rrahman=[email-masked]>>

---

From: "Sterne, Jason (Nokia - CA/Ottawa)" <[email-masked]>
Date: Mon, 30 Mar 2020 20:04:54 +0000

I'm not sure that anyone is currently arguing that IETF modules will always be BC.  Martin seems to be saying they are linear but there could still be an NBC change in a linear IETF module (e.g. L3 SM).

Even with linear, you'd have to look at all intermediate revision statements (and hope they are all still in there) to see if one of them has rev:nbc-changes.

Jason

From: Joe Clarke (jclarke) <[email-masked]>
Sent: Monday, March 30, 2020 4:00 PM
To: Sterne, Jason (Nokia - CA/Ottawa) <[email-masked]>
Cc: Reshad Rahman (rrahman) <[email-masked]>; [email-masked]; Rob Wilton (rwilton) <[email-masked]>
Subject: Re: [Netmod-ver-dt] Use of modified semver

Joe

Jason

---

From: "Reshad Rahman (rrahman)" <[email-masked]>
Date: Mon, 30 Mar 2020 20:15:49 +0000

From what I recall, the revision-label (or whatever it was initially called) was added to easily be able to know in many/most cases whether 2 revisions are BC or not. Even if tooling can do the (N)BC check, it’s useful for a user to say “yes 2.1.0 is BC with 2.0.0”, “no 3.0.0 is NBC with 2.0.0” without any tooling.

From: "Sterne, Jason (Nokia - CA/Ottawa)" <[email-masked]>
Date: Monday, March 30, 2020 at 4:05 PM
To: "Joe Clarke (jclarke)" <[email-masked]>
Cc: "Reshad Rahman (rrahman)" <[email-masked]>, "[email-masked]" <[email-masked]>, "Rob Wilton (rwilton)" <[email-masked]>
Subject: RE: [Netmod-ver-dt] Use of modified semver

Jason

Joe

Jason

---

From: "Sterne, Jason (Nokia - CA/Ottawa)" <[email-masked]>
Date: Mon, 30 Mar 2020 20:25:07 +0000

and without manually scanning up through (a hopefully complete) revision history (or two)

From: Reshad Rahman (rrahman) <[email-masked]>
Sent: Monday, March 30, 2020 4:16 PM
To: Sterne, Jason (Nokia - CA/Ottawa) <[email-masked]>; Joe Clarke (jclarke) <[email-masked]>
Cc: [email-masked]; Rob Wilton (rwilton) <[email-masked]>
Subject: Re: [Netmod-ver-dt] Use of modified semver

From: "Sterne, Jason (Nokia - CA/Ottawa)" <[email-masked]<mailto:[email-masked]>>
Date: Monday, March 30, 2020 at 4:05 PM
To: "Joe Clarke (jclarke)" <[email-masked]<mailto:[email-masked]>>
Cc: "Reshad Rahman (rrahman)" <[email-masked]<mailto:[email-masked]>>, "[email-masked]<mailto:[email-masked]>" <[email-masked]<mailto:[email-masked]>>, "Rob Wilton (rwilton)" <[email-masked]<mailto:[email-masked]>>
Subject: RE: [Netmod-ver-dt] Use of modified semver

Jason

From: Joe Clarke (jclarke) <[email-masked]<mailto:[email-masked]>>
Sent: Monday, March 30, 2020 4:00 PM
To: Sterne, Jason (Nokia - CA/Ottawa) <[email-masked]<mailto:[email-masked]>>
Cc: Reshad Rahman (rrahman) <[email-masked]<mailto:[email-masked]>>; [email-masked]<mailto:[email-masked]>; Rob Wilton (rwilton) <[email-masked]<mailto:[email-masked]>>
Subject: Re: [Netmod-ver-dt] Use of modified semver

Joe

Jason

---

From: "Joe Clarke (jclarke)" <[email-masked]>
Date: Mon, 30 Mar 2020 20:25:51 +0000

On Mar 30, 2020, at 16:15, Reshad Rahman (rrahman) <[email-masked]<mailto:[email-masked]>> wrote:

Yes, that’s what I recall as well.  Even with a fully-BC world, knowing that module@2020-04-01 at version 1.1.0 has some new features compared to module@2019-01-04 at 1.0.0 means I can dive deeper into what’s changed.  Quick and easy.

Now Martin and Andy’s latest comments imply YANG semver is too complicated and not needed when compared to semver 2.0.0.  But YANG semver is a superset.  One _could_ use plain ol’ semver and be just fine.  But maybe they don’t want to implement the parsing logic for YANG semver?

Joe

Jason

Joe

Jason

---

From: "Sterne, Jason (Nokia - CA/Ottawa)" <[email-masked]>
Date: Mon, 30 Mar 2020 20:45:04 +0000

Yes - it is a superset. If IETF modules don't branch then they won't see the m or M.  But if they ever do branch then the m or M may be needed to help describe what has happened.

From: Joe Clarke (jclarke) <[email-masked]>
Sent: Monday, March 30, 2020 4:26 PM
To: Reshad Rahman (rrahman) <[email-masked]>
Cc: Sterne, Jason (Nokia - CA/Ottawa) <[email-masked]>; [email-masked]; Rob Wilton (rwilton) <[email-masked]>
Subject: Re: [Netmod-ver-dt] Use of modified semver

Joe

Jason

Joe

Jason