Subject: [Netmod-ver-dt] Solutions review

From: Balázs Lengyel <[email-masked]>
Date: Sat, 13 Oct 2018 13:53:18 +0000

Hello Rob,

A bunch of comments to the solutions doc. If you send me the git
link again I could edit the draft, but I am not sure all my views
are shared by the whole group.

Ch 1) We need to define what a patch/bug-fix/cosmetic change is.

Patch: do not use the term

Bug-fix: Any change that does not change the intended and
described working of the interface. Bug fixes are considered bc
changes. Bug-fixes include:

Updates to the description statement if they don't change the
semantics of the schema-node

Correction type updates to the schema definition if the
original intent was clearly described in the YANG model at least
in the description statement. These types of bug-fixes are
allowed to be formally nbc.

The implementation behind the model usually (but not always) rejects
incorrect values even if the faulty YANG model allows it.

The possiblity of bugfixes MUST not be abused to hide functional
updates by labeling them bug fixes. If an implementation fails to
fullfill the contract defined by the model that in itself does not
mean the model is faulty (so should be fixed), it just means the
implementation deviates from the model.

Examples include:

Updating a pattern statement for an IpV4 address that allows
addresses starting with 355

Updating a leafref path that points to a different object then
what is defined in a description

Updating a description statement that don't correctly define
the datatype used, like wrong textual definition of a
distinguished name defined in an other RFC.

If this is too long maybe make this a separate section.

Cosmetic change: (I don't know if we need the term at all):
Update to the description statement if it does not change the
semantics of the schema-node like correcting spelling mistakes.

Ch 4) there are two 2.1 requirements in the list.

CH 5.1)

We anyway manage interface (YANG) versioning separartely from SW
releases. IMHO our task is just to manage interface versioning.
Ericsson (and probably others) have a lot of models that are mixed
and matched for different products and product releases. Keeping a
consistent versioning for each release inside the YAMs would be a
nightmare. So while all the branching we have discussed is a valid
requirement/concern connecting the SW release  and the interface
(YANG) versioning is something we should avoid. Please change the
wording.

" anticipated to not meet the business requirements of vendors"
Ericsson and Openconfig are already using this solution, so it
does meet the requirements of some vendors. It does not need the
needs of "some vendors".

Disadvantages 2 and 3 seem to be the same.

5.2) Does major=0 mean a prerelease of that release?

For the second disadvantage you need to add "in different
releases"

5.3) Sorry I still don't see the advantage over 5.2

I have read https://pvp.haskell.org/faq/#semver  but still don't
see it. You need to provide a detailed example because I guees
many others will not get it.

5.4)

"To mitigate this, it is proposed that this solution also
introduces a

new YANG extension statement to indicate that a change is
backwards

compatible."

Compatible to which previous version. This will have the same set
of issues as the model versioning, but also degrade readability.

A big disadvantage is that a complicated tool needs to be run in
live systems often. It is not enough to use this tool in
design/implementation time. We would need to write, update and
maintain this tool for many different environments and programing
languages. Integrating YANG extensions into the tool will be a big
work.

A big disadvantage is thatwhile simple scripts can check a
module's version on-the fly running a big tool is not feasible.

Running a tool to check this in a live real-time environment
might create delays in processing.

Running such a tool in a constrained resource constrained
environment may be a problem.

5.5) There are immediate problems with obsolete/deprecated schema
nodes that are not solved by 5.5

5.6)

Add: When evaluating solution alternatives requirements 2.1, 3.2,
4.1, 4.2, 4.3, 5.1, 5.2, 5.3  were not considered as their
implementation does not seem to dependd on the chosen alternative.
Natuarally selecting the alternative to stick to the existing
rules will not solve any of the above requirements.

6.1)

All YAMs must have a revision date. IMHO it should be unique,
because it is used as a key in many places today. I don't care
about functionality flip-floping, because that can already happen
today. (Add a few features obsolete another few, again, again. You
will never know if a newer system has more or less features.)

6.3) There are systems that model internal interfaces with YAM.
They can coordinate changes, so they probably don't care that much
for compatibility. Do we want to mentin this?

