Re: [netmod] New guidelines for IANA in draft-ietf-netmod-rfc8407bis

[Martin Björklund <[e-mail]>]

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.
> > iana.org%2Fassignments%2Fyang-parameters%2Fiana-dns-class-rr-
> > type%402023-11-
> > 08.yang&data=05%7C01%7Cmohamed.boucadair%40orange.com%7Ccf5ad65dd26d4a
> > e3a1f508dbf73e4f79%7C90c7a20af34b40bfbc48b9253b6f5d20%7C0%7C0%7C638375
> > 619746432780%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luM
> > zIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C2000%7C%7C%7C&sdata=X6s86KFMCkdu03
> > 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.
> > iana.org%2Fassignments%2Fyang-parameters%2Fiana-dns-class-rr-
> > type%402023-11-
> > 08.yang&data=05%7C01%7Cmohamed.boucadair%40orange.com%7Ccf5ad65dd26d4a
> > e3a1f508dbf73e4f79%7C90c7a20af34b40bfbc48b9253b6f5d20%7C0%7C0%7C638375
> > 619746432780%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luM
> > zIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C2000%7C%7C%7C&sdata=X6s86KFMCkdu03
> > 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://github.com/boucadair/rfc8407bis/pull/31/files) 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://www.iana.org/assignments/iana-foo/iana-foo.xhtml

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://www.iana.org/assignments/iana-foo/iana-foo.xhtml";
  }
  revision 2022-04-01 {
    reference
      "https://www.iana.org/assignments/iana-foo/iana-foo.xhtml";
  }
  revision 2020-04-01 {
    reference
      "https://www.iana.org/assignments/iana-foo/iana-foo.xhtml";
  }

The proposal was to use the url to the module itself:

  revision 2023-04-01 {
    reference
      "https://www.iana.org/assignments/yang-parameters/[e-mail]";
  }
  revision 2022-04-01 {
    reference
      "https://www.iana.org/assignments/yang-parameters/[e-mail]";
  }
  revision 2020-04-01 {
    reference
      "https://www.iana.org/assignments/yang-parameters/[e-mail]";
  }


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://github.com/boucadair/rfc8407bis/pull/32/files

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