Subject: [netmod] Proposed IANA text for YANG Module Versioning and Semver Drafts

From: "Rob Wilton (rwilton)" <[email-masked]>
Date: Wed, 3 Mar 2021 11:07:28 +0000

Hi,

// As an individual contributor

We discussed proposed IANA text at the last NETMOD interim on the YANG versioning work.  Tracked by issue https://github.com/netmod-wg/yang-ver-dt/issues/59

I had the action of updating the text based on comments received in the interim meeting and then sending that text to the list.

The proposed text is below (that is in the current published versions of both drafts).  If the WG has no objections to this text, then the planned next step is to ask IANA for an early review of this text.

IANA section in draft-ietf-netmod-yang-module-versioning-02:

11.2.  Guidance for versioning in IANA maintained YANG modules

   Note for IANA (to be removed by the RFC editor): Please check that
   the registries and IANA YANG modules are referenced in the
   appropriate way.

   IANA is responsible for maintaining and versioning YANG modules that
   are derived from other IANA registries.  For example, "iana-if-
   type.yang" [IfTypeYang] is derived from the "Interface Types (ifType)
   IANA registry" [IfTypesReg], and "iana-routing-types.yang"
   [RoutingTypesYang] is derived from the "Address Family Numbers"
   [AddrFamilyReg] and "Subsequent Address Family Identifiers (SAFI)
   Parameters" [SAFIReg] IANA registries.

   Normally, updates to the registries cause any derived YANG modules to
   be updated in a backwards-compatible way, but there are some cases
   where the registry updates can cause non-backward-compatible updates
   to the derived YANG module.  An example of such an update is the
   2020-12-31 revision of iana-routing-types.yang

   [RoutingTypesDecRevision], where the enum name for two SAFI values
   was changed.

   In all cases, IANA MUST follow the versioning guidance specified in
   Section 3.1, and MUST include a "rev:nbc-changes" substatement to the
   latest revision statement whenever an IANA maintained module is
   updated in a non-backwards-compatible way, as described in
   Section 3.2.

   Note: For published IANA maintained YANG modules that contain non-
   backwards-compatible changes between revisions, a new revision should
   be published with the "rev:nbc-changes" substatement retrospectively
   added to any revisions containing non-backwards-compatible changes.

   Non normative examples of updates to enumeration types in IANA
   maintained modules that would be classified as non-backwards-
   compatible changes are: Changing the status of an enumeration typedef
   to obsolete, changing the status of an enum entry to obsolete,
   removing an enum entry, changing the identifier of an enum entry, or
   changing the described meaning of an enum entry.

   Non normative examples of updates to enumeration types in IANA
   maintained modules that would be classified as backwards-compatible
   changes are: Adding a new enum entry to the end of the enumeration,
   changing the status or an enum entry to deprecated, or improving the
   description of an enumeration that does not change its defined
   meaning.

   Non normative examples of updates to identity types in IANA
   maintained modules that would be classified as non-backwards-
   compatible changes are: Changing the status of an identity to
   obsolete, removing an identity, renaming an identity, or changing the
   described meaning of an identity.

   Non normative examples of updates to identity types in IANA
   maintained modules that would be classified as backwards-compatible
   changes are: Adding a new identity, changing the status or an
   identity to deprecated, or improving the description of an identity
   that does not change its defined meaning.

IANA section for draft-ietf-netmod-yang-semver-02