6.4) Define what is a "native YANG module".

regards Balazs

--
Balazs Lengyel Ericsson Hungary Ltd.
Senior Specialist
Mobile: +36-70-330-7909 email: [email-masked]

---

From: Robert Wilton <[email-masked]>
Date: Mon, 15 Oct 2018 17:37:10 +0100

Hi Balazs,

Thanks for the comments.

The github link is https://github.com/netmod-wg/yang-ver-dt

Some comments inline ... it would be good if others can also chip in on 
their thoughts ...  I've applies some updated, but there is still more 
to do.

What do you mean by YAM?  Is this just an abbreviation for YANG module?

Yes, I'm also happy for anyone to update it directly.

On 13/10/2018 14:53, Balázs Lengyel wrote:
>
> Hello Rob,
>
> A bunch of comments to the solutions doc. If you send me the git link 
> again I could edit the draft, but I am not sure all my views are 
> shared by the whole group.
>
Patch is as used in https://semver.org/, and is part of the 
major.minor.patch version number scheme.  I think that it should only be 
used as a field in version strings.

>
> Bug-fix: Any change that does not change the intended and described 
> working of the interface. Bug fixes are considered bc changes. 
> Bug-fixes include:
>
I'm not sure whether we necessarily want to define bug fix, or assume 
that folks already know what it is.

If I were to define a bug fix then I would probably define it is:
Bug-fix: Any change to a published YANG model with the aim of correcting 
incorrectly specified functionality.  Depending on what the scope of 
changes are a bug fix could be classified as a major change, minor 
change or patch level change.

I.e. I could see that a bug fix is classified as :
  a major change, if the module is changed in a non backwards compatible 
way, unless configuration clients can be reasonably expected not to be 
broken by the change
  a minor change, if the module is changed in a backwards compatible way.
  a patch change, if the module is changed in a way that does not modify 
the YANG semantics in any way (e.g. correcting or improving the 
description, but retaining exactly the same behavior).

I still have an open mind as to whether a non backwards compatible bug 
fix is allowed:
  - If the versioning solution doesn't easily allow nbc changes to 
released software then I think that a looser interpretation of bc/nbc 
bugfix is probably required.
  - If, however, the versioning does allow for nbc change to released 
software (e.g. the major.major.minor.patch) scheme then a stricter 
interpretation of whether a bugfix is bc or nbc may be better.  I.e. 
allow the client to see the change and determine whether or not they 
might get broken by the change.

>   * Updates to the description statement if they don't change the
>   * Correction type updates to the schema definition if the original
>     intent was clearly described in the YANG model at least in the
>     description statement. These types of bug-fixes are allowed to be
>     formally nbc.
>
This might be true, but it is also important on how the implementation 
rejects incorrect values:
  i) if it fails the config request, such the the client cannot observe 
any significant difference in behavior, vs
  ii)if the config is accepted, but then does not get applied (e.g. a 
protocol session doesn't get brought up).

Changing the behavior from (ii) to (i) will break clients.

>   * Updating a pattern statement for an IpV4 address that allows
>   * Updating a leafref path that points to a different object then
>   * Updating a description statement that don't correctly define the
>     datatype used, like wrong textual definition of a distinguished
>     name defined in an other RFC.
>
> Cosmetic change: (I don't know if we need the term at all): Update to 
> the description statement if it does not change the semantics of the 
> schema-node like correcting spelling mistakes.
>
>
This should now be fixed.

> Ericsson (and probably others) have a lot of models that are mixed and 
> matched for different products and product releases. Keeping a 
> (YANG) versioning is something we should avoid. Please change the wording.
>
> Ericsson and Openconfig are already using this solution, so it does 
> meet the requirements of some vendors. It does not need the needs of 
> "some vendors".
>
Yes, OK.  I have changed to "some vendors", but I think that you are 
looking for further updates here.

Note, I don't think that the requirement is necessarily that the YANG 
modules have to be versioned as part of the releases (certainly, I'm not 
proposing including and software release version number in the YANG 
module), but more whether it should be possible to add backwards 
compatible or not backwards compatible changes to a release that has 
already shipped.  Even if the YANG is versioning separately from the 
releases, the different schemes give differing amounts of flexibility.

> Disadvantages 2 and 3 seem to be the same.
These are slightly different, but I've moved them as sub points to the 
first disadvantage.

> 5.2) Does major=0 mean a prerelease of that release?
If a release number is being used then probably major=0 should not be used.

> For the second disadvantage you need to add "in different releases"
>
I didn't understand this (or perhaps I had already updated my local copy).

> I have read https://pvp.haskell.org/faq/#semver but still don't see 
> it. You need to provide a detailed example because I guees many others 
> will not get it.
>
OK, I can look at doing this.

The main advantage over 5.1 is that it allows for non backwards 
compatible bug fixes to older releases.
The main advantage over 5.2 is that the number properly follows semver 
properties.  I.e. from the version number alone I know whether or not it 
is a backwards compatible, or backwards compatible change. 5.2 does not 
have these semantics because of the release version number that doesn't 
follow semver rules.

> 5.4)
>
> "To mitigate this, it is proposed that this solution also introduces a
>    new YANG extension statement to indicate that a change is backwards
>    compatible."
>
> Compatible to which previous version. This will have the same set of 
> issues as the model versioning, but also degrade readability.
>
It would follow the rules of the module level version number. Probably 
it would specify the module version number where the change was introduced.

