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

[Andy Bierman <[e-mail]>]

On Wed, Oct 25, 2023 at 11:49 AM Jürgen Schönwälder
<[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]>
> > > Sent: Wednesday, October 25, 2023 2:32 PM
> > > To: Jason Sterne (Nokia) <[e-mail]>
> > > Cc: [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.
> > >
> > >
> > >
> > > 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]>
> > > >
> > > > 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]>
> > > >   *   org#2:    my-module#[e-mail]<mailto:my-
> > > 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]> 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/>
>
> --
> 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
>