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

[Amanda Baber via RT <[e-mail]>]

Thanks, all. We've updated our internal documentation.

Amanda

On Wed Dec 06 15:40:42 2023, [e-mail] wrote:
> Not from my side. Thanks
> 
> Mahesh Jethanandani
> [e-mail]
> 
> > On Dec 5, 2023, at 6:22 PM, Amanda Baber via RT <iana-
> > [e-mail]> wrote:
> >
> > Hi all,
> >
> > Sending a reminder for this one. Are there any objections to these
> > processing instructions for IANA-maintained modules?
> >
> >> 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