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

[Martin Björklund <[e-mail]>]

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/[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/[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/[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 [e-mail]
> > > >>> 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