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

[Acee Lindem <[e-mail]>]

Sounds good to me as well.
Acee

> On Dec 6, 2023, at 01:48, Ladislav Lhotka <ladislav.lhotka=[e-mail]> wrote:
> 
> Hi Amanda,
> 
> Dne 06. 12. 23 v 3:21 Amanda Baber via RT napsal(a):
>> Hi all,
>> Sending a reminder for this one. Are there any objections to these processing instructions for IANA-maintained modules?
> 
> No objections from my side.
> 
> Best regards, Lada
> 
>>> 1.  Publish the initial version of the module as-is from the RFC.
>>> 
>>> 2.  When the module is updated the first time, change the "This
>>> version of
>>>     this YANG module..." as discussed [below].
>>> 
>>> 3.  For every module update, add a "revision" statement with a
>>>     "reference" statement that refers to the published module (e.g.,
>>>     https://www.iana.org/assignments/yang-parameters/iana-dns-class-
>>> [e-mail])
>> Please see below.
>> thanks,
>> Amanda
>> On Wed Nov 29 12:07:59 2023, [e-mail] wrote:
>>> Hi,
>>> 
>>> "Amanda Baber via RT" <[e-mail]> wrote:
>>>> Hi all,
>>>> 
>>>> First, we understand that existing revision statements in
>>>> IANA-maintained modules should be left alone.
>>>> 
>>>> A few questions:
>>>> 
>>>> 1) When we first add an entry to an IANA-maintained module, should
>>>> we,
>>>> as Martin suggested, change, e.g. "This version of this YANG module
>>>> is
>>>> part of RFC 8294; see the RFC itself for full legal notices." to
>>>> "This
>>>> original version of this YANG module is part of RFC 8294; see the RFC
>>>> itself for full legal notices."?
>>> 
>>> I think so, but I would like to hear what others have to say.
>>> 
>>> 
>>>> 
>>>> 2a) Is it agreed that if IANA registers a codepoint in a First Come
>>>> First Served or Expert Review range, and there is no associated
>>>> specification, IANA will list a URL?
>>>> 
>>>> 2b) If the registration is in the RRTYPE registry in
>>>> https://www.iana.org/assignments/dns-parameters, would that reference
>>>> be to https://www.iana.org/assignments/dns-parameters,
>>>> https://www.iana.org/assignments/iana-dns-class-rr-type [1], or for
>>>> example,
>>>> https://www.iana.org/assignments/yang-parameters/iana-dns-class-rr-
>>>> [e-mail]?
>>>> 
>>>> [1] We prefer to leave out the trailing
>>>> "/iana-dns-class-rr-type.xhtml" in case other extensions are
>>>> preferred
>>>> in the future, although the .xhtml version will continue to work.
>>> 
>>> The motivation behind the rule is to make it easy for readers of a
>>> module to find the original source of the module.  In the example
>>> above, I think that the reference to
>>> https://www.iana.org/assignments/dns-parameters should be in the
>>> module's reference statement, which it is.
>>> 
>>> So I'd say either one of
>>> https://www.iana.org/assignments/iana-dns-class-rr-type or
>>> https://www.iana.org/assignments/yang-parameters/iana-dns-class-rr-
>>> [e-mail]
>>> (see more below).
>>> 
>>> 
>>>> 
>>>> 2c) About this:
>>>> 
>>>>> When I validate this module directly with pyang, I get the errors:
>>>>> 
>>>>> $ pyang --ietf [e-mail]
>>>>> [e-mail]:35: error: RFC 8407: 4.8:
>>>>> statement
>>>>> "revision" must have a "reference" substatement
>>>> 
>>>> We were using https://yangcatalog.org/yangvalidator, which is where
>>>> we
>>>> came across the ietf-* vs. iana-* reference discrepancy. We've since
>>>> started using pyang.
>>>> 
>>>> Something I should note here is that IANA operations staff (as
>>>> opposed
>>>> to its technical staff, which includes regular and irregular IETF
>>>> participants) are not only not expert in YANG but are also,
>>>> essentially, liberal arts majors who have learned to use command line
>>>> tools and markup languages as needed. (I also have a two-year
>>>> programming degree that involved about half an hour of JSON, which is
>>>> why I get to be the delegate here.)
>>> 
>>> Ok.  So perhaps the simplest solution would be:
>>> 
>>> 1.  Publish the initial version of the module as-is from the RFC.
>>> 
>>> 2.  When the module is updated the first time, change the "This
>>> version of
>>>     this YANG module..." as discussed above.
>>> 
>>> 3.  For every module update, add a "revision" statement with a
>>>     "reference" statement that refers to the published module (e.g.,
>>>     https://www.iana.org/assignments/yang-parameters/iana-dns-class-
>>> [e-mail])
>>> 
>>> 
>>> 
>>> As an alternative, if we decide that IANA-maintained modules don't
>>> need "reference" in "revision", I can add a flag "--iana" to pyang
>>> that would implement this.  But in this case, we should probably add
>>> the URL to the IANA registry (e.g.,
>>> https://www.iana.org/assignments/iana-dns-class-rr-type) somewhere,
>>> probably in the module's "description".
>>> 
>>> 
>>> /martin
>>> 
>>> 
>>> 
>>>> 
>>>> Where RFC 8407 is concerned, we acted on the IANA Considerations
>>>> section only, and didn't recognize that (as actors on modules) we
>>>> need
>>>> to implement certain other sections of that document. We've relied on
>>>> online validation tools, as we had/have with MIB modules.
>>>> 
>>>> I think we need a tutorial before we re-approach RFC 8407 and turn
>>>> our
>>>> internal module maintenance notes into an internal manual (which if
>>>> not already necessary will certainly be so when
>>>> draft-ietf-netmod-yang-module-versioning and
>>>> draft-ietf-netmod-yang-semver arrive). Are there resources you can
>>>> recommend?
>>>> 
>>>> thanks,
>>>> Amanda
>>>> 
>>>> On Thu Nov 23 07:39:39 2023, [e-mail] wrote:
>>>>> Ladislav Lhotka <[e-mail]> wrote:
>>>>>> Dne 22. 11. 23 v 11:24 Martin Björklund napsal(a):
>>>>>>> Hi,
>>>>>>> Ladislav Lhotka <ladislav.lhotka=[e-mail]>
>>>>>>> wrote:
>>>>>>>> Hi Amanda,
>>>>>>>> 
>>>>>>>> "Amanda Baber via RT" <[e-mail]> writes:
>>>>>>>> 
>>>>>>>>> Hi,
>>>>>>>>> 
>>>>>>>>> We came across an issue when attempting to validate RFC
>>>>>>>>> 9403's
>>>>>>>>> [e-mail] module before posting.
>>>>>>>>> 
>>>>>>>>> That module refers to [e-mail], and
>>>>>>>>> pyang is
>>>>>>>>> refusing to validate it on the grounds that
>>>>>>>>> [e-mail] doesn't have references
>>>>>>>>> for
>>>>>>>>> its
>>>>>>>>> revision statements. (Which it indeed does not.)
>>>>>>>>> 
>>>>>>>>> However, if we try to validate iana-routing-types@2022-08-
>>>>>>>>> 19.yang
>>>>>>>>> directly, we don't get any errors.
>>>>>>>>> 
>>>>>>>>> Which pyang reaction is correct?
>>>>>>> When I validate this module directly with pyang, I get the
>>>>>>> errors:
>>>>>>>    $ pyang --ietf [e-mail]
>>>>>>>    [e-mail]:35: error: RFC 8407: 4.8:
>>>>>>> statement
>>>>>>>    "revision" must have a "reference" substatement
>>>>>>>    ...
>>>>>>> 
>>>>>>>> 
>>>>>>>> RFC 8407 states in sec. 4.8:
>>>>>>>> 
>>>>>>>> The "revision" statement MUST have a "reference" substatement.
>>>>>>>> 
>>>>>>>> The module description refers to RFC 8294 though, and I am not
>>>>>>>> sure
>>>>>>>> how this particular module is updated and whether there is
>>>>>>>> always
>>>>>>>> a
>>>>>>>> relevant reference available for a given revision.
>>>>>>>> 
>>>>>>>>> 
>>>>>>>>> One larger issue is that we weren't aware that we needed to
>>>>>>>>> add
>>>>>>>>> references for revision statements in the IANA-maintained
>>>>>>>>> modules. We
>>>>>>>>> have no expertise in YANG and have been relying entirely on
>>>>>>>>> validation
>>>>>>>>> tools (and on IANA Considerations sections for registry
>>>>>>>>> maintenance
>>>>>>>>> instructions in general).
>>>>>>>>> 
>>>>>>>>> Should we go back and add references to revision statements
>>>>>>>>> for
>>>>>>>>> all
>>>>>>>>> the IANA-maintained modules?
>>>>>>>> 
>>>>>>>> This could lead to problems with versioning of modules.
>>>>>>>> 
>>>>>>>>> 
>>>>>>>>> Do we need to do so only going forward?
>>>>>>>> 
>>>>>>>> I'd suggest to add reference statements to future
>>>>>>>> (substantial)
>>>>>>>> revisions of modules, perhaps even retroactively, but only
>>>>>>>> where
>>>>>>>> it
>>>>>>>> makes sense.
>>>>>>>> 
>>>>>>>>> 
>>>>>>>>> Either way, we have two questions:
>>>>>>>>> 
>>>>>>>>> 1) Many of the registries mirrored by the IANA-maintained
>>>>>>>>> modules
>>>>>>>>> have
>>>>>>>>> First Come First Served or Expert Review ranges that don't
>>>>>>>>> require
>>>>>>>>> that the applicant provide a specification. For those
>>>>>>>>> registrations,
>>>>>>>>> we list the name of a contact person in the registry's
>>>>>>>>> "Reference"
>>>>>>>>> field. In the module, would we continue to omit the reference
>>>>>>>>> field?
>>>>>>>> 
>>>>>>>> If there is no suitable document to refer to, it makes no
>>>>>>>> sense to
>>>>>>>> me
>>>>>>>> to add any stub references. RFC 8407 is IMO unnecesarily
>>>>>>>> strict
>>>>>>>> here,
>>>>>>>> and a SHOULD might suffice.
>>>>>>> The full text in RFC 8407 is:
>>>>>>>     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.
>>>>>>> In this case, there really isn't any "published document" - the
>>>>>>> module
>>>>>>> is published directly on the web.  One option could be to add
>>>>>>> the
>>>>>>> URL
>>>>>>> to the module in "reference".  The motivation for the rule is:
>>>>>> 
>>>>>> Right, but this link to the authoritative registry page belongs
>>>>>> to
>>>>>> the
>>>>>> "reference" statement that is a direct substatement of "module"
>>>>>> (see
>>>>>> e.g. [1]). The problem here is that RFC 8407 requires *every*
>>>>>> "revision" statement to contain "reference".
>>>>>> 
>>>>>> Lada
>>>>>> 
>>>>>> [1]
>>>>>> https://www.iana.org/assignments/iana-dns-class-rr-type/iana-dns-
>>>>>> class-rr-type.xhtml
>>>>> 
>>>>> In this example, the module's "reference" is
>>>>> 
>>>>> https://www.iana.org/assignments/dns-parameters
>>>>> 
>>>>> 
>>>>> 
>>>>> I was thinking the revision's "reference" could be
>>>>> 
>>>>> https://www.iana.org/assignments/iana-dns-class-rr-type/iana-dns-
>>>>> class-rr-type.xhtml
>>>>> 
>>>>> or even
>>>>> 
>>>>> https://www.iana.org/assignments/yang-parameters/iana-dns-class-rr-
>>>>> [e-mail]
>>>>> 
>>>>> 
>>>>> 
>>>>> /martin
>>>>> 
>>>>> 
>>>>> 
>>>>>> 
>>>>>>> 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.
>>>>>>> So the URL would help for this.
>>>>>>> Side note.  In the description of the module it says:
>>>>>>>   This version of this YANG module is part of RFC 8294; see
>>>>>>>   the RFC itself for full legal notices.";
>>>>>>> This isn't true... Should IANA change the description of the
>>>>>>> module
>>>>>>> when it updates the module?  Perhaps to:
>>>>>>>   This original version of this YANG module is part of RFC
>>>>>>> 8294;
>>>>>>> see
>>>>>>>   the RFC itself for full legal notices.";
>>>>>>> /martin
>>>>>>> 
>>>>>>>> 
>>>>>>>>> 
>>>>>>>>> 2) When we need to correct an IANA-maintained module, in the
>>>>>>>>> absence
>>>>>>>>> of a document to refer to, what can we do to make the
>>>>>>>>> revision
>>>>>>>>> statement valid?
>>>>>>>> 
>>>>>>>> I'd say yes.
>>>>>>>> 
>>>>>>>> Best regards, Lada
>>>>>>>> 
>>>>>>>>> 
>>>>>>>>> Best regards,
>>>>>>>>> 
>>>>>>>>> Amanda Baber
>>>>>>>>> IANA Operations Manager
>>>>>>>>> 
>>>>>>>>> _______________________________________________
>>>>>>>>> yang-doctors mailing list
>>>>>>>>> [e-mail]
>>>>>>>>> https://www.ietf.org/mailman/listinfo/yang-doctors
>>>>>>>> 
>>>>>>>> --
>>>>>>>> Ladislav Lhotka, CZ.NIC
>>>>>>>> PGP Key ID: 0xB8F92B08A9F76C67
>>>>>>>> 
>>>>>>>> _______________________________________________
>>>>>>>> yang-doctors mailing list
>>>>>>>> [e-mail]
>>>>>>>> https://www.ietf.org/mailman/listinfo/yang-doctors
>>>>>> 
>>>>>> --
>>>>>> Ladislav Lhotka, CZ.NIC
>>>>>> PGP Key ID: 0xB8F92B08A9F76C67
>>>> 
>>>> _______________________________________________
>>>> yang-doctors mailing list
>>>> [e-mail]
>>>> https://www.ietf.org/mailman/listinfo/yang-doctors
>> _______________________________________________
>> yang-doctors mailing list
>> [e-mail]
>> https://www.ietf.org/mailman/listinfo/yang-doctors
> 
> -- 
> Ladislav Lhotka, CZ.NIC
> PGP Key ID: 0xB8F92B08A9F76C67
> 
> _______________________________________________
> yang-doctors mailing list
> [e-mail]
> https://www.ietf.org/mailman/listinfo/yang-doctors