On Tue, Oct 08, 2024 at 06:08:11PM -0400, Lou Berger wrote:
> All,
>
> This starts working group last call on our core versioning documents:
[...]
> The working group last call ends on Friday October 25th - slightly extended
> since LC for 3 documents.
>
> Please send your comments to the working group mailing list.
I have finished reading the documents and here are my comments. I read
them in a somewhat unusual order...
* YANG module file name conventions
<draft-ietf-netmod-yang-module-filename-00>
- I suggest to remove text making claims that something is "easy"
etc. unless there is a real definition for "easy". Having a
semantic version number in a file name does nothing by itself, it
just adds more clutter to the locations where modules are stored.
The semantic version number only is useful if people implement a
revised version of YANG that supports semantic versioning.
- Why "instead of the revision date"? I think the revision date
should always be there - at least as long a we talk about YANG
1.1. Existing deployed tools do use those names. You may _in
addition_ have other names.
- I am not sure the statement "YANG semantic version is recommended
in order to simplify for module consumers" is true if at the same
time you recommend to break RFC 7950 compliant implementations by
not requiring the YANG 1.1 module file names anymore.
- Typically, only one file name SHOULD exist for the same module (or
submodule) revision. [...] Two file names [...] MAY exist for the
same module (or submodule) revision.
I disagree with this statement. You can add additional names,
there is no point in changing and breaking RFC 7950 rules.
Implementations can arrange files in different directories if that
is a concern. Storage is cheap, breaking existing code is not.
- I do not really understand why this is a separate document and not
a part of draft-ietf-netmod-yang-semver (after rewriting it to
stop break YANG 1.1).
* Updated YANG Module Revision Handling
<draft-ietf-netmod-yang-module-versioning-12>
- The flagging of NBC changes still is at the module level and not
at the level of definitions. Why not? (Other real world languages
do have annotations such @since etc.) It always matters _which_
definition has actually an NBC change, not whether something in a
module has an NBC change. Why do we not mark the definitions that
have non-backwards-compatible changes and then the rest follows
from this? Instead, we give readers and compilers the puzzle to
find out what has actually changed. This feels backwards. If there
is an NBC change in YANG module, you want to quickly find out
whether your module is affected or not. Why do we make this
complicated? If we were to make an NBC change to
yang:date-and-time, why would I not mark this typedef and instead
mark ietf-yang as NBC? If an importing module does not use
yang:date-and-time, it is not affected. Why do we make it hard to
determine whether an importing module is affected?
- If a module import a definition from some other module that has an
NBC change of say a typedef used by the importing module, does
this module have to declare an NBC change as well? And if so, what
if the presence of an NBC change depends on how the import is
resolved, i.e., it may not be in the hands of the module author?
- I wonder whether extension statements were ever allowed "to change
the semantic of a module". It should always be possible to ignore
extensions. See RFC 7950: "An extension attaches non-YANG
semantics to statements." And then later:
Care must be taken when defining extensions so that modules that use
the extensions are meaningful also for applications that do not
support the extensions.
Hence, I do not understand bullet #3 in section 3.1.1.
- Section 6.2 is a bit confusing because it talks about clients but
the guidance seems to apply to developers of clients, or do you
really expect that client code itself can "plan to make changes to
match published status changes". To me, this section seems to
provide guidance for client developers not clients.
- The definition of revision date could be as well:
typedef revision-date {
type yang:date-no-zone;
description
"A date associated with a YANG revision.
Matches dates formatted as YYYY-MM-DD.";
reference
"RFC XXXX: Common YANG Data Types";
}
But perhaps the idea is to avoid dependencies. I do not care much
but I thought I at least mention that we now (or soon) have a
suitable type in place.
- Is ietf-yang-status-conformance is a good module name given that
this module is essentially an extension of ietf-yang-library? Did
you consider to name the module say ietf-yang-library-status and
to also use a prefix like yanglib-status (or yl-status - see
below)?
- Appendix A: Changing a type is NBC only if the new type is having
different syntax or semantics. See section 11 of RFC 7950, there
is an explicit bullet for this.
* 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.
- 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?
- 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]?
- 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).
- 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?
- 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?
- 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.
- 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').
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.
- 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.
- Editorial
s/do not not require/do not require/
/js
--
Jürgen Schönwälder Constructor University Bremen gGmbH
Phone: +49 421 200 3587 Campus Ring 1 | 28759 Bremen | Germany
_______________________________________________
netmod mailing list -- [email protected]
To unsubscribe send an email to [email protected]
