[netmod] iana-template RE: New guidelines for IANA in draft-ietf-netmod-rfc8407bis

[[e-mail]]

Hi Martin, 

> Ok.  Perhaps we should include an explicit template for IANA-
> maintained modules in an appendix, just like we do with IETF-modules
> in appendix B?

Let's see if we can agree on a template. Feel free to review:

==
module iana-template {
  yang-version 1.1;

  // replace this string with a unique namespace URN value

  namespace "urn:ietf:params:xml:ns:yang:iana-template";

  // replace with the assigned prefix

  prefix iana-foo;

  organization
    "Internet Assigned Numbers Authority (IANA)";

  contact
    "Internet Assigned Numbers Authority

     ICANN
     12025 Waterfront Drive, Suite 300
     Los Angeles, CA 90094

     Tel: [phone]

     <mailto:[e-mail]>";

  description
    "This module defines a template for IANA-maintained modules.

     Copyright (c) <insert year> IETF Trust and the persons 
     identified as authors of the code.  All rights reserved.

     Redistribution and use in source and binary forms, with or
     without modification, is permitted pursuant to, and subject to
     the license terms contained in, the Simplified BSD License set
     forth in Section 4.c of the IETF Trust's Legal Provisions
     Relating to IETF Documents
     (https://trustee.ietf.org/license-info).

     The initial version of this YANG module is part of RFC IIII; see 
     the RFC itself for full legal notices.

  // RFC Ed.: replace IIII with actual RFC number and remove
  // this note

  // If a script is used, complete with the script information

     This version of this YANG module was generated from the
     corresponding IANA registry using an <script-info>.

  // RFC Ed.: replace the URL and remove this note

     The latest version of this YANG module is available at
     <URL>.";

  // replace with the registry name and the URL of the IANA registry

  reference
    "Registry Name (URL)";


  // replace 'date-revision' with the module publication date
  // the format is (year-month-day)

  revision date-revision {
    description
      "Indicates the list of changes";
    reference
      "URL of the latest version of the module";
  }

  // replace 'date-initial' with the module publication date
  // the format is (year-month-day)

  revision date-initial {
    description
      "Initial version";
    reference
      "URL of the published initial version of the module
       RFC IIII: RFC Title";

  // RFC Ed.: Update with the RFC number and title 
  // of the RFC that defined the initial version of
  // the module and remove this not
  }

  // identity statements
  // typedef statements
} 
==

Cheers,
Med

[1]: https://github.com/boucadair/rfc8407bis/blob/main/templates/iana-template.yang

> -----Message d'origine-----
> De : Martin Björklund <[e-mail]>
> Envoyé : vendredi 8 décembre 2023 09:07
> À : BOUCADAIR Mohamed INNOV/NET <[e-mail]>
> Cc : [e-mail]
> Objet : Re: [netmod] New guidelines for IANA in draft-ietf-netmod-
> rfc8407bis
> 
> Hi,
> 
> [e-mail] wrote:
> > Hi Martin,
> >
> > Thanks for raising these points.
> >
> > Please see inline.
> >
> > Cheers,
> > Med
> >
> > > -----Message d'origine-----
> > > De : netmod <[e-mail]> De la part de Martin
> Björklund
> > > Envoyé : jeudi 7 décembre 2023 17:05 À : [e-mail] Objet :
> > > [netmod] New guidelines for IANA in draft-ietf-netmod- rfc8407bis
> > >
> > > Hi,
> > >
> > > There has been some discussion with IANA on the YANG doctors list
> > > regarding this text in section 4.8 in RFC 8407:
> > >
> > >    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.
> > >
> > > (the same text is present in rfc8407bis)
> > >
> > > It continues with the motivation behind the rule:
> > >
> > >    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.
> > >
> > > As can be seen in e.g.,
> > >
> https://eur03.safelinks.protection.outlook.com/?url=https%3A%2F%2Fwww%
> 2F&data=05%7C01%7Cmohamed.boucadair%40orange.com%7C8778e705b2e34e99790
> 808dbf7c4c75c%7C90c7a20af34b40bfbc48b9253b6f5d20%7C0%7C0%7C63837619675
> 3722174%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLC
> JBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=Fxf8A2Rg8DoawhFAJqe
> xoKe%2BReEruxK23PK1BYY5UAQ%3D&reserved=0.
> > > iana.org%2Fassignments%2Fyang-parameters%2Fiana-dns-class-rr-
> > > type%402023-11-
> > >
> 08.yang&data=05%7C01%7Cmohamed.boucadair%40orange.com%7Ccf5ad65dd26d
> > > 4a
> > >
> e3a1f508dbf73e4f79%7C90c7a20af34b40bfbc48b9253b6f5d20%7C0%7C0%7C6383
> > > 75
> > >
> 619746432780%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2l
> > > uM
> > >
> zIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C2000%7C%7C%7C&sdata=X6s86KFMCkdu
> > > 03 Z6hne6g16fU405pTiLPhv5gZYZV4k%3D&reserved=0,
> > > this rule has not been followed.
> > >
> > > The discussion ended with the recommendation to IANA to always add
> a
> > > "reference" statement that refers to the published module (e.g.,
> > >
> https://eur03.safelinks.protection.outlook.com/?url=https%3A%2F%2Fwww%
> 2F&data=05%7C01%7Cmohamed.boucadair%40orange.com%7C8778e705b2e34e99790
> 808dbf7c4c75c%7C90c7a20af34b40bfbc48b9253b6f5d20%7C0%7C0%7C63837619675
> 3722174%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLC
> JBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=Fxf8A2Rg8DoawhFAJqe
> xoKe%2BReEruxK23PK1BYY5UAQ%3D&reserved=0.
> > > iana.org%2Fassignments%2Fyang-parameters%2Fiana-dns-class-rr-
> > > type%402023-11-
> > >
> 08.yang&data=05%7C01%7Cmohamed.boucadair%40orange.com%7Ccf5ad65dd26d
> > > 4a
> > >
> e3a1f508dbf73e4f79%7C90c7a20af34b40bfbc48b9253b6f5d20%7C0%7C0%7C6383
> > > 75
> > >
> 619746432780%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2l
> > > uM
> > >
> zIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C2000%7C%7C%7C&sdata=X6s86KFMCkdu
> > > 03 Z6hne6g16fU405pTiLPhv5gZYZV4k%3D&reserved=0).
> > >
> > > If people agree that this is the correct solution, I think we
> should
> > > update 8407bis with this.
> > >
> > > Specifically, I suggest to change 4.30.3.1 and 4.30.3.2:
> > >
> > > OLD:
> > >
> > > 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.
> > >
> > > NEW:
> > >
> > > 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.  The "revision" statement must have
> a
> > > "reference" substatement that to the published module (e.g.,
> > >  ...)
> > >
> > >
> >
> > [Med] Looks reasonable to me. As you can see in the proposed PR
> (https://eur03.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgit
> hub.com%2Fboucadair%2Frfc8407bis%2Fpull%2F31%2Ffiles&data=05%7C01%7Cmo
> hamed.boucadair%40orange.com%7C8778e705b2e34e99790808dbf7c4c75c%7C90c7
> a20af34b40bfbc48b9253b6f5d20%7C0%7C0%7C638376196753878412%7CUnknown%7C
> TWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVC
> I6Mn0%3D%7C3000%7C%7C%7C&sdata=C14SqlE34qDH8wVo9rB271oY%2FqO80sSfBk1oi
> XCMjBI%3D&reserved=0) I went with a slightly modified wording because
> we do already have the following to refer to the link to be used:
> >
> >    Examples of IANA URLs from where to retrieve the latest version
> of an
> >    IANA-maintained module are: [IANA_BGP-L2_URL], [IANA_PW-
> Types_URL],
> >    and [IANA_BFD_URL].  [IANA_FOO_URL] is used in the following to
> refer
> >    to such URLs.  These URLs are expected to be sufficiently
> permanent
> >    and stable.
> 
> I cannot find the reference [IANA_FOO_URL].  If we assume that it is
> similar to [IANA_PW-Types_URL], it would be:
> 
> 
> https://eur03.safelinks.protection.outlook.com/?url=https%3A%2F%2Fwww.
> iana.org%2Fassignments%2Fiana-foo%2Fiana-
> foo.xhtml&data=05%7C01%7Cmohamed.boucadair%40orange.com%7C8778e705b2e3
> 4e99790808dbf7c4c75c%7C90c7a20af34b40bfbc48b9253b6f5d20%7C0%7C0%7C6383
> 76196753878412%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2l
> uMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=LautcTkhE%2B
> UMJ2V2iNkebAF5rUKyu2Y%2Btu8ys%2F01HjI%3D&reserved=0
> 
> This points to the "meta" page for the module, which has a pointer to
> the latest version of the YANG module.
> 
> I don't think it makes sense to put this URL in the "reference"
> statement in each revision, b/c it would be:
> 
>   revision 2023-04-01 {
>     reference
> 
> "https://eur03.safelinks.protection.outlook.com/?url=https%3A%2F%2Fwww
> .iana.org%2Fassignments%2Fiana-foo%2Fiana-
> foo.xhtml&data=05%7C01%7Cmohamed.boucadair%40orange.com%7C8778e705b2e3
> 4e99790808dbf7c4c75c%7C90c7a20af34b40bfbc48b9253b6f5d20%7C0%7C0%7C6383
> 76196753878412%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2l
> uMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=LautcTkhE%2B
> UMJ2V2iNkebAF5rUKyu2Y%2Btu8ys%2F01HjI%3D&reserved=0";
>   }
>   revision 2022-04-01 {
>     reference
> 
> "https://eur03.safelinks.protection.outlook.com/?url=https%3A%2F%2Fwww
> .iana.org%2Fassignments%2Fiana-foo%2Fiana-
> foo.xhtml&data=05%7C01%7Cmohamed.boucadair%40orange.com%7C8778e705b2e3
> 4e99790808dbf7c4c75c%7C90c7a20af34b40bfbc48b9253b6f5d20%7C0%7C0%7C6383
> 76196753878412%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2l
> uMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=LautcTkhE%2B
> UMJ2V2iNkebAF5rUKyu2Y%2Btu8ys%2F01HjI%3D&reserved=0";
>   }
>   revision 2020-04-01 {
>     reference
> 
> "https://eur03.safelinks.protection.outlook.com/?url=https%3A%2F%2Fwww
> .iana.org%2Fassignments%2Fiana-foo%2Fiana-
> foo.xhtml&data=05%7C01%7Cmohamed.boucadair%40orange.com%7C8778e705b2e3
> 4e99790808dbf7c4c75c%7C90c7a20af34b40bfbc48b9253b6f5d20%7C0%7C0%7C6383
> 76196753878412%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2l
> uMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=LautcTkhE%2B
> UMJ2V2iNkebAF5rUKyu2Y%2Btu8ys%2F01HjI%3D&reserved=0";
>   }
> 
> The proposal was to use the url to the module itself:
> 
>   revision 2023-04-01 {
>     reference
> 
> "https://eur03.safelinks.protection.outlook.com/?url=https%3A%2F%2Fwww
> .iana.org%2Fassignments%2Fyang-parameters%2Fiana-foo%402023-04-
> 01.yang&data=05%7C01%7Cmohamed.boucadair%40orange.com%7C8778e705b2e34e
> 99790808dbf7c4c75c%7C90c7a20af34b40bfbc48b9253b6f5d20%7C0%7C0%7C638376
> 196753878412%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luM
> zIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=D1zmBaf6eFt0A7
> NwI30vPkuu1OAee%2BXiG28ywkb1yJw%3D&reserved=0";
>   }
>   revision 2022-04-01 {
>     reference
> 
> "https://eur03.safelinks.protection.outlook.com/?url=https%3A%2F%2Fwww
> .iana.org%2Fassignments%2Fyang-parameters%2Fiana-foo%402022-04-
> 01.yang&data=05%7C01%7Cmohamed.boucadair%40orange.com%7C8778e705b2e34e
> 99790808dbf7c4c75c%7C90c7a20af34b40bfbc48b9253b6f5d20%7C0%7C0%7C638376
> 196753878412%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luM
> zIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=NbP00VMflUnqSj
> %2BVhKRinwU07qBOWq%2BosbMxTSaaJkA%3D&reserved=0";
>   }
>   revision 2020-04-01 {
>     reference
> 
> "https://eur03.safelinks.protection.outlook.com/?url=https%3A%2F%2Fwww
> .iana.org%2Fassignments%2Fyang-parameters%2Fiana-foo%402020-04-
> 01.yang&data=05%7C01%7Cmohamed.boucadair%40orange.com%7C8778e705b2e34e
> 99790808dbf7c4c75c%7C90c7a20af34b40bfbc48b9253b6f5d20%7C0%7C0%7C638376
> 196753878412%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luM
> zIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=gploWqV0nCAPLi
> fGYwzZGkvlUU1DhI%2BA9aVlLGppig8%3D&reserved=0";
>   }
> 
> 
> However, it would be useful to have the "meta" URL somewhere in the
> document; in the "description" of the module, or "reference".
> 
> 
> 
> 
> >
> > The change is consistent with this part of the bis:
> >
> >    If an IANA-maintained module is imported by another module, a
> >    normative reference with the IANA URL from where to retrieve the
> >    IANA-maintained module SHOULD be included.  Although not
> encouraged,
> >    referencing the RFC that defines the initial version of the IANA
> >    module is acceptable in specific cases (e.g., the imported
> version is
> >    specifically the initial version, ...
> >
> > >
> > >
> > > Further, some IANA modules use the IETF template for the module's
> > > "description", see e.g.,
> > >
> > > That module has in its "description":
> > >
> > >      This version of this YANG module is part of RFC 8294; see
> > >      the RFC itself for full legal notices.";
> > >
> > > But that is not correct.  Other module use this instead:
> > >
> > >      The initial version of this YANG module is part of RFC 7224;
> > >      see the RFC itself for full legal notices.";
> > >
> > > I think 8407bis should recommend that IANA-maintained modules use
> > > this wording instead.
> > >
> >
> > [Med] Good point. Made this change so far:
> >
> > OLD:
> >    For both cases, the document that defines an IANA-maintained
> module
> >    MUST include a note indicating that the document is only
> documenting
> >    the initial version of the module and that the authoritative
> version
> >    is to be retrieved from the IANA registry.
> >
> > NEW:
> >    For both cases, the document that defines an IANA-maintained
> module
> >    MUST include a note indicating that the document is only
> documenting
> >    the initial version of the module and that the authoritative
> version
> >    is to be retrieved from the IANA registry. Also, the IANA-
> maintained
> >    module MUST include the following note indicating the RFC that
> >    registered the initial version of the IANA- maintained module:
> >
> >       The initial version of this YANG module is part of RFC IIII;
> >       see the RFC itself for full legal notices.
> >
> > The full change can be see here:
> >
> https://eur03.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgith
> >
> ub.com%2Fboucadair%2Frfc8407bis%2Fpull%2F32%2Ffiles&data=05%7C01%7Cmoh
> >
> amed.boucadair%40orange.com%7C8778e705b2e34e99790808dbf7c4c75c%7C90c7a
> >
> 20af34b40bfbc48b9253b6f5d20%7C0%7C0%7C638376196753878412%7CUnknown%7CT
> >
> WFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI
> >
> 6Mn0%3D%7C3000%7C%7C%7C&sdata=GtsRvNaOfBWj21RhsZnG72MpKR9i53FgBw8Q3MCZ
> > mqg%3D&reserved=0
> 
> Ok.  Perhaps we should include an explicit template for IANA-
> maintained modules in an appendix, just like we do with IETF-modules
> in appendix B?
> 
> 
> /martin
____________________________________________________________________________________________________________
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.