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 <[email protected]> > Sent: Wednesday, October 25, 2023 2:32 PM > To: Jason Sterne (Nokia) <[email protected]> > Cc: [email protected] > 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:[email protected]> > > > > 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: [email protected]<mailto:[email protected]> > > * org#2: my-module#[email protected]<mailto:my- > module#[email protected]> > > * 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 <[email protected]> On Behalf Of Jason Sterne > (Nokia) > > Sent: Tuesday, October 24, 2023 9:58 AM > > To: [email protected] > > 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 > > [email protected] > > https://www.ietf.org/mailman/listinfo/netmod > > > -- > Jürgen Schönwälder Constructor University Bremen gGmbH > Phone: +49 421 200 3587 Campus Ring 1 | 28759 Bremen | Germany > Fax: +49 421 200 3103 <https://constructor.university/> _______________________________________________ netmod mailing list [email protected] https://www.ietf.org/mailman/listinfo/netmod
