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

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

Hi all,

A poll at IETF118 was roughly split on recommended-min.

We discussed this in the weekly YANG versioning call and feel we should:
1) keep recommended-min-date in the Module Versioning draft
2) add recommended-min-label (or similar name) in the YANG Semver draft.
They would be mutually exclusive inside a single import statement.

As defined in Module Versioning, the recommended-min is informational only. Compilers/tools are not required to use the recommended-min as a constraint.

We don't believe this causes any new incompatibility issues wrt RFC7950.

RFC7950 section 5.1.1 says the following:

   If a module is not imported with a specific revision, it is undefined which revision is used.

So clients, servers and tools can pick whatever revision they want. Two different tools may pick different revisions.

In section 5.6.5 RFC7950 says the following:

   If a server lists a module C in the "/modules-state/module" list from
   "ietf-yang-library" and there are other modules Ms listed that import
   C without specifying the revision date of module C, the server MUST
   use the definitions from the most recent revision of C listed for
   modules Ms.

Recommended-min does not affect conformance and is not mandatory. So a server, toolchain, etc can continue to select the "most recent revision" even if that revision is older than the recommended-min.

Jason


> -----Original Message-----
> From: Jürgen Schönwälder <[e-mail]>
> Sent: Thursday, October 26, 2023 4:23 AM
> To: Andy Bierman <[e-mail]>
> Cc: Joe Clarke (jclarke) <jclarke=[e-mail]>; Jason Sterne
> (Nokia) <[e-mail]>; [e-mail]
> Subject: Re: [netmod] Updated Content of Module Versioning - T8
> (recommended-min for imports)
> 
> 
> CAUTION: This is an external email. Please be very careful when clicking links or
> opening attachments. See the URL nok.it/ext for additional information.
> 
> 
> 
> Well, yes, import-by-revision is broken. However, changing the way how
> imports work changes the YANG language. So it is important to know
> which version of the YANG language tools implement. For this we have
> language version numbers.
> 
> /js
> 
> On Wed, Oct 25, 2023 at 02:44:26PM -0700, Andy Bierman wrote:
> > On Wed, Oct 25, 2023 at 12:03 PM Joe Clarke (jclarke) <jclarke=
> > [e-mail]> wrote:
> >
> > > This is the reason that, for me, I’d want the extension to be outside the
> > > description in something that is machine-readable.  Tools that do
> > > understand this extension could make a better decision about which module
> > > revision to use.
> > >
> > >
> > >
> >
> > +1
> >
> > The YANG author should know if their module depends on imported definitions
> > from a specific revision.
> > IMO the min-revision is needed in this case, and SHOULD be present.
> > There is a big difference between "module will compile" and "module will
> > work as intended".
> >
> > Tools that do not understand the extension will resolve the import as they
> > > normally would, which may lead to a failure at compile time (e.g., for a
> > > missing node).
> > >
> >
> > This extension MUST be ignored if the 'revision-date' statement is present
> > in the import-stmt.
> >
> >
> > >
> > > Joe
> > >
> >
> > Andy
> >
> >
> > >
> > >
> > > *From: *netmod <[e-mail]> on behalf of Jürgen
> Schönwälder
> > > <[e-mail]>
> > > *Date: *Wednesday, October 25, 2023 at 14:45
> > > *To: *Jason Sterne (Nokia) <[e-mail]>
> > > *Cc: *[e-mail] <[e-mail]>
> > > *Subject: *Re: [netmod] Updated Content of Module Versioning - T8
> > > (recommended-min for imports)
> > >
> > > I am strongly against this. The import statement is used by tools.
> > > Adding a recommendation for humans that existing and conforming tools
> > > will not understand just causes confusion.
> > >
> > > /js
> > >
> > > On Wed, Oct 25, 2023 at 06:41:19PM +0000, Jason Sterne (Nokia) wrote:
> > > > 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)
> > > >
> > >
> > > > _______________________________________________
> > > > netmod mailing list
> > > > [e-mail]
> > > > https://www.ietf.org/mailman/listinfo/netmod
> > >
> > >
> > > --
> > > Jürgen Schönwälder              Constructor University Bremen gGmbH
> > > Phone: [phone]         Campus Ring 1 | 28759 Bremen | Germany
> > > Fax:   [phone]         <https://constructor.university/>
> > >
> > > _______________________________________________
> > > netmod mailing list
> > > [e-mail]
> > > https://www.ietf.org/mailman/listinfo/netmod
> > > _______________________________________________
> > > netmod mailing list
> > > [e-mail]
> > > https://www.ietf.org/mailman/listinfo/netmod
> > >
> 
> --
> Jürgen Schönwälder              Constructor University Bremen gGmbH
> Phone: [phone]         Campus Ring 1 | 28759 Bremen | Germany
> Fax:   [phone]         <https://constructor.university/>