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

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

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

[JMC] In terms of the drafts, I believe the authors have settled on a revision update comes with a revision-label update.  Text may need some more clarity here.


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

[JMC] SemVer is generally understood in the industry, and we anchored to something as a starting point for YANG Semver that made sense.  Their approach to their own spec is outside our control.


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

[JMC] Yes.  I have made some changes in GH to clarify that.


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

[JMC] There is text explicitly about the camel case difference, and this whole doc is based on YANG Semver with a reference to where it started in SemVer 2.0.0.  I’d like to hear from others as to whether this is too ambiguous.


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

[JMC] YANG Semver is based on the rules of SemVer and is compatible with SemVer.  The opposite is not true, so they are not the same.  For example, 2.0.0 is a valid SemVer and a valid YANG Semver.  However, 2.0.1_COMPATIBLE, while a valid YANG Semver is not a valid SemVer.


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

[JMC] Right now we entertain multiple revision-label models with only one way to write a YANG Semver.  That said, it can be debated if we really need different revision-label models.


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

[JMC] Early on we discussed with the WG our requirements and limited branching was one of them.  This is why strict SemVer was insufficient.  We needed something that supported this limited branching, and we arrived at what YANG Semver is today.



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

[JMC] We have per-module notation, and we discussed general per-node tags (though they were moved to schema comparison as you point out).  Part of this oscillation is due to changes in feedback over time, and I am unclear the best path forward on this issue.  Myself, personally, I would be okay bringing back the per-node tags as I agree with your point above.


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

[JMC] This is another case where feedback swayed us in this direction.  If the WG wants tighter rules, I think we can have them.


Joe