Re: [netmod] Updated Content of Module Versioning - T7 (Filename changes)

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

Hi all,

We discussed this in the weekly YANG versioning call. There have been concerns expressed on the list about weakening the format specified as a SHOULD in RFC7950 and about the time it may take for the ecosystem of tools to be updated. There is not any clear consensus that we should keep the new label-based filename recommendation.

So we’re proposing to remove this new filename convention from the Module Versioning draft. That means there would be no particular standardized way of putting a label (yang semver label) in the module filename. We’d stick with the RFC7950 [e-mail]<mailto:[e-mail]> format for now (or of course the format without any label or date: my-module.yang).

If anyone feels that you can’t live without the new filename format specified (e.g. [e-mail]<mailto:[e-mail]>) now is the time to speak up. Otherwise we’ll remove it from the next iteration of Module Versioning.

Jason

From: Andy Bierman <[e-mail]>
Sent: Wednesday, October 25, 2023 4:28 PM
To: Jürgen Schönwälder <[e-mail]>; Jason Sterne (Nokia) <[e-mail]>; [e-mail]
Subject: Re: [netmod] Updated Content of Module Versioning - T7 (Filename changes)


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.




On Wed, Oct 25, 2023 at 11:49 AM Jürgen Schönwälder <[e-mail]<mailto:[e-mail]>> wrote:
I strongly disagree. You can add additional file names, you can't
soften the existing SHOULD to a conditional SHOULD.

+1

Getting tools to handle the file naming patterns defined in RFC 7950 took a long time.
It would be disruptive to introduce yet another file-naming pattern.
It would also be another NBC change forced on YANG 1.1 tools.


/js

Andy

On Wed, Oct 25, 2023 at 06:45:31PM +0000, Jason Sterne (Nokia) wrote:
> Sure - I'd be OK with adding some wording here that makes it clear the 7950 recommendation remains.
>
> i.e. you SHOULD use my-module@2023-01-06 as per 7950, but if you elect to not use that format, and want to use a label in the filename, then this format is RECOMMENDED:  my-module#3.0.2.yang.
>
> I can see that 'primary identifier' isn't great. Maybe something more like "to uniquely identify the version of the module" or similar.
>
> Jason
>
> > -----Original Message-----
> > From: Jürgen Schönwälder <[e-mail]<mailto:[e-mail]>>
> > Sent: Wednesday, October 25, 2023 2:32 PM
> > To: Jason Sterne (Nokia) <[e-mail]<mailto:[e-mail]>>
> > Cc: [e-mail]<mailto:[e-mail]>
> > Subject: Re: [netmod] Updated Content of Module Versioning - T7
> > (Filename changes)
> >
> >
> > CAUTION: This is an external email. Please be very careful when clicking
> > links or opening attachments. See the URL nok.it/ext<http://nok.it/ext> for additional
> > information.
> >
> >
> >
> > It needs to be clear that the existing text in section 5.2 remains
> > untouched.
> >
> >    YANG modules and submodules are typically stored in files, one
> >    "module" or "submodule" statement per file.  The name of the file
> >    SHOULD be of the form:
> >
> >      module-or-submodule-name ['@' revision-date] ( '.yang' / '.yin' )
> >
> >    "module-or-submodule-name" is the name of the module or submodule,
> >    and the optional "revision-date" is the latest revision of the module
> >    or submodule, as defined by the "revision" statement (Section 7.1.9).
> >
> > Words like 'primary identifier' confuse me.
> >
> > /js
> >
> > On Wed, Oct 25, 2023 at 06:22:57PM +0000, Jason Sterne (Nokia) wrote:
> > > Hi all,
> > >
> > > Starting a dedicated thread for T7 Filename changes.
> > >
> > > These are my own personal opinions (not those of the
> > authors/contributors).
> > >
> > > RFC7950 says that the filename format SHOULD be my-module@2023-01-
> > 06.yang<mailto:[e-mail]<mailto:[e-mail]>>
> > >
> > > Module versioning currently says the following format is RECOMMENDED
> > (if the file has a revision label):  my-module#3.1.2.yang
> > >
> > > I'd recommend we remove that from Module Versioning, but add it to the
> > YANG Semver draft (where all revision label text will be located - it is all
> > being removed from Module Versioning).
> > >
> > > We could potentially say it more like this:
> > >
> > >   If a revision has an associated yang-semver-label, and if the publisher
> > >  wishes to use the label in the filename as the primary identifier for the
> > >  version of the module instead of the revision date, then it is
> > >   RECOMMENDED to put the yang-semver-label into the filename as
> > follows:
> > >
> > >      module-or-submodule-name ['#' yang-semver-label] ( '.yang' / '.yin' )
> > >
> > >        E.g., acme-router-module#2.0.3.yang
> > >
> > >   YANG module (or submodule) files may be identified using either the
> > >   revision-date (as per [RFC8407] section 3.2) or the revision label.
> > >
> > > If we don't at least have a recommendation (*if* people really want to put
> > the label in the filename), then we might have different organizations using
> > different formats:
> > >
> > >   *   org #1:   [e-mail]<mailto:[e-mail]<mailto:[e-mail]>>
> > >   *   org#2:    my-module#[e-mail]<mailto:my-<mailto:my->
> > module#[e-mail]<mailto:module#[e-mail]>>
> > >   *   org#3:    my-module%2.0.3.yang
> > >   *   org#4:    my-module(2.0.3).yang
> > >
> > > I'm trying to find wording that doesn't strongly mandate the my-
> > module#2.0.3.yang filename format, but does highly recommend it *if*
> > someone is going to put a label in the filename somewhere.
> > >
> > > Jason
> > >
> > >
> > > From: netmod <[e-mail]<mailto:[e-mail]>> On Behalf Of Jason Sterne
> > (Nokia)
> > > Sent: Tuesday, October 24, 2023 9:58 AM
> > > To: [e-mail]<mailto:[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]<mailto:[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/>

--
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]<mailto:[e-mail]>
https://www.ietf.org/mailman/listinfo/netmod