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

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

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."?

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. 

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.) 

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