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

[[e-mail]]

Hi Kent, all,

Thanks for sharing this update.

Please see inline.

Cheers,
Med

De : Kent Watsen <[e-mail]>
Envoyé : jeudi 21 mars 2024 10:35
À : Mahesh Jethanandani <[e-mail]>
Cc : Robert Wilton <[e-mail]>; Murray Kucherawy <[e-mail]>; BOUCADAIR Mohamed INNOV/NET <[e-mail]>; YANG Doctors <[e-mail]>; [e-mail]
Objet : Re: [yang-doctors] [IANA #1289473] Revision statements in IANA-maintained YANG modules


Sent from my iPhone


On Mar 21, 2024, at 10:20 AM, Mahesh Jethanandani <[e-mail]<mailto:[e-mail]>> wrote:
Hi Kent,

Overall this captures the conversation. Some minor comments/additions.


On Mar 21, 2024, at 10:09 AM, Kent Watsen <[e-mail]<mailto:[e-mail]>> wrote:

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…

                   - or ask the requestor to provide a description to be inserted …

Ah, yes, this also.  good catch.
[Med] Not sure this works as the requestor does only provide what is required by the authoritative registry; the requestor does not modify directly the YANG module and does not even need to be aware that such a module exists. Whether the content of a registry is displayed as XML, txt, or YANG is a matter of representation of the same content. Please refer to this part in the bis:

   IANA maintains a set of registries that are key for interoperability.
   The content of these registries are usually available using various
   formats (e.g., plain text, XML).  However, there were some confusion
   in the past about whether the content of some registries is dependent
   on a specific representation format.  For example, Section 5 of
   [RFC8892] was published to clarify that MIB and YANG modules are
   merely additional formats in which the "Interface Types (ifType)" and
   "Tunnel Types (tunnelType)" registries are available.  The MIB
   [RFC2863] and YANG modules [RFC7224][RFC8675] are not separate
   registries, and the same values are always present in all formats of
   the same registry.

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

You mean the reference should be pointer (URL?) to the underlying registry.

There is no need to do this.  The YANG module’s top-level “description” should have this URL (pointer to the underlying registry) already, hence it would be redundant to put again in the “revision” statement.

[Med] Hmm We are actually manipulating two types of links:
•   IANA_FOO_URL
•   IANA_FOO_URL_With_REV

The top level of the module points to the first URL, while the revision points to the one with _REV. Having the one with REV allows to points to a specific version of the modules, when newer revisions are made.
Cheers.

Likewise
Kent





                             - 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]<mailto:[e-mail]>> wrote:

Hi Mahesh,


On Mar 12, 2024, at 4:25 PM, Mahesh Jethanandani <[e-mail]<mailto:[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]<mailto:[e-mail]>
https://www.ietf.org/mailman/listinfo/yang-doctors



Mahesh Jethanandani
[e-mail]<mailto:[e-mail]>





____________________________________________________________________________________________________________
Ce message et ses pieces jointes peuvent contenir des informations confidentielles ou privilegiees et ne doivent donc
pas etre diffuses, exploites ou copies sans autorisation. Si vous avez recu ce message par erreur, veuillez le signaler
a l'expediteur et le detruire ainsi que les pieces jointes. Les messages electroniques etant susceptibles d'alteration,
Orange decline toute responsabilite si ce message a ete altere, deforme ou falsifie. Merci.

This message and its attachments may contain confidential or privileged information that may be protected by law;
they should not be distributed, used or copied without authorisation.
If you have received this email in error, please notify the sender and delete this message and its attachments.
As emails may be altered, Orange is not liable for messages that have been modified, changed or falsified.
Thank you.