Subject: Re: [netmod] WG Last Call: draft-ietf-netmod-yang-semver-06

From: Jürgen Schönwälder <[email-masked]>
Date: Sun, 6 Mar 2022 12:09:29 +0100

Hi,

below is my last call review.

Document: draft-ietf-netmod-yang-semver-06
Date: 2022-03-06

* 1. Introduction

  s/for updating modules/for updating YANG modules/

  s/extended [semver] rules/extended semantic versioning rules [semver]/

  Thanks for the text pointing out that the semantic versioning specs
  change in non-backwards-compatible ways without bumping the version
  of the versioning specs. Its like saying "the truth about semantic
  versioning rules is that they are merely guidelines but not any hard
  rules".

  BTW, is it Semver or SemVer? And since this is not really SemVer,
  should there be an acronym that makes it clear that this is not
  really SemVer?

* 3.1. YANG Semver Pattern

  It may be useful to spell out where you follow [semver] and where
  not. The _COMPAT suffix seems to be something new that I did not
  spot in [semver].

  I am somewhat surprised by the _COMPAT suffix that can declare a
  patch update to be non-compatible. [semver] says that Z is for
  "backwards compatible bug fixes". If so, how can you have a
  backwards compatible bug fix that is not backwards compatible?

* 3.2. Examples for YANG semantic versions

     Looking at the version number alone does not indicate ancestry.  The
     module definition in "2.0.0", for example, does not contain all the
     contents of "1.3.0".  Version "2.0.0" is not derived from "1.3.0".

  So how do we identify branching points? How do I tell that 2.0.0 was
  derived from 1.2.0? If we can't construct the order from the version
  labels, will not some of things in the versioning document break, in
  particular if I throw a bunch of _non_compatible suffixes into the
  mix as well?

  What is the reason that we talk about "editorial updates" instead of
  "bug fixes" (which seems to be the [semver] terminology)? Even worse,
  how can 'editorial updates' be _non_compatible?

  I understand that SemVer fails to work well once you have not a
  single development line (where all NBC changes go into the next
  major number increase) but you have to maintain multiple development
  lines where each development line can have NBC changes within it.
  In short, you would need SemVers for each development line. It seems
  this document acknowledges that multiple development lines exist but
  then proposes to handle this reality by collapsing entire
  development lines into _non_compatible markers for series of
  patches.

* 6. YANG Module

         rev:revision-label "1.0.0-draft-ietf-netmod-yang-semver-05";

  This is wrong, we are already at -06. ;-) I guess these revision
  labels will be commonly wrong if they need to be updated manually
  and we have no tooling in place to verify consistency.

* 7. Contributors

  - Typo 'Discussons'

  - Perhaps just list the names of the contributors comma separated
    instead of making this a longish list.

* 9.1. YANG Module Registrations

  The ietf-yang-semver module defines the prefix 'ysver' but the IANA
  section suggests to register 'yangver'. Why not simply 'semver'? The
  'rev' prefix also does not start with a 'y'. Anyway, whatever is
  picked, the prefix and the IANA registration should be consistent.

On Mon, Feb 21, 2022 at 12:20:38PM -0500, Lou Berger wrote:
> All,
> 
> This starts working group last call on
> https://datatracker.ietf.org/doc/draft-ietf-netmod-yang-semver/
> 
> The working group last call ends on March 7 th.
> Please send your comments to the working group mailing list.
> 
> Positive comments, e.g., "I've reviewed this document
> and believe it is ready for publication", are welcome!
> This is useful and important, even from authors.
> 
> Please note that once WG Last call is complete, this document will be held
> and submitted as a set with the other versioning documents (once they are
> ready) for publication request to the IESG.
> 
> Thank you,
> Lou (Co-Chair & doc Shepherd)
> 
> 
> _______________________________________________
> netmod mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/netmod

-- 
Jürgen Schönwälder              Jacobs University Bremen gGmbH
Phone: +49 421 200 3587         Campus Ring 1 | 28759 Bremen | Germany
Fax:   +49 421 200 3103         <https://www.jacobs-university.de/>

---

From: Italo Busi <[email-masked]>
Date: Tue, 8 Mar 2022 00:00:40 +0000

I have read the draft and I think it is ready to move forward

I think that also this draft is well written and it is addressing some real needs

I have only one doubt since I am not sure it has been an oversight or a conscious decision

The I-D draft-ietf-netmod-yang-module-versioning-05 says that the "the revision-label MAY be used instead of the revision date in the filename of a YANG file", however this draft does not say anything about whether this has an impact on the file name to be used in the <CODE BEGINS> tag

According to section 3.2 of RFC 8407, the " name string form that includes the revision date SHOULD be used"

Is the intention not to change this requirement also when semver revision labels are used?

Please note that with the convention defined in section 5.2, using the semver revision labels would most likely cause the line with <CODE BEGIN> tag to exceed the 72 character limit of Internet-Drafts ...

Thanks, Italo

