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

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

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

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. 

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.  

2) If we use the submitter's description, would it be useful for us to automatically prepend something like "Added value 47."?

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)

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?

Note that this description may need to cover multiple assignments.

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

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

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.

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

thanks,
Amanda