Re: [netmod] Joint WGLC on "semver" and "module-versioning" drafts

[Jürgen Schönwälder <[e-mail]>]

On Mon, Jun 12, 2023 at 03:45:41PM +0000, Joe Clarke (jclarke) wrote:
> Thanks for the detailed review, Jürgen.  See below on responses concerning YANG Semver.
> 
> As for the discussion on YANG artifact “equivalence” I recall we discussed this a bit in meetings and amongst the authors.  I don’t remember all the points but it boiled down to when the revision changes, the revision-label changes.  So if, for example, a module is extracted or produced with extra newlines that module is still equivalent to another module with the same revision/revision-label.  Text in Section 1 states that when a new revision of a module… changes; however, the text in Section 3 might be adding ambiguity here, and we could make that clearer with respect to modules.  The same attention can be applied to the versioning draft.
>

You need to settle what you want. The mailing list discussion is not
consistent with what you wrote and what the document says.

> Comments on draft-ietf-netmod-yang-semver-11:
> 
> - Is the end of the introduction telling me that the SemVer 2.0.0
>   rules change in non-backwards compatible ways without the version
>   number changing?
> 
> [JMC] Yes.  We raised this a few meetings back when we learned that the SemVer 2.0.0 spec (using git to look at history) had changed in NBC ways.  We therefore anchored to a revision in time that corresponded to the rules at the time on their web site.
>

What good is SemVer is the SemVer people do not follow it?
 
> - The term 'YANG artifact' is imported from the packages draft, which
>   has expired. I pulled out the expired version 03, I could not find a
>   definition in there either.
> 
> [JMC] YANG artifact is “defined” in the YANG Semver draft, but uses packages as a type of artifact to go along with modules and submodules.  I admit that the definition here is weak (definition by example only), and I can improve that.
>

You need to import it from where it is defined.

> - SemVer and YANG Semver look very similar and perhaps too similar or
>   not similar enough. I do not have a good proposal, just noting a
>   possible writing issue that we will have with Semver and SemVer.
>   Why does 'Semver' and  'YANG SemVer' not do the job?
> 
> [JMC] There are clear differences in YANG Semver when compared to the SemVer 2.0.0 spec that the document references.  The difference in case is because SemVer 2.0.0 refers to itself that way, and using “YANG Semver” (without the camel case) seemed like enough of a textual differentiator when reading the document.

For me, this is too obscure. I fear people will mess this detail up.
 
> - Section 3.1 starts with a statement that SemVer and YANG Semver are
>   'completely compatible'. While I started wondering what the
>   difference between 'compatible' and 'completely compatible' might
>   be, I was more confused to read this statement upfront, i.e., before
>   I even get told what YANG Semver is. Perhaps first define what YANG
>   Semver is and then discuss its relationship to SemVer?
> 
> [JMC] Fair enough.  The adverb there is also unneeded.

But did you not just explain that they are not the same?
 
> - As already mentioned above, my take is that a 'versioning scheme'
>   should use exactly one 'revision label scheme' and it should have
>   specific 'module update rules' supporting the "versioning scheme".
>   This does not seem to be the model that the draft authors use and I
>   am a bit confused what their model is. In other words, I see
> 
>   YANG Semantic Versioning consists of
>        -> YANG Semantic Version Module Update Rules
>        -> YANG Semantic Version Revision Label Scheme
>        -> YANG Semantic Version Import Rules
>        -> NC/RC/... version selection protocol mechanisms needed
> 
>   YANG Traditional Versioning consists of
>        -> YANG's Traditional Module Update Rules
>        -> YANG's Traditional Module Label Scheme (revision dates)
>        -> YANG's Traditional Module Import Rules (lacking import by min revision)
>        -> no specific protocol mechanisms needed to support transitions
> 
>   It seems we have not factored out an interface for plugging
>   additional versioning models into YANG and the protocols providing
>   access to YANG-defined data.
> 
> [JMC] The original intent was that different YANG artifact producers might want different schemes.  Admittedly, examples other than YANG Semver were mainly vendor-centric (e.g., codenames or software revisions).  I think it’s reasonable to have the conversation as to whether or not this flexibility is really needed.
>

