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

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

If compilers can pick different revisions and this results in
different interpretations of YANG definitions then thigns are
broken.

/js

On Wed, Nov 15, 2023 at 10:30:49PM +0000, Jason Sterne (Nokia) wrote:
> 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://eur01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fwww.ietf.org%2Farchive%2Fid%2Fdraft-ietf-netmod-yang-versioning-reqs-&data=05%7C01%7Cjschoenwae%40constructor.university%7Cb1d7ba4086994666f7bc08dbe62a895f%7Cf78e973e5c0b4ab8bbd79887c95a8ebd%7C0%7C0%7C638356842599181819%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=mToffeBs6EqTWG6FnQzemM4cQlx7PdN%2BCK2ldHUxMYg%3D&reserved=0
> > 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://eur01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fnotes.ietf.org%2FCdKrT5kVSF6qbnRSY4KeSA%3Fboth&data=05%7C01%7Cjschoenwae%40constructor.university%7Cb1d7ba4086994666f7bc08dbe62a895f%7Cf78e973e5c0b4ab8bbd79887c95a8ebd%7C0%7C0%7C638356842599181819%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=TLBU8t%2BDky6T9wHbWtix699ImOUayYFVaIPC7EVQNTA%3D&reserved=0
> > > > >
> > > > >
> > > > > 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://eur01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fnotes.ietf.org%2FCdKrT5kVSF6qbnRSY4KeSA%3Fboth&data=05%7C01%7Cjschoenwae%40constructor.university%7Cb1d7ba4086994666f7bc08dbe62a895f%7Cf78e973e5c0b4ab8bbd79887c95a8ebd%7C0%7C0%7C638356842599181819%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=TLBU8t%2BDky6T9wHbWtix699ImOUayYFVaIPC7EVQNTA%3D&reserved=0
> > > > >
> > > > > 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://eur01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fwww.ietf.org%2Fmailman%2Flistinfo%2Fnetmod&data=05%7C01%7Cjschoenwae%40constructor.university%7Cb1d7ba4086994666f7bc08dbe62a895f%7Cf78e973e5c0b4ab8bbd79887c95a8ebd%7C0%7C0%7C638356842599181819%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=P8IzGqzGsqheqNe%2BcIEUtE1e4hdJNG1I7Amo%2BryWPM0%3D&reserved=0
> > > >
> > > >
> > > > --
> > > > Jürgen Schönwälder              Constructor University Bremen gGmbH
> > > > Phone: [phone]         Campus Ring 1 | 28759 Bremen | Germany
> > > > Fax:   [phone]         <https://eur01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fconstructor.university%2F&data=05%7C01%7Cjschoenwae%40constructor.university%7Cb1d7ba4086994666f7bc08dbe62a895f%7Cf78e973e5c0b4ab8bbd79887c95a8ebd%7C0%7C0%7C638356842599181819%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=TmXcqltoqstXmxR52%2BOh8yEwk3B2oi4EGMb%2FIgxMSnU%3D&reserved=0>
> > > >
> > > > _______________________________________________
> > > > netmod mailing list
> > > > [e-mail]
> > > > https://eur01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fwww.ietf.org%2Fmailman%2Flistinfo%2Fnetmod&data=05%7C01%7Cjschoenwae%40constructor.university%7Cb1d7ba4086994666f7bc08dbe62a895f%7Cf78e973e5c0b4ab8bbd79887c95a8ebd%7C0%7C0%7C638356842599181819%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=P8IzGqzGsqheqNe%2BcIEUtE1e4hdJNG1I7Amo%2BryWPM0%3D&reserved=0
> > > > _______________________________________________
> > > > netmod mailing list
> > > > [e-mail]
> > > > https://eur01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fwww.ietf.org%2Fmailman%2Flistinfo%2Fnetmod&data=05%7C01%7Cjschoenwae%40constructor.university%7Cb1d7ba4086994666f7bc08dbe62a895f%7Cf78e973e5c0b4ab8bbd79887c95a8ebd%7C0%7C0%7C638356842599181819%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=P8IzGqzGsqheqNe%2BcIEUtE1e4hdJNG1I7Amo%2BryWPM0%3D&reserved=0
> > > >
> > 
> > --
> > Jürgen Schönwälder              Constructor University Bremen gGmbH
> > Phone: [phone]         Campus Ring 1 | 28759 Bremen | Germany
> > Fax:   [phone]         <https://eur01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fconstructor.university%2F&data=05%7C01%7Cjschoenwae%40constructor.university%7Cb1d7ba4086994666f7bc08dbe62a895f%7Cf78e973e5c0b4ab8bbd79887c95a8ebd%7C0%7C0%7C638356842599181819%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=TmXcqltoqstXmxR52%2BOh8yEwk3B2oi4EGMb%2FIgxMSnU%3D&reserved=0>

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