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

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

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