9.2.  Guidance for YANG Semver in IANA maintained YANG modules

   Note for IANA (to be removed by the RFC editor): Please check that
   the registries and IANA YANG modules are referenced in the
   appropriate way.

   IANA is responsible for maintaining and versioning some YANG modules,
   e.g., iana-if-types.yang [IfTypeYang] and iana-routing-types.yang
   [RoutingTypesYang] .

   In addition to following the rules specified in the IANA
   Considerations section of [I-D.ietf-netmod-yang-module-versioning] ,
   IANA maintained YANG modules MUST also include a YANG Semver revision
   label for all new revisions, as defined in Section 3 .

   The YANG Semver version associated with the new revision MUST follow
   the rules defined in Section 3.3 .

   Note: For IANA maintained YANG modules that have already been
   published, revision labels MUST be retrospectively applied to all
   existing revisions when the next new revision is created, starting at
   version "1.0.0" for the initial published revision, and then
   incrementing according to the YANG Semver version rules specified in
   Section 3.3 .

   Most changes to IANA maintained YANG modules are expected to be
   backwards-compatible changes and classified as MINOR version changes.
   The PATCH version may be incremented instead when only editorial
   changes are made, and the MAJOR version would be incremented if non-
   backwards-compatible major changes are made.

   Given that IANA maintained YANG modules are versioned with a linear
   history, it is anticipated that it should not be necessary to use the
   "_compatible" or "_non_compatible" modifiers to the "Z_COMPAT"
   version element.

Comments welcome.

Thanks,
Rob

---

From: Ladislav Lhotka <[email-masked]>
Date: Wed, 03 Mar 2021 13:19:06 +0100

Hi Rob,

I don't know whether this has been discussed, but one issue that might need to be addressed is the difference between IANA and YANG in the definitions of "obsolete" and "deprecated" - the details are here (slide 5):

https://datatracker.ietf.org/meeting/104/materials/slides-104-dnsop-sessa-yang-types-for-dns-classes-and-resource-record-types-00

The best solution would be to unify the definitions. If this is not possible (in a short term), then it is IMO necessary to mark an entry that is made obsolete or deprecated in an IANA registry as "obsolete" in the YANG module.

Lada

"Rob Wilton \(rwilton\)" <rwilton=[email-masked]> writes:

> _______________________________________________
> netmod mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/netmod

-- 
Ladislav Lhotka
Head, CZ.NIC Labs
PGP Key ID: 0xB8F92B08A9F76C67

---

From: "Rob Wilton (rwilton)" <[email-masked]>
Date: Fri, 5 Mar 2021 12:23:24 +0000

Hi Lada,

Thanks for the feedback.  I agree that we should think about this.

Looking at those slides, it also asks the question as to whether a YANG file derived from an IANA registry entry should ever differ.  I agree with the answer proposed in those slides: I.e., the two should always be kept in sync, even if that ends causing a non-backwards-compatible change to the YANG module.

But my question is whether we should add any text to the IANA section of this document to make this explicit?

Regarding your second issue:

I agree that unifying the definitions between IANA and YANG would be ideal, but I'm not sure whether that will be feasible in the short term.

draft-ietf-netmod-yang-module-versioning-02 tries to encourage stricter YANG definitions of deprecated and obsolete (both in the rules defining what is backwards compatible, and also new YANG library leaves to advertise that the server conforms to the stricter behaviour):

I.e., the behaviour that it is trying to encourage is:
 -  deprecated nodes must be implemented (just like status current nodes), or otherwise explicitly deviated if they are not supported.
 -  obsolete nodes must not be implemented.

The reason that stricter semantics are proposed is so that the client can know the exact schema supported by the server rather than having to guess whether or not deprecated or obsolete nodes are implemented.

I read the IANA definition of deprecated as being "SHOULD NOT implement", and YANG doesn't today have a status value that maps well to.  In particular, YANG doesn't currently have a way to express to a client that a deprecated node that "should not be implemented" actually is still implemented by a server.  E.g., the reverse semantics of "deviate not-supported".

Hence, I wonder YANG shouldn't end up with 4 levels of status (better name required for 'really-deprecated'):

 (1) "current":           Current.  Must implement or deviate not-supported
 (2) "deprecated":        Going away. Should implement, but may deviate not-supported
 (3) "really-deprecated": Really going away.  Should not implement, but may deviate to indicate it is still supported.
 (4) "obsolete":          Dead.  Must not implement.  Cannot deviate.

Note, that a separate status "experimental" has been proposed previously as an addition for YANG Next, tracked by https://github.com/netmod-wg/yang-next/issues/59

