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

["Joe Clarke (jclarke)" <[e-mail]>]

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.

On 3/6/22 06:10, Jürgen Schönwälder wrote:
> 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.  Fixed in git.

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

Ah, irony.

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

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.

>
> * 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].

Issue #140 was added to clarify what is unique to YANG 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?

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.

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

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

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

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.

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

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.

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

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.

>
> * 7. Contributors
>
>   - Typo 'Discussons'
>
>   - Perhaps just list the names of the contributors comma separated
>     instead of making this a longish list.

Fixed and fixed.

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

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