Re: [netmod] New guidelines for IANA in draft-ietf-netmod-rfc8407bis
Martin Björklund writes: > 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) I think it would be sufficient to have SHOULD instead of MUST here. Other cases apart from IANA modules may arise where it makes no sense to attach reference to every single revision. And adding dummy references just to satisfy tools is actually harmful. On the other hand, I assume YANG doctors would object if a reference isn't provided where it is appropriate and no sound reason is given. Lada > > 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://www.iana.org/assignments/yang-parameters/iana-dns-class-rr-t...@2023-11-08.yang, > 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://www.iana.org/assignments/yang-parameters/iana-dns-class-rr-t...@2023-11-08.yang). > > 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., > https://www.iana.org/assignments/yang-parameters/iana-...@2023-11-08.yang) > > > > > Further, some IANA modules use the IETF template for the module's > "description", see e.g., > https://www.iana.org/assignments/yang-parameters/iana-routing-ty...@2022-08-19.yang. > 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. > > > > /martin > > ___ > netmod mailing list > netmod@ietf.org > https://www.ietf.org/mailman/listinfo/netmod -- Ladislav Lhotka, CZ.NIC PGP Key ID: 0xB8F92B08A9F76C67 ___ netmod mailing list netmod@ietf.org https://www.ietf.org/mailman/listinfo/netmod
Re: [netmod] New guidelines for IANA in draft-ietf-netmod-rfc8407bis
Hi,
mohamed.boucad...@orange.com wrote:
> Hi Martin,
>
> Thanks for raising these points.
>
> Please see inline.
>
> Cheers,
> Med
>
> > -Message d'origine-
> > De : netmod De la part de Martin Björklund
> > Envoyé : jeudi 7 décembre 2023 17:05
> > À : netmod@ietf.org
> > 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=05%7C01%7Cmohamed.boucadair%40orange.com%7Ccf5ad65dd26d4a
> > e3a1f508dbf73e4f79%7C90c7a20af34b40bfbc48b9253b6f5d20%7C0%7C0%7C638375
> > 619746432780%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luM
> > zIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C2000%7C%7C%7C=X6s86KFMCkdu03
> > Z6hne6g16fU405pTiLPhv5gZYZV4k%3D=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=05%7C01%7Cmohamed.boucadair%40orange.com%7Ccf5ad65dd26d4a
> > e3a1f508dbf73e4f79%7C90c7a20af34b40bfbc48b9253b6f5d20%7C0%7C0%7C638375
> > 619746432780%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luM
> > zIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C2000%7C%7C%7C=X6s86KFMCkdu03
> > Z6hne6g16fU405pTiLPhv5gZYZV4k%3D=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/assignm
Re: [netmod] New guidelines for IANA in draft-ietf-netmod-rfc8407bis
Hi Martin, Thanks for raising these points. Please see inline. Cheers, Med > -Message d'origine- > De : netmod De la part de Martin Björklund > Envoyé : jeudi 7 décembre 2023 17:05 > À : netmod@ietf.org > 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=05%7C01%7Cmohamed.boucadair%40orange.com%7Ccf5ad65dd26d4a > e3a1f508dbf73e4f79%7C90c7a20af34b40bfbc48b9253b6f5d20%7C0%7C0%7C638375 > 619746432780%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luM > zIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C2000%7C%7C%7C=X6s86KFMCkdu03 > Z6hne6g16fU405pTiLPhv5gZYZV4k%3D=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=05%7C01%7Cmohamed.boucadair%40orange.com%7Ccf5ad65dd26d4a > e3a1f508dbf73e4f79%7C90c7a20af34b40bfbc48b9253b6f5d20%7C0%7C0%7C638375 > 619746432780%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luM > zIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C2000%7C%7C%7C=X6s86KFMCkdu03 > Z6hne6g16fU405pTiLPhv5gZYZV4k%3D=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. 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
[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://www.iana.org/assignments/yang-parameters/iana-dns-class-rr-t...@2023-11-08.yang, 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://www.iana.org/assignments/yang-parameters/iana-dns-class-rr-t...@2023-11-08.yang). 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., https://www.iana.org/assignments/yang-parameters/iana-...@2023-11-08.yang) Further, some IANA modules use the IETF template for the module's "description", see e.g., https://www.iana.org/assignments/yang-parameters/iana-routing-ty...@2022-08-19.yang. 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. /martin ___ netmod mailing list netmod@ietf.org https://www.ietf.org/mailman/listinfo/netmod
