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

[Kent Watsen <[e-mail]>]

Hi all,

Amanda, Rob, Mahesh, Murray (CC-ed), and I all met a couple days ago.  After about 30-mins or so, we came to an understanding for how IANA should set the “revision” statements for updates to IANA-maintained YANG modules.

1) For the revision statement’s “description” field:
	- the goal is to capture what changed.
		- did an algorithm get added?
		- did an algorithm get deprecated, discouraged, or obsoleted?
	- for updates made due to an RFC 
		- the description could be as simple as “Applied updates as specified by RFC XXXX.”
		- or, if easy enough, enumerate the specific changes…
	- for updates made by other means (e.g., FC/FS or Expert-review)
		- the description could be as simple as “Applied updated as specified by <FC/FS or expert-review>”
		- or, if easy enough, enumerate the specific changes…

2) For the revision statement’s “reference” field:
	- the goal is to point to some authoritative artifact
	- for updates made due to an RFC
		- the description should be “RFC XXXX: <titile of RFC XXXX>”
	- for updates made by other means (e.g., FC/FS or Expert-review)
		- the description should be “Please see the underlying registry for details.”
		- PS: at this time, the underlying registries do NOT capture such details
			- but this isn’t seen as a problem for what we’re trying to accomplish

Comments?

Kent


> On Mar 13, 2024, at 9:41 AM, Kent Watsen <[e-mail]> wrote:
> 
> Hi Mahesh,
> 
>> On Mar 12, 2024, at 4:25 PM, Mahesh Jethanandani <[e-mail]> wrote:
>> 
>> Hi Kent,
>> 
>>> On Mar 11, 2024, at 2:31 PM, Kent Watsen <[e-mail] <mailto:[e-mail]>> wrote:
>>> 
>>> Hi Mahesh, Amanda,
>>> 
>>> 
>>>> On Mar 8, 2024, at 8:12 PM, Mahesh Jethanandani <[e-mail] <mailto:[e-mail]>> wrote:
>>>> 
>>>> 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].
>>> 
>>> I don’t agree.  
>>> 
>>> As I wrote before, I never want to see a URL to https://www.iana.org/assignments/yang-parameters in the “reference”.   To which, Martin said my proposal seemed better and you wrote "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."
>>> 
>>> Just because Amanda explains their ticketing system is private doesn’t mean we have to throw out the whole idea.   Amanda’s proposal to have "[IANA #123456]: [e-mail] <mailto:[e-mail]>” would be fine, IMO.
>> 
>> Ok. The problem of the ticketing system being private is much like a reference that is behind a paywall, where most of us cannot see it. But if others agree, I can live with it.
>> 
>>> 
>>> That said, it seems odd that the authoritative reference is something the IETF has to discuss at all.  It is wholly in IANA’s court.  The YANG-module for any underlying IANA-maintained registry should get all its data from that registry.  Never should IANA have to create a secondary reference that isn’t in the underlying registry.  Stated differently, I don’t think rfc8407bis should have recommendations that exceed what is possible using just the data in the underlying registry.
>> 
>> Agree.
>> 
>>> 
>>> Case in point, [1] points to [2] and [3] as examples of a First Come, First Served registries.  In both cases there is a column called “Reference” that usually points to an RFC, but sometimes points to a “Contact”, which is effectively a name and an email address.
>>> [1] https://datatracker.ietf.org/doc/html/rfc8126#section-4.4
>>> [2] https://www.iana.org/assignments/sasl-mechanisms/sasl-mechanisms.xhtml
>>> [3] https://www.iana.org/assignments/ldap-parameters/ldap-parameters.xhtml
>>> 
>>> 
>>> IMO, these are not great “references”, such that I recommend IANA institute a global update for how non-RFC references are tracked, but that is out-of-scope to rfc8407bis.  
>> 
>> If they are not great “references”, then isn’t that a problem? If we were to fix it, e.g. by using the same ticketing reference, it would address both the question of asserting anything that the underlying registry does not do, and it will provide a better reference.
> 
> True, but the “fix” is something IANA has to internalize.  We may be able to paper over it, but the root-issue doesn’t go away.   Note that it is even more important that updates to the underlying registry are verifiable than it is that the updates to the YANG module are verifiable.
> 
> Something to consider, if ever a script is written to automatically create YANG modules for [2] and/or [3], you can be sure that the script will just use the data present in the registry, which will be just a person’s name/email in some cases.
> 
> 
>> The problem that I see is specifically with the second example reference, i.e., if the reference is via an individual. If that person is not available or not responding to any queries, how does one validate the reference?
> 
> True, but this is IANA’s system.  The source of truth lies there.  Currently they only have a name/email for some “References”.   What they may actually want/need are two fields:
> 	- Reference:  an RFC, ticket#, email-archive link, etc.
> 	- Contact: The IESG, name/email, etc.
> 
> But, again, out of our hands, and possible beyond what rfc8407bis can fix.
> 
> Kent
> 
> 
> 
>>> With this in mind, perhaps the “revision” statement might be like this?
>>> 
>>> 	If the reference a via an RFC
>>> 	======================
>>> 	revision 2024-03-11 {
>>> 		description
>>> 			“Added the FOO_BAR algorithms per RFC 1234"
>>> 		reference 
>>> 			“RFC 1234: Additional Foo Bar Algorithms.”
>>> 
>>> 	If the reference is via an individual
>>> 	==========================
>>> 	revision 2024-03-11 {
>>> 		description
>>> 			“Added the FOO_BAR algorithms per request by John Smith."
>>> 		reference 
>>> 			“John Smith: [e-mail] <mailto:[e-mail]>”
>>> 
>>> 	If the reference is unknown
>>> 	=====================
>>> 	revision 2024-03-11 {
>>> 		description
>>> 			“Added the FOO_BAR algorithms."
>>> 		reference 
>>> 			“Unknown: The underlying foo-bar registry does not track this information.”
>>> 
>>> 
>>> Thoughts?
>>> 
>>> Kent
>>> 
>>> 
>>> 
>>>> 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] <mailto:[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] <mailto:[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] <mailto:[e-mail]>
>>>>> https://www.ietf.org/mailman/listinfo/yang-doctors
>>>> 
>>>> 
>>>> Mahesh Jethanandani
>>>> [e-mail] <mailto:[e-mail]>
>>>> 
>>>> 
>>>> 
>>>> 
>>>> 
>>>> 
>>>> _______________________________________________
>>>> yang-doctors mailing list
>>>> [e-mail] <mailto:[e-mail]>
>>>> https://www.ietf.org/mailman/listinfo/yang-doctors
>> 
>> 
>> Mahesh Jethanandani
>> [e-mail] <mailto:[e-mail]>
>> 
>> 
>> 
>> 
>> 
>> 
> 
> _______________________________________________
> yang-doctors mailing list
> [e-mail]
> https://www.ietf.org/mailman/listinfo/yang-doctors