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

[tom petch <[e-mail]>]

From: netmod <[e-mail]> on behalf of Ladislav Lhotka <ladislav.lhotka=[e-mail]>
Sent: 08 December 2023 12:48

Martin Björklund <[e-mail]> 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.

<tp>

This thread reminds me of a curiosity I have seen a number of times where the structure of a YANG module is

 module
   ...
   description
    "...
   reference
   " RFC xxxx"
   revision
     description
     reference
....
I see it in e.g. draft-ietf-i s is-yang
but in other I-D too and wonder what the first reference clause is up to.

Tom Petch

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/[e-mail],
> 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/[e-mail]).
>
> 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/[e-mail])
>
>
>
>
> Further, some IANA modules use the IETF template for the module's
> "description", see e.g.,
> https://www.iana.org/assignments/yang-parameters/[e-mail].
> 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
> [e-mail]
> https://www.ietf.org/mailman/listinfo/netmod

--
Ladislav Lhotka, CZ.NIC
PGP Key ID: 0xB8F92B08A9F76C67

_______________________________________________
netmod mailing list
[e-mail]
https://www.ietf.org/mailman/listinfo/netmod