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

[Kent Watsen <[e-mail]>]

Okay, we’re both right  ;)

I searched RFC 8407 for “---“ (3 dashes), as you had in your patch, and didn’t find any instances.  However, the original RFC 8407 did use “--“ (two dashes) in its Section 3.7.1 (and only in that section).  I see that you have since fixed your patch to use just two dashes, which better.  I still don’t think that it is great reading, and don’t like that it now shows in other places in rfc8407bis, but that’s a NETMOD issue... 

Enough noise on the YANG Doctors and IANA Issues lists!

K.


> On Apr 18, 2024, at 1:04 AM, [e-mail] wrote:
> 
> 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] <mailto:[e-mail]>> 
> Envoyé : jeudi 18 avril 2024 02:33
> À : 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,
>  
> 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.