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

[Jürgen Schönwälder <[e-mail]>]

On Mon, May 08, 2023 at 10:49:15PM +0000, Kent Watsen wrote:
> Dear NETMOD WG,
> 
> This message begins a joint two-week WGLC for draft-ietf-netmod-yang-semver-11 and draft-ietf-netmod-yang-module-versioning-09
>  ending on Monday, May 22nd.  Neither draft has IPR declared.  Here are the direct links to the HTML version for these drafts:
> 
>    - https://datatracker.ietf.org/doc/html/draft-ietf-netmod-yang-semver-11
>    - https://datatracker.ietf.org/doc/html/draft-ietf-netmod-yang-module-versioning-09
> 
> Positive comments, e.g., "I've reviewed this document and believe it is ready for publication", are welcome!  This is useful and important, even from authors.  Objections, concerns, and suggestions are also welcomed at this time.
>

Comments on draft-ietf-netmod-yang-module-versioning-09.txt:

- My opinion about changing YANG 1.1 rules without bumping the YANG
  version number is likely clear to everyone so I won't repeat it
  here.

- YANG 1.1 does not have an import by minimum revision, which clearly
  is a bug in YANG 1.1. This document now introduces a "soft" version
  of an import by minimum revision but the sad story is that this
  remains again incomplete from the perspective of the new versioning
  scheme. If we allow NBC changes, then it is necessary to express
  revision ranges since the definitions a module depends on can appear
  at revision a.b.c and disappear at revision e.f.g (and perhaps even
  reappear in revision h.i.j). Hence, we again have an incomplete
  solution.

- Do we really need to support multiple 'revision label schemes'? If
  so, we have to work out more details. What kind of order properties
  do we expect from revision label schemes? And what is the
  relationship between a versioning scheme and a revision label
  scheme? Can you mix and match revision label schemes? What happens
  to revision labels encoded in file names, can there be collisions
  between different revision label schemes?  Perhaps we are
  over-engineering here and one 'revision label scheme' that people
  can agree on is sufficient and simplifies things?

- Instead of multiple 'revision label schemes' for the same
  'versioning scheme', I think it makes sense to consider support of
  multiple 'versioning schemes' (not just different label schemes, for
  me different labels expressing the same information are pointless).
  Can we design a solution where the original 'linear order always
  backwards compatible versioning scheme' of RFC 7950 becomes just one
  of several versioning schemes we have? This would essentially mean
  that the update rules become a property of a versioning scheme
  instead of being a hardwired property of the language. Perhaps there
  could even be space for a third 'null versioning scheme' that defers
  all versioning to a package solution where the package definitions
  define which modules work together, i.e., we focus on versioning
  packages instead of individual modules.

- I suggested (long time ago) to maintain versioning constraints
  outside of the modules. This allows to update import constraints
  without having to edit and republish modules. (And versioning
  packages of modules may be more practical than versioning each and
  every module once a data model reach a certain size.) I guess I
  rather have semantic version numbers on packages of modules than on
  each and every module itself. The beginning of section 4 seems to be
  spot on but then we fall back doing the wrong thing.

- The document seems to be silent about how different versions can be
  supported. In the old world, having foo and foo2 coexist was easy,
  clients could gradually be updated to use foo2 instead of foo. In
  the new versioning world, this becomes more complex and may require
  protocol work. It remains unclear to me where and when this protocol
  work will be done.

- More specific comments follow. Concerning this:

   *  Any change made to the "revision-date" or "recommended-min"
      substatements of an "import" statement, including adding new
      "revision-date" or "recommended-min" substatements, changing the
      argument of any "revision-date" or "recommended-min"
      substatetements, or removing any "revision-date" or "recommended-
      min" substatements, is classified as backwards-compatible.

  Why is that? If I add/change recommended-min to a module revision
  that has NBC changes affecting the current module, then how can this
  be considered backwards compatible?

- Why do we tag modules with rev:non-backwards-compatible? Why do we
  not tag the concrete definitions that have non-backwards-compatible
  changes and then the rev:non-backwards-compatible is implied?

- What are the order rules for revision labels? A statement like
  rev:recommended-min only makes sense if there is a certain order
  defined.

- Concerning this:

    A specific revision label identifies a specific revision of the
    module.  If two YANG modules contain the same module name and the
    same revision label (and hence also the same revision-date) in their
    latest revision statement, then the file contents of the two modules,
    including the revision history, MUST be identical.

  It is unclear what "identical" means here. If two people extract a
  module from an RFC, they may not end up with identical byte
  sequences. So does white space matter when we talk about MUST be
  identical? What about comments? The problem is that the IETF still
  publishes YANG modules in RFCs instead of files.

- I do not know why we allow for multiple revision label schemes but
  since we do, what happens if different revision label schemes clash
  in the module file names? To properly support multiple revision
  label schemes properly, one would have to scope the revision labels
  in the file names, no? Do we really need to support multiple
  revision label schemes?

- I do not understand what section 6 is trying to achieve. There is a
  SHOULD that points to "e.g., [I-D.ietf-netmod-yang-packages]". How
  is someone going to implement this SHOULD? And does RFC 9195 not
  make use of YANG library? Is that not sufficient? Do the YANG
  library extensions apply to RFC 9195 or are they recommended to be
  used with RFC 9195?

- As mentioned earlier, my view is that the update rules are a part of
  a versioning scheme. Hence, if there are two or more versioning
  schemes, we should spell out the different updated rules for each
  versioning scheme.

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?

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

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

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

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

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

- I prefer to have non-backwards compatible changes marked and
  explained in the modules instead of relying on some schema
  comparison algorithm.

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

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

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

- Reference [openconfigsemver] resolves to an empty page (tried two
  browsers). Do you mean <https://www.openconfig.net/docs/guides/semver/>?

/js

-- 
Jürgen Schönwälder              Constructor University Bremen gGmbH
Phone: [phone]         Campus Ring 1 | 28759 Bremen | Germany
Fax:   [phone]         <https://constructor.university/>