[netmod] YANG Versioning: filename recommendations for YANG Semver

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

Hello NETMOD WG,

At IETF 119, during the YANG Versioning discussions, there was a suggestion to raise the filename issue again as one last issue to resolve before going to last call.

Version 10 of Module Versioning had the following content that was subsequently removed in version 11:
https://datatracker.ietf.org/doc/html/draft-ietf-netmod-yang-module-versioning-10#name-file-names

3.4.1.  File names

   This section updates [RFC7950] section 5.2, [RFC6020] section 5.2 and
   [RFC8407] section 3.2

   If a revision has an associated revision label, then it is
   RECOMMENDED that the name of the file for that revision be of the
   form:

     module-or-submodule-name ['#' revision-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.

At least one major implementation is already using YANG Semver in filenames, and the IETF 119 attendees raised the concern that if we don't specify a desired filename format, then an de-facto standard will likely occur. Or perhaps we'll end up with multiple competing approaches to having a YANG Semver in a filename.

There are a number of advantages of having the key version identifier in the filename (hence why it is recommended in RFC 7950 and RFC 8407). Resolving the new 'recommended-min' extensions in Module Versioning and YANG Semver would also be easier if the YANG Semver is right in the filename.

In the IETF 118 Hackathon, Per demonstrated that modifying pyang to handle the additional filename format was a fairly trivial change. But it still may take other tool authors time to update other tools.

Some potential issues for us to consider & discuss as a WG:

  1.  Should we mention anything about potential use of symlinks (e.g. instead of having 2 copies of a module with two different filenames, one with revision date, the other with YANG Semver, just have one of them symlink to the other?)
  2.  The YANG Semver draft mandates that IETF YANG modules have a YANG Semver. Do we also need to recommend/mandate something specific about filenames for IETF YANG modules (e.g. in the CODE BEGINS line in RFCs)?
  3.  Will most tools that haven't been modified yet to recognize the new filename format simply interpret the #X.Y.Z as part of the module name? Will they complain that the filename doesn't match the module name?
  4.  Will some tools & processes fail because of the "#" (i.e. consider it a comment marker and chop off the chars that follow)?

Another possible approach is something along these lines:
*If* you are going to put a YANG Semver into a module filename, then you MUST use this format:   <name>#<yang semver>.yang

That doesn't preclude having both a revision date format and a YANG Semver format, but doesn't specifically suggest to use one or the other. Then perhaps YANG-NEXT could mandate the YANG Semver filename format?

So the big questions are:

  *   Whether to include this filename convention in the YANG Semver draft?
  *   How strong a recommendation/mandate should it be?

Jason (he/him)