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

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

Hi Kent, all,

My understanding is that the decision was to use the URL for the module itself, not for the YANG Module Names registry itself or the "source" registry. That is, https://www.iana.org/assignments/yang-parameters/[e-mail] rather than https://www.iana.org/assignments/yang-parameters or https://www.iana.org/assignments/bfd-parameters.

About this:

> description:
>         This update reflects a First Come, First Served request
>         made by John Smith via email 123456.

Please add a preferred description format to 8407bis if there's specific information you'd like us to include.  Right now we're adding descriptions like "Registered ifType 303",  "Changed gpon description to refer to G.984",  "Updated reference for 64 and 65".

It should be noted that although we typically have to add or update only one entry at a time, there's a revision in iana-iftype-yang that added five. 

thanks,
Amanda

On Wed Mar 06 14:24:17 2024, [e-mail] wrote:
> Hi Amanda,
> 
> I never want to see a URL to https://www.iana.org/assignments/yang-
> parameters in the “reference”.
> My previous example shows the module’s top-level description already
> indicating that all modules can be found at
> https://www.iana.org/assignments/yang-parameters, so the additional
> link would be redundant.
> 
> For the revision-specific description and reference statements, as
> Martin points out, the “description” is the *why* and the “reference”
> is the *where*, only I think it is important to spell it out:
> 
> description: why was the change made
> reference: where is it shown that the *why* happened
> 
> In the simplest case, there is an RFC:
> 
> description:
>         This update reflects the update made to the underlying
>         Foo Bar registry per RFC YYYY.
>  reference:
>         RFC YYYY: Extend the Foo Bars Registry to Support
>         Something Important
> 
> For weird things like FC/FS and Expert Review, firstly I assume that
> 1) the request comes to IANA (as IANA doesn’t make stuff up on their
> own) and 2) the request is in some achievable form, even if just a
> IANA-ticket or an email, so then we might have:
> 
> description:
>         This update reflects a First Come, First Served request
>         made by John Smith per IANA ticket 123456.
>  reference:
>         https://iana.org/tickets/123456
> 
> Or perhaps:
> 
> description:
>         This update reflects a First Come, First Served request
>         made by John Smith via email 123456.
>  reference:
>         https://iana.org/mailing-list/requests/123456
> 
> Or, in the very worst case:
> 
> description:
>         This update reflects a First Come, First Served request
>         made by John Smith via a hallway conversation.
>  reference:
>         No reference to the conversation can be provided.
> 
> 
> Makes sense?
> Kent
> 
> 
> 
> 
> > On Mar 5, 2024, at 8:18 PM, Amanda Baber via RT <iana-
> > [e-mail]> wrote:
> >
> > 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
> >