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
_______________________________________________
netmod mailing list
[email protected]
https://www.ietf.org/mailman/listinfo/netmod
