[netmod] Updated Content of Module Versioning - T8 (recommended-min for imports)

["Jason Sterne (Nokia)" <[e-mail]>]

Hi all,

Starting a dedicated thread for T8 recommended-min for imports

These are my own personal opinions (not those of the authors/contributors).

It has been discussed before that import by a specific revision is somewhat broken (not recommended). It is mentioned in section 2.5 of the versioning requirements draft: https://www.ietf.org/archive/id/draft-ietf-netmod-yang-versioning-reqs-08.html#name-no-good-way-to-specify-whic

Based on previous WG LC discussions, we already changed from a revision-or-derived extension (that did affect conformance & what a tool could/should use), to a weaker recommended-min in order to avoid further changes to the YANG language & conformance rules.  The recommended-min is pretty much purely a documentation tag that helps users of the modules understand what versions of imports might be best to use (e.g. when supporting multiple modules in a server, or constructing a "package" of modules that work together).

We could instead just say to put this information into a description field in the module. But it is helpful if the field is broken out (i.e. structured data) and more easily machine readable.

So I'd like to see this stay as part of Module Versioning but be renamed to recommended-min-date.  Then in YANG Semver we should add recommended-min-semver-label.

Jason


From: netmod <[e-mail]> On Behalf Of Jason Sterne (Nokia)
Sent: Tuesday, October 24, 2023 9:58 AM
To: [e-mail]
Subject: [netmod] Updated Content of Module Versioning

Hello NETMOD WG,

The YANG versioning authors and weekly call group members have been discussing the next steps for the versioning drafts.

We'd propose that the first step is to converge on what aspects of the current Module Versioning draft should be retained, and which parts should be removed. We can then work towards a final call on an updated version with this revised scope.

Below is a summary of the main topics in the Module Versioning draft. We've divided the items T1-T10 into 2 groups:
A) Baseline content of Module Versioning
B) Items which need more WG discussion

In addition to whatever discussions happen on this email list, we have also created a hedgedoc where you can register your preference for items T7-T10. It would be much appreciated if you can put your opinion in the hedgedoc here:
https://notes.ietf.org/CdKrT5kVSF6qbnRSY4KeSA?both


GROUP A (Baseline content of Module Vesioning)
-----------------------------------------------------------------
Based on resolution of WG LC comments and subsequent discussions, and some feedback to reduce complexity and content in the Module Versioning draft, here is a summary of items that will and won't be part of the next update of the Module Versioning draft (also referred to as "this draft" below).

T1. The "ver:non-backwards-compatible" annotation (Sec 3.2):
Retained. This top level (module level) extension (which can be ignored by tools that don't understand it) is critical to include so that module readers and tools can know when NBC changes have occurred.

T2. Updated rules of what is NBC: (Sect 3.1.1, 3.1.2)
Retained. These are updates/clarifications (i.e., changes) to the RFC 7950 rules that are appropriate and helpful:
(i) "status obsolete"
  - This draft changes RFC 7950 so that marking a data node as obsolete is an NBC change because it can break clients.
(ii) "extensions"
  - This draft changes the RFC 7950 rules to allow extensions to define the backwards compatibility considerations for the extension itself.  The existing RFC 7950 rules only allow extensions to be added, not changed or removed.
(iii) "import by revision-date"
  - This draft changes the RFC 7950 rules to allow the revision date of an import-statement to be changed/added/removed.  The imported module must be versioned separately (i.e., by a YANG package/library defining the schema).
(iv)  "whitespace":
  - This draft clarifies the existing RFC 7950 behaviour that changing insignificant whitespace is classified as a backwards compatible change

T3. revision-label-scheme extension (Sec 3.4.2)
Removed. Based on WG LC discussions we will go back to a single versioning scheme for YANG modules, and hence the revision-label-scheme extension will be removed from this draft.

T4. revision-label extension (Sec 3.4)
Removed. Related to T3 above, given that a single versioning scheme is sufficient, the revision-label extension will be moved to the YANG Semver draft, and removed from Module Versioning.

T5. Resolving ambiguous imports in YANG library (Sec 5.1)
Removed. This will be removed from Module Versioning (could be considered in YANG Next, although that is many years away).  Note, RFC 7950, section 5.6.5, paragraph 5 does consistently define how to build the schema.  The change in the draft was to always prioritise an implemented module over the most recent implemented *or* import-only revision. But this will be removed.

T6. Advertisement for how deprecated & obsolete nodes are handled (Sec 5.2.2)
Retained. This information is important for clients to be able to accurately construct the schema and hence it is retained in Module Versioning.

GROUP B (Needs WG discussion)
-------------------------------------------
For these items we don't have consensus within the WG - they need more discussion and input.

It is recommended to go back and look at the NETMOD emails on these topics (from the WG LC discussions).

Please add your name beside your preferred option in the poll: https://notes.ietf.org/CdKrT5kVSF6qbnRSY4KeSA?both

T7. filename changes (Sec 3.4.1)
The authors/contributors are leaning towards suggesting that this moved change be moved to YANG Next consideration.  However, there isn't complete consensus, with concerns that the vendors will each define their own incompatible file naming schemes for YANG modules that use version numbers.  If we retain this work then this would likely move to the YANG Semver draft.
[See hedgedoc poll T7]

T8. recommended-min for imports (Sec 4)
The WG seems to be somewhat split on how urgent this is, and there isn't consensus amongst authors/contributors for retaining this work or deferring it. One option is to keep it, but renamed as recommended-min-date.
[See hedgedoc poll T8]

T9. Versioning of YANG instance data (Sec 6)
There wasn't any consensus among the authors/contributors as to whether this should be retained or deferred to a new version of the YANG instance data document.
[See hedgedoc poll T9]

T10. Do *all* whitespace changes (including whitespace between statements) require a new revision to be published? Sec 3.1, last paragraph.
The authors/contributors are somewhat split on whether to retain this.  The advantage of keeping this is that it makes it very easy to check (i.e., via a simple text diff tool) whether two modules pertaining to be the same version are in fact the same.  It should also mean that it is easy to generate a hash-based fingerprint of a module revision.  The alternative gives more flexibility to users to reformat modules (e.g., for different line-lengths), but complicates the check to ensure that a YANG module revision hasn't been changed or makes it slightly more expensive to generate a hash since the module formatting would need to be normalized first.
[See hedgedoc poll T10]

Jason (he/him)