The IANA version of "deprecated" would map to (3) "really-deprecated" in YANG, whilst the IANA definition of "obsolete" matches the YANG definition of "obsolete".

But this can't really be solved until we have a new revision of YANG.

Rob

> -----Original Message-----
> From: netmod <[email-masked]> On Behalf Of Ladislav Lhotka
> Sent: 03 March 2021 12:19
> To: Rob Wilton (rwilton) <rwilton=[email-masked]>;
> [email-masked]
> Subject: Re: [netmod] Proposed IANA text for YANG Module Versioning and
> Semver Drafts
> 
> Hi Rob,
> 
> I don't know whether this has been discussed, but one issue that might
> need to be addressed is the difference between IANA and YANG in the
> definitions of "obsolete" and "deprecated" - the details are here (slide
> 5):
> 
> https://datatracker.ietf.org/meeting/104/materials/slides-104-dnsop-sessa-
> yang-types-for-dns-classes-and-resource-record-types-00
> 
> The best solution would be to unify the definitions. If this is not
> possible (in a short term), then it is IMO necessary to mark an entry that
> is made obsolete or deprecated in an IANA registry as "obsolete" in the
> YANG module.
> 
> Lada
> 
> > We discussed proposed IANA text at the last NETMOD interim on the YANG
> versioning work.  Tracked by issue https://github.com/netmod-wg/yang-ver-
> dt/issues/59
> >
> > I had the action of updating the text based on comments received in the
> interim meeting and then sending that text to the list.
> >
> > The proposed text is below (that is in the current published versions of
> both drafts).  If the WG has no objections to this text, then the planned
> next step is to ask IANA for an early review of this text.
> >
> >

---

From: Ladislav Lhotka <[email-masked]>
Date: Fri, 05 Mar 2021 15:11:53 +0100

> Looking at those slides, it also asks the question as to whether a YANG file derived from an IANA registry entry should ever differ.  I agree with the answer proposed in those slides: I.e., the two…

This was actually a reaction to some voices in the DNSOP WG that went like "IANA registries are broken, why don't we abandon them and keep doing the right thing just in the YANG modules?"

> But my question is whether we should add any text to the IANA section of this document to make this explicit?

Yes, I think so. The update rules of sec. 11 in RFC 7950 don't work well with these modules.  

In fact, an ideal outcome would be that no instructions to IANA need to be given, i.e. the correct YANG module could be generated automatically from the registry. The approach via XSLT adopted in

https://tools.ietf.org/html/draft-ietf-dnsop-iana-class-type-yang-02

comes pretty close, at least for the DNS Parameters registry. I think that the rules for "rev:..." backward compatibility statements could also be implemented this way.

>  (4) "obsolete":          Dead.  Must not implement.  Cannot deviate.

Perhaps the first three could be sufficient. It somebody feels the need to implement something in the category (4), they would do it anyway, and it is then better to indicate it via deviation.

As I understand it, "obsolete" in the IANA sense is a mere statement of the fact that nobody uses that item any more.

> Note, that a separate status "experimental" has been proposed previously as an addition for YANG Next, tracked by https://github.com/netmod-wg/yang-next/issues/59

Yes, this is something that also frequently appears in IANA registries.

Lada

---

From: tom petch <[email-masked]>
Date: Mon, 8 Mar 2021 11:58:26 +0000

From: netmod <[email-masked]> on behalf of Rob Wilton (rwilton) <rwilton=[email-masked]>
Sent: 05 March 2021 12:23

Hi Lada,

<tp>
I think that it is safe to say that that will never be feasible.

Code - SMI, YANG ...  - needs the concept of backwards compatible to protect users and others, which is why it has existed for decades even if the details are a bit flakey.

IANA Registries have no such concept and lack the need for one.  Look in vain in RFC8126 for any constraint on changes that can be made, changes that would be ruinous for YANG.

So the first step is to come up with rules for what changes to an IANA Registry come in which category and I am not optimistic that the IETF will ever reach consensus on that.  In which case the rules for YANG will never be in line.

Tom Petch

Rob