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

[Kent Watsen <[e-mail]>]

Hi Amanda,

> On Mar 7, 2024, at 11:26 PM, Amanda Baber via RT <[e-mail]> wrote:
> 
> Hi Mahesh, all,
> 
> Many questions inline/below!
> 
>>> 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.
>> 
>> I assume you are talking about what to put in the reference in the
>> case when there is no document URL. But isn’t it in some sense
>> pointing to itself? It does not tell me the “where”.
>> 
>> For that reason, I like Kent’s idea of linking this somehow to the
>> request that resulted in the update to the module, however that comes
>> to IANA. If it comes in the form of a ticket, then hopefully that
>> ticket explains who made the request, why they made the request etc.
>> In other words, some form of traceability.
> 
> We can do something like this, but the reference doesn't quite work:
> 
>>>> description:
>>>>       This update reflects a First Come, First Served request
>>>>       made by John Smith per IANA ticket 123456.
>>>> reference:
>>>>       https://iana.org/tickets/123456

The above is perfect. 

> We have a searchable ticket archive that goes back to 2006, and that would get us all of the associated correspondence. We also record ticket numbers in Git commits. However, neither of those resources are public.

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). 

There is no need for a historical analysis.   But, if you look at the IANA-modules my Python script creates, you will see that each “enum” statement has a “revision” statement that points to the RFC that defined it. 

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. 

For these, the preference is always to point to a normative document (e.g., an RFC) requesting IANA to make the update to the underlying registry (which cascades into being an update to the YANG module). 

In case the update to the underlying registry is not via a normative document (e.g., FC/FS), then a link to the IANA ticket is perfect. 

> 
> About the description format:
> 
>> But maybe the requestor should be asked to tell you
>> what description should be added in the revision statement, rather
>> than you having to guess.
> 
> So here's a set of questions:
> 
> 1) Because we can't link to the ticket, should we provide IANA's contact information in the reference field? We could point to [e-mail], which appears at the beginning of the module, or https://www.iana.org/contact.  

For new requests to update the underlying registry (e.g., FC/FS), is my understanding correct that there would always now be an IANA-ticket that could be pointed at?

If so, then pointing to the ticket seems always possible going forward…


> 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. 


> 3) If we include the submitter's description, should the ticket number be moved to the reference field? This is assuming that you want both their description and the information about the source.
> 
> Does this revision statement work?
> 
> description:
> Added value 47. <description provided by applicant> This update reflects a First Come, First Served request made by John Smith.
> reference:
> [IANA #123456]: https://www.iana.org/contact
> 
> (or [e-mail], to keep people from faxing us)

I liked it better before, when the link to the ticket was provided. 


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

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 



> Note that this description may need to cover multiple assignments.

Indeed. 


> 5) If an RFC registers, e.g., an ifType, would you want the authors to include the revision statement in the document or just provide it to IANA informally (upon request)?

Neither.  These high-level descriptions are not required.   Though nice, there is no requirement to capture that detail. 


> 6) Can you confirm that these would be the correct revision statement references for other non-RFC documents?
> 
> a) For an I-D:
> 
> draft-ietf-netmod-extend-foo: Extend the Foo Bars Registry to Support
> Something Important
> 
> b) For a document that has a title (FCFS, Expert Review, or Specification Required):
> 
> ISO 99999: Large Numbers
> 
> c) For a document that exists only as, say, a Github page (FCFS, Expert Review, or Specification Required):
> 
> either
> 
> https://www.github/user/stuff
> 
> or
> 
> Title of Page: https://www.github/user/stuff
> 
> In this case, the new revision statement reference policy would be "refer to whatever specification is available, and to IANA's ticket number and contact information if they didn't provide a spec."


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. 

2) *where* is the proof that the *why* occurred 
      - this is in the “revision” statement 
      - the revision statement provides details about the identifier in the “description” statement.   For an RFC, this could be the “RFC XXXX: title” format.  For an IANA-ticket, this could be a hyperlink to the ticket. 


> My understanding is that we would not be adding references to non-IETF documents/webpages for actual module items. Let me know if that's not correct.

I’m unsure what “actual module items” means.  Do you mean the individual enum/identity statements?

I’m pretty sure the “revision” statement is optional, from a YANG-validation perspective.   But, in general, a pointer to *where* the underlying thing (e.g., algorithm) was defined would be good. 

Kent 

> 
> Mahesh, we can start implementing whatever's decided when you give us the word.
> 
> thanks,
> Amanda