[yang-doctors] [IANA #1289473] Revision statements in IANA-maintained YANG modules

[Amanda Baber via RT <[e-mail]>]

Hi all,

Do you agree that for references in IANA-maintained module revision statements, the "always point to the module URL" instruction should be changed to "point to the RFC if there is one, and to the module URL if there isn't"? 

thanks,
Amanda

On Thu Feb 29 14:31:51 2024, [e-mail] wrote:
> Hi,
> 
> 
> "Amanda Baber via RT" <[e-mail]> wrote:
> > Hi,
> >
> > I'm writing to ask whether IANA's approach to references in revision
> > statements in IANA-maintained modules should be reconsidered.
> >
> > I was talking to Kent Watsen about
> > draft-ietf-netconf-ssh-client-server-38, which asks IANA to refer to
> > RFCs in revision statements for IANA-maintained modules. (See the
> > third-to-last paragraph of Section 6.3 for an example.)
> >
> > We understood that because some registrations (for example, those
> > coming from First Come First Served or Expert Review registries)
> > aren't associated with an RFC, the YANG doctors prefer that we
> > instead
> > point to the location of the module (e.g.,
> > "https://www.iana.org/assignments/yang-parameters/iana-tunnel-
> > [e-mail]")
> > in the revision statement. This is reflected in 8407bis:
> >
> > When the "iana-foo" YANG module is updated, a new "revision"
> > statement with a unique revision date must be added in front of the
> > existing revision statements. The "revision" statement must have a
> > "reference" substatement that points specifically to the published
> > module (i.e., IANA_FOO_URL_With_REV).
> >
> > After talking to Kent, I'm wondering whether we should instead point
> > to the RFC by default, and point to the module when there is no RFC
> > to
> > point to.
> 
> This sounds like a good idea!
> 
> > I'm forwarding Kent's suggestion (and copying him on this email):
> >
> > ===
> >
> > Though I see that Lada/Acee/Mahesh did not “object”, I don’t like the
> > advice of just pointing to the URL of the YANG module, nor do I agree
> > with Martin’s statement:
> >
> > "The motivation behind the rule is to make it easy for readers
> > of a module to find the original source of the module."
> >
> > Perhaps I misunderstand what Martin means by “rule”, but will say
> > that
> > the common sense understanding is that the purpose of the revision
> > statement is to explain *why* the module is being updated, and not so
> > much *where* it can be downloaded.
> 
> The "description" in the "revision" statement should explain the
> *why*,
> and the "reference" (in this case) the *where*.  (I suggested the url
> in order to have a simple instruction that always works.  The new
> proposal is better.)
> 
> Currently there are no instructions for IANA to fill in the
> "description" statement, AFAIK.
> 
> > Furthermore, regarding where the module can be downloaded, it seems
> > that it is something that should be in the top-level “description”
> > statement and, in fact, could apply to *all* YANG modules published
> > by
> > the IETF (not just those that are IANA-maintained).
> >
> > To be constructive, let me give a concrete example of what I think
> > would be super. Assume there is an IANA-maintained module called
> > “iana-foo-bar” that was initially created by RFC XXXX and
> > subsequently
> > updated (by IANA) due to the underlying “Foo Bar” registry being
> > updated due to RFC YYYY. Here’s what I’d like to see as a
> > module-reader:
> >
> > module iana-foo-bar {
> > <snip/>
> >
> > description
> > "This module defines enumerations for foo bars
> > defined in the ‘Foo Bar' registry maintained by IANA
> > at https://www.iana.org/assignments/foo-bar-parameters.
> >
> > <snip/>
> >
> > All versions of this module are published by IANA at
> > https://www.iana.org/assignments/yang-parameters.”;
> >
> > revision 2024-02-02 {
> > description
> > “This update reflect the update made to the underlying
> > Foo Bar registry per RFC YYYY.”;
> > reference
> > "RFC YYYY: Extend the Foo Bars Registry to Support Something
> > Important";
> > }
> >
> > revision 2024-01-01 {
> > description
> > “This initial version of the module was created using
> > the mechanism defined in RFC XXXX to reflect the
> > contents of the underlying ‘Foo Bar’ registry maintained
> > by IANA.”;
> > reference
> > "RFC XXXX: YANG Data Model for Foo Bars";
> > }
> >
> > <snip/>
> > }
> >
> > ===
> >
> > IANA, I should add, has no preference between always pointing to the
> > module URL and only pointing to the module URL in the absence of a
> > reference to an RFC (which is technically a possibility where SSH
> > Expert Review registrations are concerned).
> >
> > thanks,
> > Amanda
> 
> If we agree that this is the way it should work, it should be
> reflected in 8407bis.
> 
> 
> /martin