> -----Original Message-----
> From: Lou Berger [mailto:[email-masked]]
> Sent: lunedì 21 febbraio 2022 18:21
> To: NETMOD Group <[email-masked]>
> Cc: NetMod WG Chairs <[email-masked]>
> Subject: [netmod] WG Last Call: draft-ietf-netmod-yang-semver-06
> 
> All,
> 
> Positive comments, e.g., "I've reviewed this document and believe it is ready
> for publication", are welcome!
> Please note that once WG Last call is complete, this document will be held and
> submitted as a set with the other versioning documents (once they are ready)
> for publication request to the IESG.
> 
> Thank you,

---

From: "Joe Clarke (jclarke)" <[email-masked]>
Date: Tue, 8 Mar 2022 15:51:49 +0000

Thanks for your comments and feedback, Jürgen.  Some of these changes
have been done in git whereas others have had issues opened for more
discussion and work.  Based on other responses, we will create a new
revision of the I-D after the window opens.

See below for specific replies.

>   s/extended [semver] rules/extended semantic versioning rules [semver]/

Thanks.  Fixed in git.

>   versioning rules is that they are merely guidelines but not any hard

Ah, irony.

>   should there be an acronym that makes it clear that this is not

We went with SemVer as you raise a good point about this being tied to a
name.  We raised issue #139 to track additional changes to add
clarification about how our scheme deviates.

>   not. The _COMPAT suffix seems to be something new that I did not

Issue #140 was added to clarify what is unique to YANG Semver.

>   backwards compatible bug fix that is not backwards compatible?

This is key to YANG Semver.  This will also be covered by issue #140. 
The need for this _COMPAT prefix was to handle limited branching and,
going back to the overall requirements, provide a means to indicate when
NBC changes had been made.

>   particular if I throw a bunch of _non_compatible suffixes into the

It is not intended to construct a lineage from the YANG Semver revision
labels in and of themselves.  One cannot really do that with base
SemVer, either.  For example, in base SemVer you might have
1.0.0>1.1.0>1.2.0>2.0.0, and then release a 1.3.0 off of 1.2.0.  You
cannot say that 2.0.0 encompasses the changes in 1.3.0.

The intent of the revision-label is two-fold.  One, you can use it as a
naming alias to anchor the revision-label to a specific revision.  From
there, you work backwards based on the YANG module versioning work to
determine the lineage (i.e., construct the order).

The other purpose is to provide a hint to a consumer that NBC changes
may have occurred in the module and require further analysis (some of
which can be done via the forthcoming tooling draft).

>   how can 'editorial updates' be _non_compatible?

Raised #141 to clarify this.  We feel "editorial updates" is the right
terminology given that bug fixes in YANG would tend to be at the MINOR
or MAJOR levels.

>   development lines into _non_compatible markers for series of

Yes.  To support the limited branching, this was what was worked out. 
There is text to discourage needing to use _non_compatible, but we know
in reality those NBC changes will occur.  The stickiness will at least
provide that operator hint to do more analysis to determine the changes
and if they are relevant.

>   and we have no tooling in place to verify consistency.

This was on purpose.  As with revision date, we are not bumping the YANG
Semver label if the module itself has not changed.  That said, we raised
#142 to add more clarification here.

>     instead of making this a longish list.

Fixed and fixed.

>   picked, the prefix and the IANA registration should be consistent.

Ugh.  This was one me.  We had some last-minute discussion around
prefix, and I missed changing the IANA section.  It is done now in git.

As for the choice, we are sticking with ysver to avoid any confusion
that this is the base semver.

Joe

---

From: Jürgen Schönwälder <[email-masked]>
Date: Wed, 9 Mar 2022 10:57:46 +0100

> revision of the I-D after the window opens.

[...]

> which can be done via the forthcoming tooling draft).

If some module depends on some feature defined in x.y.z, then you need
to be able to tell whether version X.Y.Z is a descendant of x.y.z. If
the information about descendants can't be recovered from the revision
label markups, then which value do the revision labels have? Is the
answer that the truth comes out of some complicated tooling?

/js

---

From: Lou Berger <[email-masked]>
Date: Sun, 13 Mar 2022 14:13:29 -0400

Hi,

I'd like to formally close this (and the other) LC -- by saying the same 
thing for both.

There were some good comments made during the LC that should be 
addressed before publication.  Authors, as I'm sure you are doing so 
already, please work through all public and private comments received; 
preferably with on-list discussion.  Once you publish a version that 
addresses all received comments as well as the on-list discussions, 
please summarize the changes to the WG.  Also please state that the 
document is ready for publication. The need for a second last call will 
be based on the specific changes.

Thank you!

Lou (Co-Chair & doc Shepherd)
On 2/21/2022 12:20 PM, Lou Berger wrote:
> Please note that once WG Last call is complete, this document will be
> held and submitted as a set with the other versioning documents (once
> they are ready) for publication request to the IESG.
>
> Thank you,