Subject: [netmod] yang versioning solution complexity and alternative approaches

From: Jürgen Schönwälder <[email-masked]>
Date: Wed, 9 Mar 2022 11:16:09 +0100

Hi,

the YANG versioning solution appears to be complex.

- We introduce version numbers that smell a bit like SemVers but then
  are not really SemVer.

- We have no solution to do meaningful things with these version
  numbers, it does not even seem to be possible to decide whether
  X.Y.Z derives from x.y.z or not. We still seem to believe that
  having compatibility constraints embedded in module imports are a
  workable solution even though we acknowledge future breaking
  changes.

- We push for a reasonably complex algorithm to calculate deltas of
  YANG module revisions to let users of modules to determine the real
  impact of module updates on their work.

I wonder why we not consider the opposite approach, namely to have
author making NBC changes to document them right where the changes
are. If authors would write something like

      leaf foo {
	nbc-change "2022-03-01" {
          description "changed type from int32 to string";
	};
	// ...
      }

then tool and humans can easily figure out in which revision NBC
changes occured and if they affect a certain usage of the module.

Instead of simply properly documenting the changes, we invent fuzzy
version numbers and complex algorithms to reverse engineer the facts
that could have easily been documented by whoever makes the change.

If the reason is that developers do not document their changes, then
go and develop tools to force them to document their changes. I do not
think it is fair to simply push the pain to the users of YANG modules.

/js

-- 
Jürgen Schönwälder              Jacobs University Bremen gGmbH
Phone: +49 421 200 3587         Campus Ring 1 | 28759 Bremen | Germany
Fax:   +49 421 200 3103         <https://www.jacobs-university.de/>

---

From: Andy Bierman <[email-masked]>
Date: Wed, 9 Mar 2022 10:12:43 -0800

> the YANG versioning solution appears to be complex.
strongly agree.

There are many new procedures (for using extensions) that are not likely to
be adopted outside of the IETF/

There was a valid original problem statement related to release trains.
This is the first disconnect. The problem is related to software release
trains.
Vendors do not release YANG modules. The release software that contains and
implements YANG modules.

Multiple release trains can lead to 2 problems (that are currently handled
by the implementation)

1) most recent release date for a module may not be the latest in all
software release trains
    This affects "import-without-revision" for a client that tries to use
the most recent revision

2) the same [name, date] tuple may be used in multiple release trains.
   This affects the YANG library and <get-schema>.

The solution for (1) is problematic because extensions are used and a YANG
1.1 compliant
tool MAY ignore ANY extension. I support a better import-stmt, but this
should be
done in a new YANG version so it is not optional to implement.

The solution for (2) is not workable (as pointed out, it could take 5 days
to release a change),
and the different revision dates add complexity and do not work if
import-by-revision is used.

A great deal of effort is spent identifying that an NBC change occurred.
IMO it is not useful at the module level.  It would be useful at the object
level,
but at a significant module maintenance cost.

> - We introduce version numbers that smell a bit like SemVers but then

This is very important.
IMO it will do harm to interoperability to have 2 SemVer schemes in use.
The early drafts said the OpenConfig SemVer 2.0 would be used.

>   workable solution even though we acknowledge future breaking

We have no plans whatsoever to write code that uses the NBC extensions.
The module revisions have to be compared and the real changes have to
be evaluated against real use-cases and real applications.  Since the
tooling
has to do all the work anyway, having a "this module changed" flag is not
really useful.

>   impact of module updates on their work.

The semver is trying to characterize changes to the YANG module and also
seems to try to identify the software release train containing the module.

>           description "changed type from int32 to string";

This is more work but also more useful.

I am confused about the revision updates for work-in-progress.
IMO there SHOULD NOT be any revision tracking from I-D to I-D.
This would be total noise and way too much work.
Consider the client-server groupings, which had constant NBC changes
across 27 revisions of the drafts.

I-Ds currently reuse the same revision-stmt over and over in an update I-D,
just changing the date.  Maintaining a semver label throughout this process
is a waste of time.

There is also no way to tell that a 1.x.x release is a work-in-progress.
It is clear for 0.x.x  only.

There is no easy way to identify a release as "published" or "unpublished",
especially since YANG modules are extracted from the source document.

> that could have easily been documented by whoever makes the change.

Some vendors actually avoid making NBC changes to their APIs.
IMO this IETF work is trying to normalize bad engineering practice.
The past WG (people creating YANG 1.0 and YANG 1.1) felt quite strongly
that changing the type of a leaf was something that should not be allowed.

> think it is fair to simply push the pain to the users of YANG modules.

1 more comment:

Errata not integrated:

Most organizations publish corrected documents when mistakes are found, but
not the IETF.
Instead the WEB page will have a link "Errata Exists".  It is up to the
reader to notice it,
read all the errata, apply all the changes manually, and maintain their own
private copy
of the RFC.

This is especially bad for extracted YANG modules.
For example there is no way to create a revision label (or date string) that
indicates that this is  [ietf-netconf-notifications, 2012-02-06] + Errata
3957.
Vendors just hack the incorrect RFC version of the module.
It would be quite useful to have corrected YANG modules when errors are
found.
Even the YANG repos simply maintain the uncorrected versions.

/js
Andy

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

---

From: Jürgen Schönwälder <[email-masked]>
Date: Tue, 22 Mar 2022 10:10:22 +0100

Since I wrote this down anyway I can share it with the WG. Here is a
set of fictious examples adopting annotations as they are often used
in programming languages. The idea is to focus on documenting changes
instead of inventing fuzzy numbering systems plus magic algorithms to
find changes.

revision 2022-03-22 {  }
revision 2022-03-20 {  }
revision 2022-03-01 {  }

typedef foo {
  type int16;
  v:since "2022-03-22";
}

typedef bar {
  type int8;
  v:since "2022-03-20";
  status deprecated {
    v:since "2022-03-22"
    description "Deprecated, use typedef foo instead."
  }
}

typedef baz {
  type uint8;
  status obsolete {
    v:since 2022-03-20;
  }
}

typedef boo {
  type string;
  v:since 2022-03-01;
  v:incompatible {
    v:at "2022-03-20"
    description "Moved type from int8 to string.";
  }
  status "deprecated" {
    v:since 2022-03-22;
    description "This incompatible update was a bad idea.";
  }
}

/js