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

[[e-mail]]

Hi Kent,

Hmm, RFC8407 already uses “--" for such instructions. Please check Section 3.7.1.

Not only we are consistent here, but we also ease the life of the authors who will consume the template.

I will proceed with the publication of the version I have so far, but I’m open to hear more feedback during the WGLC. Thanks.

Cheers,
Med

De : Kent Watsen <[e-mail]>
Envoyé : jeudi 18 avril 2024 02:33
À : BOUCADAIR Mohamed INNOV/NET <[e-mail]>
Cc : Mahesh Jethanandani <[e-mail]>; Rob Wilton (rwilton) <[e-mail]>; Murray Kucherawy <[e-mail]>; YANG Doctors <[e-mail]>; [e-mail]
Objet : Re: [yang-doctors] [IANA #1289473] Revision statements in IANA-maintained YANG modules


Hi Med,

I looked at your changes, but I think an even larger issue is at play.

My last message to you contained nicely written paragraphs, but you converted them into “instructions”, using some kind of “—“ syntax...

I object to the use of the “—“ syntax to express instructions.  Not only was this syntax not present in the original RFC 8407, but such instruction-language is not properly specified anywhere.  Despite best intentions, common English grammar/syntax is best.

PS: I recognize that the “YANG Doctors” list should be CC-ed here.  Please view this reply as an early WGLC comment.

Kent




On Apr 16, 2024, at 3:45 AM, [e-mail]<mailto:[e-mail]> wrote:

Hi Kent,

Thank you for the review and good suggestions.

The changes I made so far can be tracked here: Diff: draft-ietf-netmod-rfc8407bis.txt - draft-ietf-netmod-rfc8407bis.txt<https://author-tools.ietf.org/api/iddiff?url_1=https://boucadair.github.io/rfc8407bis/draft-ietf-netmod-rfc8407bis.txt&url_2=https://boucadair.github.io/rfc8407bis/boucadair-patch-2/draft-ietf-netmod-rfc8407bis.txt>

Please see inline.

Cheers,
Med

De : Kent Watsen <[e-mail]<mailto:[e-mail]>>
Envoyé : lundi 15 avril 2024 17:55
À : BOUCADAIR Mohamed INNOV/NET <[e-mail]<mailto:[e-mail]>>
Cc : Mahesh Jethanandani <[e-mail]<mailto:[e-mail]>>; Rob Wilton (rwilton) <[e-mail]<mailto:[e-mail]>>; Murray Kucherawy <[e-mail]<mailto:[e-mail]>>; YANG Doctors <[e-mail]<mailto:[e-mail]>>; [e-mail]<mailto:[e-mail]>
Objet : Re: [yang-doctors] [IANA #1289473] Revision statements in IANA-maintained YANG modules


Hi Med,

Thank you for your continued effort to push this forward.  Your update captures the essence of the agreement made, but can be improved.  Below I provide spec-text that blends both of our contributions.

First, not discussed before, let’s update Section 4.8, which currently says:

   The "description" statement MUST be present.  For modules published
   within IETF documents, the appropriate IETF Trust Copyright text MUST
   be present, as described in Section 3.1.

To also point to the YANG Parameters registry, like so:

  The "description" statement MUST be present.  For modules published
   within IETF documents, the appropriate IETF Trust Copyright text MUST
   be present, as described in Section 3.1, and contain the following statement:



      All revisions of IETF and IANA published modules can be found at the YANG
      Parameters registry: https://www.iana.org/assignments/yang-parameters.

[Med] We also need to update the module templates to be consistent with this guidance.

With the above stated at the module-level, the same doesn’t need to be stated again (in any form) at the revision-level.


Next are a series of updates to 4.30.3.1 (Template for IANA-Maintained Modules with Identities).  Of course, similar text-updates would apply to Section 4.30.3.2 (for enumerations).  The following diffs your patch at: https://boucadair.github.io/rfc8407bis/boucadair-patch-2/draft-ietf-netmod-rfc8407bis.txt.


A paragraph halfway-down begins:

   When the "iana-foo" YANG module is updated, a new "revision"
   statement with a unique revision date must be added in front of the
   existing revision statements.

I think that it would help to finish the paragraph there with the following sentence:

   The revision statement MUST contain both “description” and
   “reference” substatements as follows.

[Med] OK

Then we’d have a section/paragraph for each substatement.  For instance:

   The “description” substatement captures what changed in the
   revised version.  Ideally, the description notes which identities

[Med] Updated the text to cover other changes such as updating description or reference of existing entries. The draft already includes an example for such changes (from https://www.iana.org/assignments/yang-parameters/[e-mail]):

   revision 2023-04-25 {
     description "Updated reference for 64 and 65.";
  }

   revision 2022-05-30 {
     description "Updated description, reference for 64 and 65.";
  }

   were, added, or had their status changed, e.g., deprecated,
   discouraged, obsoleted, etc.  When such a description is
   infeasible, the description varies on how the update is triggered.
   If the update is triggered by the publication of an RFC, the
   description should be "Applied updates as specified by RFC
   XXXX.”

[Med] Went with almost all the proposed changes. However, I used a format that eases to consume the template. The authors will need to pick whatever is applicable in their case.

 Otherwise, if the update is made following another
   IANA registration policy (Section 4 of [RFC8126]), IANA may
   ask the requestor to provide a description to be inserted

[Med] I don’ think this one is optimal especially that the authors of the changes are not even aware that a YANG module exists. For example, I have requested recently a new RR (https://www.iana.org/assignments/dns-parameters/RESINFO/resinfo-completed-template), which was automatically echoed in iana-dns-class-rr-type as follows:

   revision 2023-11-27 {
     description "Registered RR Type RESINFO 261.";
  }

I don’t think it is a good idea to have specifics for yang modules, especially that we say the following:

   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.

    …
   The following section provides a set of guidelines for YANG module
   authors related to the design of IANA-maintained modules.  These
   guidelines are meant to leverage existing IANA registries and use
   YANG as another format to present the content of these registries
    when appropriate.

, or
   use the statement "Applied updates corresponding to those
   made in the underlying IANA registry.”



   The "reference” substatement points to an authoritative event
   triggering the update to the YANG module.

[Med] I think we should keep a reference to specific version of the module. Such referencing is useful compared to duplicating RFC points at the level of modified entries and top level reference. Here is an example of a duplicate information from https://www.iana.org/assignments/yang-parameters/[e-mail]:

   revision 2021-04-23 {
     description
       "Registered tunnelType 19.";
     reference
       "RFC 4301: Security Architecture for the Internet Protocol";
   }

   revision 2019-11-16 {
     description
       "Initial revision.";
     reference
       "RFC 8675: A YANG Data Model for Tunnel Interface Types";
   }

   ...

   identity ipsectunnelmode {
     base ift:tunnel;
     description
       "IpSec tunnel mode encapsulation.";
     reference
       "RFC 4301: Security Architecture for the Internet Protocol";
   }

Mentioning 4301 at the top level does not bring much value given this is does no reveal the event triggered the update (that is 19 registration at the first place). Given that no other information is available in the part registry, at least the reference to the specific revision of the module should be listed as follows:

   revision 2021-04-23 {
     description
       "Registered tunnelType 19.";
     reference
       "https://www.iana.org/assignments/yang-parameters/iana-tunnel-\<https://www.iana.org/assignments/yang-parameters/iana-tunnel-/>
                                                    [e-mail]<mailto:[e-mail]>
        RFC 4301: Security Architecture for the Internet Protocol";
   }

   revision 2019-11-16 {
     description
       "Initial revision.";
     reference
       "RFC 8675: A YANG Data Model for Tunnel Interface Types";
   }
   ...
   identity ipsectunnelmode {
     base ift:tunnel;
     description
       "IpSec tunnel mode encapsulation.";
     reference
       "RFC 4301: Security Architecture for the Internet Protocol";
   }

The good news that it seems that IANA stores all the revisions of the iana-maintained modules. For example:

==
     revision 2023-11-27 {
       description
         "Registered RR Type RESINFO 261.";
       reference
         "https://www.iana.org/assignments/yang-parameters/iana-dns-\<https://www.iana.org/assignments/yang-parameters/iana-dns-/>
                                          [e-mail]<mailto:[e-mail]>"
     }

     revision 2023-11-08 {
       description
         "Updated description and replaced draft string reference to
          64 and 65 with RFC 9460: Service Binding and Parameter \
                                                           Specification
          via the DNS (SVCB and HTTPS Resource Records).";
       reference
         "RFC 9460: Service Binding and Parameter Specification via the
                    DNS (SVCB and HTTPS Resource Records)
          https://www.iana.org/assignments/yang-parameters/iana-dns-\<https://www.iana.org/assignments/yang-parameters/iana-dns-/>
                                          [e-mail]<mailto:[e-mail]>"
     }

     revision 2023-04-25 {
       description
         "Updated reference for 64 and 65.";
       reference
         "https://www.iana.org/assignments/yang-parameters/iana-dns-\<https://www.iana.org/assignments/yang-parameters/iana-dns-/>
                                          [e-mail]<mailto:[e-mail]>"
     }

     revision 2022-05-30 {
       description
         "Updated description, reference for 64 and 65.";
       reference
         "https://www.iana.org/assignments/yang-parameters/iana-dns-\<https://www.iana.org/assignments/yang-parameters/iana-dns-/>
                                          [e-mail]<mailto:[e-mail]>"
     }

     revision 2021-08-31 {
       description
         "Initial revision.";
       reference
         "RFC 9108: YANG Types for DNS Classes and Resource Record
                    Types";
     }

==


 In all cases, this
   event is cited from the underlying IANA registry.  If the update
   is triggered by the publication of an RFC, the reference should
   be "RFC XXXX: <titile of RFC XXXX>”. Otherwise, if the update
   is made following another IANA registration policy (Section 4
   of [RFC8126]), the reference should be "Please see this
   update’s reference details in the underlying IANA registry.”

[Med] This is more a description than a reference. If there is a ref in the authoritative reference, then the rule should be to automatically mirror it.

PS: for Section 4.30.3.2, for the “description” paragraph, be sure to replace “identities” with “enumerations“.
[Med] Done.

Hope that helps!
[Med] Definitely. Thanks.

Kent





On Mar 24, 2024, at 6:22 AM, Mahesh Jethanandani <[e-mail]<mailto:[e-mail]>> wrote:

Hi Med,

Thanks for proposing the text for revision statements in IANA modules. Kent and I discussed the PR, and believe that it could be improved further. One of us should get back to you on the updated text.

Thanks.

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.

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