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

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

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