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

[Ladislav Lhotka <[e-mail]>]

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