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

[Mahesh Jethanandani <[e-mail]>]

Hi Amanda, please wait on further instructions before implementing anything new at this time.

I went back to the thread that Amanda started in November, and here is a summary of discussion we have had. Cutting and pasting some of the text from earlier threads as needed.

1. When an IANA module is first published on IANA’s web site, the IANA module is copied as-is from the RFC to form the original version. Subsequent updates, should result in:

1a. Adding a “revision” statement at the top level that contains a “description" statement as discussed in 2.
1b. Addition of a “reference” statement in the same “revision” statement as discussed in 3.
1c. The description of the module should be updated from:

    This version of this YANG module is part of RFC XXXX; see
    the RFC itself for full legal notices.”;

     to say:

    This original version of this YANG module is part of RFC XXXX; see
    the RFC itself for full legal notices.";

2. IANA will ask the requestor to provide a “description” statement to be inserted as part of the update to the “revision” statement. That “description" statement may or may not include a RFC number.

3. Cutting and pasting Martin’s response here.

>  RFC 8407 currently says:
> 
>   A "revision" statement MUST be present for each published version of
>   the module.  The "revision" statement MUST have a "reference"
>   substatement.  It MUST identify the published document that contains
>   the module.
> 

[My own addition] In the case there is an RFC that updates the IANA module, that RFC should be used in the “reference" statement.

> 
> In this case, there really isn't any "published document" - the module
> is published directly on the web.  One option could be to add the URL
> to the module in "reference".  The motivation for the rule is:
> 
>   Modules are often extracted from their original
>   documents, and it is useful for developers and operators to know how
>   to find the original source document in a consistent manner.
> 
> So the URL would help for this.

In light of the fact what Amanda stated, that the IANA ticket system is not visible to outsiders, it makes sense to go with Martin’s proposal. Does anyone strongly disagree. In other words. 

Is it agreed that if IANA registers a codepoint in a First Come First Served or Expert Review range, and there is no associated specification, IANA will list a URL in the reference statement. It would for example use https://www.iana.org/assignments/yang-parameters/[e-mail] <https://www.iana.org/assignments/yang-parameters/[e-mail]>.

If agreed, we will ask Med to update 8407bis to reflect this.

Thanks.


> On Mar 8, 2024, at 10:51 AM, Amanda Baber via RT <[e-mail]> wrote:
> 
> Hi Kent,
> 
> Sorry, I didn't make this clear: tickets (and the IANA github) aren't public. They require an IANA login. That's why, if you want to use the ticket number, I was suggesting something like
> 
> reference
> [IANA #123456]: [e-mail]
> 
> instead of 
> 
> reference:
> https://iana.org/tickets/123456 [not the actual link]
> 
> That way someone could contact us and refer to ticket 123456, which we could then use to find the ticket quickly. 
> 
> It should be noted, though, that in addition to not giving the requester direct access, all this does for IANA is save a minute or two. We can also search the ticket system for the name of the registration or the date it was completed, or we can look at the commit message for the file that was created on that date.
> 
>> From our perspective, it might be more useful to link to, e.g., https://www.iana.org/assignments/address-family-numbers for an Address Family Number registration, which would allow the reader to find the contact information for John Smith directly via the registration's reference field. 
> 
>> It was my assumption that all existing registrations would be
>> grandfathered together under a single top-level “revision” statement,
>> pointing to the RFC that created the IANA-defined YANG module (e.g.,
>> my two drafts going thru the IESG right now).
> 
> That's our understanding as well.
> 
>> What we’re discussing here/now is how IANA sets the top-level
>> “revision” statement for all subsequent updates to the YANG module,
>> made by IANA.
> 
> That's our understanding too.
> 
>>> 2) If we use the submitter's description, would it be useful for us
>>> to automatically prepend something like "Added value 47."?
>> 
>> Yes.  In general, it would be helpful towards making the top-level
>> “revision” statement’s “description” better at explaining *why* the
>> module was updated, to include whatever tid-bits of information
>> possible.
>> 
>> That said, I suggest using discretion, as sometimes it may be
>> overwhelming to list out, e.g., a family of updates, in which case, it
>> might be better for the description to refer to the family as a whole.
>> 
> <snip>
>> 
>>> 4) For the submitter-provided description, could a document like
>>> 8407bis provide examples in this style that we can refer Expert
>>> Review/FCFS requesters to? If not, would it be possible to provide
>>> something for our internal records? At the moment I'm not sure we
>>> have any particularly verbose ones (outside of the initial
>>> revisions).
>>> 
>>> Or would this just be the description that we entered in the
>>> registry's name/description field?
>> 
>> We’re possibly overthinking this  :/
> 
> I'm asking for examples because applicants (for various types of registrations) don't always know what kind of answers they're expected to provide. In this case, we wouldn't be able to tell them, and would have to put the registration on hold while we asked the YANG doctors.
> 
>> For updates to the underlying registry that did NOT come from a
>> normative document, no user-supplied description is needed.  The
>> important thing to capture is:
>> 
>> 1) *why* is the module being updated
>>       - this is in the “description” statement
>> 
>> 2) *where* is the proof that the *why* occurred
>>      - this is in the “revision” statement
> 
> If descriptions need to be captured for some revision statements and not for others, and this can't be recorded in an RFC (as in 8407bis or a similar document rather than a document that creates a specific module), we need clear instructions from the group. 
> 
> IANA maintains more than 3000 registries, and won't always have the same staff working in the IETF area, so special instructions need to be recorded, if only in our internal wiki. If the instructions are coming informally, from correspondence, we'd also like them to be validated by the AD on the list.
> 
>> We may wish to  have a meeting, but maybe the following will make
>> sense.  Let me expand on the why/where from above:
>> 
>> 1) *why* is the module being updated
>>       - this is in the “description” statement
>>       - the description statement SHOULD contain an identifier of
>> some sort.  E.g., an RFC number, an IANA-ticket number, etc.
> 
> Does the RFC number belong in both the description field and the reference field?
> 
> thanks,
> Amanda
> 
> _______________________________________________
> yang-doctors mailing list
> [e-mail]
> https://www.ietf.org/mailman/listinfo/yang-doctors


Mahesh Jethanandani
[e-mail]