I'm not convinced that it would degrade readability, since it is only 
required in cases where the tooling cannot automatically determine 
whether or not it is a backwards compatible change or not, and hence to 
be safe, assumes the worse case.

> A big disadvantage is that a complicated tool needs to be run in live 
> systems often. It is not enough to use this tool in 
> languages. Integrating YANG extensions into the tool will be a big work.
>
Hum, I'm not convinced.  It seems to be me that this is just providing 
automated tooling for what would have to be done by a client engineer.  
E.g. when a tool, or client engineer, spots that the version number has 
increased in a non backwards compatible way, what do they do?  If they 
have to look at the modules to determine what the changes are then they 
are just performing a manual version of what this tool would do.

> A big disadvantage is thatwhile simple scripts can check a module's 
> version on-the fly running a big tool is not feasible.
>
The idea of this tool is probably that it would be used above and beyond 
the module level version schemes.

> Running a tool to check this in a live real-time environment might 
> create delays in processing.
>
Possibly yes, depending on how efficient the tool is.

But look at this the other way, if you don't have the tool, and the 
client is using version 2.0.0, and the server replies that you are using 
version 3.0.0 then you will have bigger delays because the client cannot 
interact with the server at all because it doesn't know what the 
incompatible changes are.

> Running such a tool in a constrained resource constrained environment 
> may be a problem.
>
Possibly yes, but I think that a lot of depends on implementation and 
how it is being used.

> nodes that are not solved by 5.5
Yes, but none of the solutions in section 5.1 to 5.5 address 
obsolete/deprecated.

> 5.6)
>
> Add: When evaluating solution alternatives requirements 2.1, 3.2, 4.1, 
> 4.2, 4.3, 5.1, 5.2, 5.3  were not considered as their implementation 
> does not seem to dependd on the chosen alternative. Natuarally 
> selecting the alternative to stick to the existing rules will not 
> solve any of the above requirements.
>
I've changed this higher in the document to hopefully clarify which 
requirements are addressed where.

> 6.1)
> All YAMs must have a revision date. IMHO it should be unique, because 
> it is used as a key in many places today. I don't care about 
> functionality flip-floping, because that can already happen today. 
> (Add a few features obsolete another few, again, again. You will never 
> know if a newer system has more or less features.)
>
I agree, but I think that this issue is probably still open.

> 6.3) There are systems that model internal interfaces with YAM. They 
> can coordinate changes, so they probably don't care that much for 
> compatibility. Do we want to mentin this?
>
Probably not required.

> 6.4) Define what is a "native YANG module".
I've change the text to use "vendor YANG module", we already have a 
reference to RFC 8199.

Thanks,
Rob

> Mobile: +36-70-330-7909              email:[email-masked]  
>
>
> _______________________________________________
> Netmod-ver-dt mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/netmod-ver-dt