Do you want multiple versioning models or multiple writing styles for
labels of the same versioning model? This is a fundamental difference.

> - Why do we need the _COMPATIBLE extension of SemVer? It would be nice
>   to explain this more clearly, the best bit of explanation I found
>   seems to be in situations where the next major version number has
>   already been taken. But then SemVer does not support branching in
>   general, why do we need a bit of this via the _COMPATIBLE extension?
>   Did anyone suggest this addition to the SemVer people and what was
>   their reaction, something they would consider adding to SemVer or
>   more reservation about this being a proper solution?
> 
> [JMC] We need _COMPATIBLE for the reason you point out: e.g., an author has produced a module with 1.0.0 and 2.0.0 revision-labels, and a consumer needs a new feature ported to the 1.X branch.  In this case the author would release 1.0.1_COMPATIBLE.
>
>
> [JMC] To my knowledge we did not raise this to the SemVer people explicitly, though someone from that camp did review this draft.  He admitted to being confused in an earlier version of the text, specifically with _COMPATIBLE.  We added more text to clarify its use, but perhaps it’s not clear enough?
> 

Yes, but that is not what SemVer supports. So its either SemVer or
something else. And you can't support full development on branches
either. It looks like a half baked addon. Those who need to support
branches will likely not be happy with it, the others do not need it.
I like to see a strong reason why departure from SemVer is desirable
and sufficient for the industry needs.


> - I prefer to have non-backwards compatible changes marked and
>   explained in the modules instead of relying on some schema
>   comparison algorithm.
> 
> [JMC] IMHO, the algorithm is useful in addition to any per-module notation as the tooling can provide a clear, consolidated report of the overall compatibility.
>

Sure, years ago I implemented smidiff, but then assuming that every
reader has the proper tools is likely wrong. And while tools can spot
differences, they lack the ability to give explanations or advice how
to adapt to changes. NBC changes deserve to be documented where they
take place. Tooling can spot missing documentation.
 
> - Does it make sense to have an example Package Using YANG Semver in
>   this document given that YANG packages is not moving along with this
>   document? Should the examples move to the appendix to make it
>   clearer that they are just examples and non-normative?
> 
> [JMC] Fair point.  I agree.  I think it makes sense to move this.
> 
> 
> - The import discussion ignores what happens if future versions are
>   not providing the symbols anymore expected by an import. See my
>   previous comment that compatibility may require ranges of version
>   numbers, revision-or-derived is a half-baked solution.
> 
> [JMC] We initially had a very complex set of import rules (inclusive, exclusive, ranges, etc.), and it was deemed overkill.  Based on other comments we received, we softened the import rules to be more advisory.
>

To me, advisory import rules are non-sense. A parser is not evaluating
advise, it needs clear rules and different parsers better behave the
same. Again, since I can remove symbols, there needs to be a way to
express that a certain import only works up to a certain revision.
Ignoring this means the solution is incomplete.

> 
> - If we really want to support multiple revision label schemes, then
>   creating a typedef 'version' which is YANG Semver specific may be a
>   bit to simplistic. We would likely need a type that is extensible
>   and qualified by a yang-semver identity, no? I am not asking for
>   this, I rather question whether we really need to have open ended
>   label schemes.
> 
> [JMC] Worth discussing again.
> 
> 
> - Reference [openconfigsemver] resolves to an empty page (tried two
>   browsers). Do you mean <https://www.openconfig.net/docs/guides/semver/>?
> 
> [JMC]  Thanks.  Will fix.
> 
> Joe

/js

-- 
Jürgen Schönwälder              Constructor University Bremen gGmbH
Phone: [phone]         Campus Ring 1 | 28759 Bremen | Germany
Fax:   [phone]         <https://constructor.university/>