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

[Martin Björklund <[e-mail]>]

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/[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