Thanks for the feedback, Jürgen. Being the editor on YANG Semver, let me
respond to some of you points there.
* YANG Semantic Versioning
<draft-ietf-netmod-yang-semver-17>
- The claims made in the first paragraph of the abstract about the
versioning document do not seem to be aligned with that document
when it says "a more flexible approach to importing modules by
revision". My understanding is that the versioning document says
that collections of suitable modules are maintained outside of
YANG modules and there is a recommended-min-date, which is a piece
of documentation but not changing YANG's current import logic.
[JMC] The YANG Semver abstract _itself_ defines the rules for import by YANG
Semantic Version. Those rules are defined in the YANG Semver draft Section 5.
That said, the module versioning draft _does_ define import guidelines based on
recommended-min-date (see section 4.1 of that document).
- I am still confused by the complexity introduced here. Why do we
need both X.Y.Z and X.Y.Z_compatible? What is the difference, when
do I use which?
[JMC] In the overwhelming majority of cases you would use X.Y.Z. In fact, I
believe in all IETF cases, only X.Y.Z would be used. It’s best to describe the
“why” of the _compatible modifier with specific numbers. Let’s say you have a
module versioned 1.2.3 and you want to add a feature (i.e., make an otherwise
MINOR change). However, module 1.3.0 has already been published. In this
case, you would publish a 1.2.4_compatible. This might be a very real case
with vendor modules.
- X.Y.Z_non_compatible sounds like a somewhat questionable idea. To
me, this says "we claim this is X.Y.Z but we know it should be
something different". The _non_compatible modifier essentially
overwrites the meaning of [SemVer], rendering X.Y.Z at best into a
branch identifier. Perhaps this is what the industry really wants,
three digit branch identifiers but not really [SemVer]?
[JMC] The intent of this is to signal to a consumer that, say,
1.2.5_non_compatible is based on the 1.2.4 version of the module but changes
have been made that would render it not backwards compatible with 1.2.4 and one
should be aware of that. We think this will be lightly used, but it has been
seen in the wild, especially with vendor modules.
- The example in Section 4.4.1 is interesting and welcome but
unfortunately there is no recommendation how situations should be
handled if branches split off (and perhaps even merge later).
[JMC] I think we can add some text here to anchor to the fact that within a
MAJOR branch (without the _non_compatible modifier) backwards compatibility can
be preserved when branches diverge and are later merged. I think this will be
left to developers how exactly this is handled. In one case you might choose
to incorporate all changes so that HEAD reflects an aggregate of changes (a
true merge). In other cases it might make sense to leave the branches
divergent and have a new MAJOR branch.
- If I need to make a BC update to X.Y.Z_compatible but
X.Y.Z+1_non_compatible has already been taken, what do I do?
[JMC] The _non_compatible modifier takes precedence. So you could do
X.Y.Z+2_non_compatible. This is one reason why we say that this scheme
supports limited branching.
- I am not sure how the recommended-min-version helps if there are
branches since there is not guarantee that 2.0.0 > v1.1.1 implies
that 2.0.0 includes everything that was in 1.1.1. If
recommended-min-version is 1.1.1, then an import of 2.0.0 may
still fail, no?
[JMC] Yes, it could. But it is not true that 2.0.0 necessarily implies that it
includes everything in 1.1.1. The MAJOR version change means that there are
non-backwards-compatible changes and you will need to look at this 2.0.0 to see
how it affects your tooling.
- An existing compliant YANG compiler will not "locate a module with
a version that is viable according to the conditions above". An
existing compiler YANG compiler will ignore the extension
statements recommended-min-version (and recommended-min-date). I
think you need to acknowledge this and word things differently.
Sure, a compiler that supporting recommended-min-version may
generate suitable warnings, but existing compliant YANG 1.1 and
YANG 1 compilers can't be expected to do something fancy due to
the presence of an (from the compiler's perspective) unknown
extension.
[JMC] Thanks. Where in the doc are you looking? I don’t find the exact text
you quote. Section 5.2 comes close, but it’s not exact. But a compiler that
is compliant with (or aware of) YANG Semver, would be able to emit a proper
warning if it cannot locate a module that meets the import rules. I agree that
a standard YANG 1[.1] compiler would not be aware of this extension and would
therefore load an available module by name and might ultimately end up with
compiler errors.
- Is 'ys' a good module prefix? Yes, it is YANG's variation of
SemVer, but perhaps ys is a bit too cryptic? What about 'semver'
or if we optimistically assume we do not need another versioning
scheme even just 'ver' (the reverse of 'rev').
[JMC] 😊 We tried a few prefixes over the years. We settled on ys because it
was short. I’m not married to it. “semver” also sounds okay to me.
rev:non-backwards-compatible rev:non-backwards-compatible
rev:recommended-min-date rev:recommended-min-date
ys:version 3.1.0 semver:version 3.1.0
ys:recommended-min-version semver:recommended-min-version
- Description of the version extension:
"The version extension can be used to provide an additional
identifier associated with a module or submodule
revision.
I am not sure about "additional identifier". Its just a version
number. So what about:
"The version extension can be used to assign a version number
to a module or submodule revision.
[JMC] Works for me.
- I like the choice ietf-yang-library-semver, see my suggestion to
use ietf-yang-library-status for the other yang library extension
above. I also like the yl-semver prefix here, I do not like so
much the ys-conf prefix used in the other draft. Some consistency
may be nice.
[JMC] Agreed. And “ys” comes back here, so maybe “semver” is better.
- Editorial
s/do not not require/do not require/
[JMC] Thanks.
Joe
_______________________________________________
netmod mailing list -- [email protected]
To unsubscribe send an email to [email protected]
