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

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

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.

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.

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