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

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

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.

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.


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


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


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


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


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


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


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


- 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