Subject: [netmod] backward compatibility requirements in draft-verdt-netmod-yang-versioning-reqs-00

From: Andy Bierman <[email-masked]>
Date: Fri, 20 Jul 2018 14:41:33 -0700

Hi,

I strongly object to requirement 3.1:

    3.1  The solution MUST provide a mechanism to allow servers to
            support existing clients in a backward compatible way.

This is not what servers do today at all.
They provide only one version of an implemented module, as specified in RFC
7950.

It is a vendor and operator decision when to upgrade a server such that
non-backward compatible changes are made. They must decide if/when it is ok
based on the client applications in use.

This requirement says you cannot make backward-incompatible changes
which completely contradicts requirements 1.1 and 1.2.

IMO requirement 3.1 should be removed, or change MUST to MAY

Andy

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Sat, 21 Jul 2018 07:45:56 +0200

My understanding is that the MUST puts a requirement on the solution
and the rest is an "allow servers", i.e., something that servers may
want to do. (I was against using RFC 2119 keywords in the first place
for this document.)

/js

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

-- 
Juergen Schoenwaelder           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: Juergen Schoenwaelder <[email-masked]>
Date: Sat, 21 Jul 2018 07:49:35 +0200

> They provide only one version of an implemented module, as specified in RFC

But today a backwards incompatible change leads to a new module and
you can very well implement two modules if that is reasonable to do in
order to allow clients a transition period.

/js

---

From: Andy Bierman <[email-masked]>
Date: Sat, 21 Jul 2018 01:48:37 -0700

> order to allow clients a transition period.

But you can tell the 2 subtrees apart this way.
If I change /foo from a container to a list, then how do you support both
implementations
of container /foo and list /foo at the same time?

Andy

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Sat, 21 Jul 2018 12:12:23 +0200

> of container /foo and list /foo at the same time?

Well, all of this is the consequence of moving from the current naming
system (module, path) to (module,path,version). Once we allow
non-backwards compatible changes, then we may have to find ways to
support different versions of a module (i.e, during session
establishment the client selects a version context to work with).

To be clear about my involvement in the versioning design team: I am
personally not convinced that a different versioning scheme is going
to be simpler; certain things that are simple and robust today will
become more complex and fragile. I decided to get involved in order to
point out that moving to a (module,path,version) naming scheme has
many implications since everywhere where we currently use
(module,path) we need to think about now required version context is
coming from. This goes far beyond YANG imports, this impacts likely
protocols, the proposed instance document storage format, NACM rules
may need to be interpreted in a version context etc.

/js

---

From: Andy Bierman <[email-masked]>
Date: Sat, 21 Jul 2018 03:44:11 -0700

> may need to be interpreted in a version context etc.

Supporting multiple concurrent conflicting configuration management models
 is too complicated
and I would expect those interested in tractable solutions will look
elsewhere.

/js

Andy

---

From: Christian Hopps <[email-masked]>
Date: Sat, 21 Jul 2018 12:00:15 -0400

As I pointed out at the mic @102 this requirement derives directly from the 1.x requirement of not changing the name of the module/namespace. If you allow for changing the namespace/module name for "major" (i.e., incompatible) changes (i.e., like today) then this 3.1 requirement goes away.

I think the plan is to reword some of these to get closer to the intention which I believe is to allow for smoother transition from one module to the next while making incompatible but mostly non-impacting changes.

Thanks,
Chris.

---

From: Andy Bierman <[email-masked]>
Date: Sat, 21 Jul 2018 09:25:19 -0700

On Sat, Jul 21, 2018 at 9:00 AM, Christian Hopps <[email-masked]> wrote:

> As I pointed out at the mic @102 this requirement derives directly from
> the 1.x requirement of not changing the name of the module/namespace. If
> you allow for changing the namespace/module name for "major" (i.e.,
> incompatible) changes (i.e., like today) then this 3.1 requirement goes
> away.
>
> I think the plan is to reword some of these to get closer to the intention
> which I believe is to allow for smoother transition from one module to the
> next while making incompatible but mostly non-impacting changes.
>
>
You may find that reality interferes with your requirement.
The term "incompatible" should be a clue.  If the change is genuinely
incompatible
then the underlying system change may be incompatible as well.
Passive operations like <get> are not a problem, but configuration
datastores
are a problem.  There are good reasons that RFC 7950 says only 1 revision
of a module can be advertised by a server.

There is already a practical solution that is available today.
A vendor can implement the server in a way that allows their customer to
select the appropriate revision for their use-cases and tools environment.

So how does YANG validation work?
There is only 1 instance of <intended>.
E.g., i there are 3 versions of module A and 2 versions of module B,
then which versions does module C use for XPath validation that reference
modules A and B?  Is a new version of XPath needed for YANG?

It is possible to make a standard so complicated that nobody implements it.

Thanks,
Andy

---

From: Christian Hopps <[email-masked]>
Date: Sat, 21 Jul 2018 17:47:45 -0400

Perhaps you are mistaking my intention here? I want a simple solution. I advocated for *not* introducing a new major version component. I don't want models changing all the time. I don't believe there is a large need for incompatible changes.

There are actual instances where small perhaps non-disruptive but incompatible changes are required. The example given to me for this type of change was when the original specification had an obvious bug (e.g., a range was incorrectly specified). I think for these there are non-standard solutions (e.g., a server could be configured to map a set (or all) clients to new module name/namespace if the operator/user decides its safe to do so). Naming conventions (e.g., a version suffix) can identify lineage to earlier "major" versions of a module as well.

Joe Clark mentioned one thing to me that I do think is missing and needed in YANG and that is some form of a "import after" so that module designers/users have the ability to select a version of the module that includes additions that have shown up in later revisions. I believe this can utilize the current revision (date) semantics.

It seems one place seeing a lot of "major" changes is with vendor models. I think internal development processes are driving these, and the vendors need to fix these processes, and not just make it easier to push these changes out to the operators/users. I expressed this multiple times to the design team this last week.

Thanks,
Chris.

---

From: Robert Wilton <[email-masked]>
Date: Mon, 23 Jul 2018 10:50:26 +0100

Hi Chris, Andy,

On 21/07/2018 17:00, Christian Hopps wrote:
> As I pointed out at the mic @102 this requirement derives directly 
> from the 1.x requirement of not changing the name of the 
> module/namespace. If you allow for changing the namespace/module name 
> for "major" (i.e., incompatible) changes (i.e., like today) then this 
> 3.1 requirement goes away.
Not sure that I agree.

I think that you have made an assumption here that the server will 
continue to support both old and new major revision (with different 
name) of the module at the same time.  However, these is nothing in the 
existing YANG upgrade rules that requires that.

Ultimately, there is a choice whether supporting older module versions 
is the servers problem or the clients problem, or perhaps a combination 
of the two.

The aim of requirement 3.1 is to ensure that there is a standard 
mechanism available so that server implementations that want the 
flexibility of supporting older client versions have a standard way of 
doing so.  My intention is that this part of the solution would be 
optional to implement and hence decided by the market, which is why the 
text in the requirement is "to allow servers" rather than "to require 
servers".

Thanks,
Rob

>
> I think the plan is to reword some of these to get closer to the 
> intention which I believe is to allow for smoother transition from one 
> module to the next while making incompatible but mostly non-impacting 
> changes.
>
> Thanks,
> Chris.
>
> .

---

From: Andy Bierman <[email-masked]>
Date: Mon, 23 Jul 2018 04:54:41 -0700

On Mon, Jul 23, 2018 at 2:50 AM, Robert Wilton <[email-masked]> wrote:

> continue to support both old and new major revision (with different name)
> of the module at the same time.  However, these is nothing in the existing
> YANG upgrade rules that requires that.
>
> Ultimately, there is a choice whether supporting older module versions is
> the servers problem or the clients problem, or perhaps a combination of the
> two.
>
> The aim of requirement 3.1 is to ensure that there is a standard mechanism
> available so that server implementations that want the flexibility of
> supporting older client versions have a standard way of doing so.  My
> intention is that this part of the solution would be optional to implement
> and hence decided by the market, which is why the text in the requirement
> is "to allow servers" rather than "to require servers".
>
>

API versioning is usually done on the message exchanges.
Trying to do the same for datastore contents is not going to work.
You can write the word MUST in all caps as many times as you want,
but that will not change anything.

Andy

---

From: Robert Wilton <[email-masked]>
Date: Mon, 23 Jul 2018 14:24:57 +0100

On 23/07/2018 12:54, Andy Bierman wrote:
>
>
> On Mon, Jul 23, 2018 at 2:50 AM, Robert Wilton <[email-masked] 
> <mailto:[email-masked]>> wrote:
>
>     Hi Chris, Andy,
>
>
>         As I pointed out at the mic @102 this requirement derives
>         directly from the 1.x requirement of not changing the name of
>         the module/namespace. If you allow for changing the
>         namespace/module name for "major" (i.e., incompatible) changes
>         (i.e., like today) then this 3.1 requirement goes away.
>
>     Not sure that I agree.
>
>     continue to support both old and new major revision (with
>     different name) of the module at the same time.  However, these is
>     nothing in the existing YANG upgrade rules that requires that.
>
>     Ultimately, there is a choice whether supporting older module
>     versions is the servers problem or the clients problem, or perhaps
>     a combination of the two.
>
>     flexibility of supporting older client versions have a standard
>     way of doing so.  My intention is that this part of the solution
>     would be optional to implement and hence decided by the market,
>     which is why the text in the requirement is "to allow servers"
>     rather than "to require servers".
>
>
>
A YANG schema can be considered an API.  Particularly looking at say the 
OpenConfig YANG schema.  I doubt all implementations will store all 
their configuration and operational state in a central place.

> but that will not change anything.

I disagree.  Marking a requirement as a MUST means that requirement has 
to be met for a solution to be considered viable.

I previously had some text in the draft explaining how RFC 2119 text 
translates to evaluating the requirements, but was asked to take it out 
because it is obvious.  Perhaps it should go back in ...

Thanks,
Rob

>     Thanks,
>     Rob
>
>
> Andy
>
>
>
>
>         I think the plan is to reword some of these to get closer to
>         the intention which I believe is to allow for smoother
>         transition from one module to the next while making
>         incompatible but mostly non-impacting changes.
>
>         Thanks,
>         Chris.
>
>         Andy Bierman <[email-masked] <mailto:[email-masked]>>
>         writes:
>
>             Hi,
>
>             [email-masked] <mailto:[email-masked]>
>             <https://www.ietf.org/mailman/listinfo/netmod>
>
>
>         [email-masked] <mailto:[email-masked]>
>         <https://www.ietf.org/mailman/listinfo/netmod>
>         .
>
>
>

---

From: Andy Bierman <[email-masked]>
Date: Mon, 23 Jul 2018 07:08:03 -0700

On Mon, Jul 23, 2018 at 6:24 AM, Robert Wilton <[email-masked]> wrote:

>> doing so.  My intention is that this part of the solution would be optional
>> to implement and hence decided by the market, which is why the text in the
>> requirement is "to allow servers" rather than "to require servers".
>>
>>
>
> OpenConfig YANG schema.  I doubt all implementations will store all their
> configuration and operational state in a central place.
>
> I disagree.  Marking a requirement as a MUST means that requirement has to
> be met for a solution to be considered viable.
>
So you can answer the question how YANG validation works when multiple
revisions of a
module are implemented?  I do not doubt that you can find a leaf somewhere
that can
be changed.  Not at all convinced the validation rules can be rewritten to
account
for actual incompatible changes, like changing the type of data node or
replacing nodes
with completely different configuration.  Even less convinced that this
complexity is
worth the cost.

Thanks,
Andy

---

From: Robert Wilton <[email-masked]>
Date: Mon, 23 Jul 2018 15:32:18 +0100

On 23/07/2018 15:08, Andy Bierman wrote:
>
>
> On Mon, Jul 23, 2018 at 6:24 AM, Robert Wilton <[email-masked] 
>>             directly from the 1.x requirement of not changing the
>>             name of the module/namespace. If you allow for changing
>>             the namespace/module name for "major" (i.e.,
>>             incompatible) changes (i.e., like today) then this 3.1
>>             requirement goes away.
>>
>>         Not sure that I agree.
>>
>>         I think that you have made an assumption here that the server
>>         will continue to support both old and new major revision
>>         (with different name) of the module at the same time.
>>         However, these is nothing in the existing YANG upgrade rules
>>         that requires that.
>>
>>         versions is the servers problem or the clients problem, or
>>         perhaps a combination of the two.
>>
>>         The aim of requirement 3.1 is to ensure that there is a
>>         standard mechanism available so that server implementations
>>         that want the flexibility of supporting older client versions
>>         have a standard way of doing so.  My intention is that this
>>         part of the solution would be optional to implement and hence
>>         decided by the market, which is why the text in the
>     A YANG schema can be considered an API.  Particularly looking at
>     say the OpenConfig YANG schema.  I doubt all implementations will
>     store all their configuration and operational state in a central
>     place.
>
>     I disagree.  Marking a requirement as a MUST means that
>     requirement has to be met for a solution to be considered viable.
>
>     I previously had some text in the draft explaining how RFC 2119
>     text translates to evaluating the requirements, but was asked to
>     take it out because it is obvious. Perhaps it should go back in ...
>
>
> module are implemented?

Ok, so the scheme that I was considering is:
  - The device implements only one version of the schema (i.e. probably 
all of the latest modules revisions/versions).

However, the protocols are extended to allow clients to select to use an 
older version set of the modules for that session.  YANG library for 
that session would report the chosen set of modules as "implemented" by 
the server for that session.

The server chooses how many different sets of modules are supported, and 
exactly what module revisions, features are included in each of those 
module sets.  Normally I would expect exact module sets to align with a 
previous software release.  The different module-sets can be exposed via 
YANG library bis.  New RPCs or protocol extensions are required to 
choose which version is being used for the session.

The server then has code to map from the older module set paths to the 
latest version that is "implemented" by the device.  The vast majority 
of the mappings would be trivial mappings of the same value on the same 
path.

This mapping is exactly the same as would have to be done on a client if 
it has to support servers running different revisions.

Not all changes can be mapped, some would have to just fail (perhaps 
could be covered by deviations).

>   I do not doubt that you can find a leaf somewhere that can
> be changed.  Not at all convinced the validation rules can be 
> rewritten to account
> for actual incompatible changes, like changing the type of data node 
> or replacing nodes
> with completely different configuration.
The mapping above will not be perfect in all cases, particularly if keys 
are changes, or support for software is removed, etc.  But they might 
still help.

>   Even less convinced that this complexity is
> worth the cost.

Well the complexity ends up going in the client or the server.  I think 
that this is generally a complex problem to solve.  Operators will 
likely argue that it is better that the complexity goes in the server to 
keep the client simple.  Server vendors will likely argue for the reverse.

Note, that I'm still somewhat open to what the right solution should be 
here.

Thanks,
Rob

>
>
>
>     Thanks,
>     Rob
>
>
> Andy
>
>>         Thanks,
>>         Rob
>>
>>
>>     Andy
>>
>>
>>
>>
>>             I think the plan is to reword some of these to get closer
>>             to the intention which I believe is to allow for smoother
>>             Andy Bierman <[email-masked]
>>             <mailto:[email-masked]>> writes:
>>
>>                 Hi,
>>

---

From: Andy Bierman <[email-masked]>
Date: Mon, 23 Jul 2018 11:46:31 -0700

On Mon, Jul 23, 2018 at 7:32 AM, Robert Wilton <[email-masked]> wrote:

>>> is the servers problem or the clients problem, or perhaps a combination of
>>> the two.
>>>
>  - The device implements only one version of the schema (i.e. probably all
> of the latest modules revisions/versions).
>
> older version set of the modules for that session.  YANG library for that
> session would report the chosen set of modules as "implemented" by the
> server for that session.
>
> YANG library bis.  New RPCs or protocol extensions are required to choose
> which version is being used for the session.
>
> latest version that is "implemented" by the device.  The vast majority of
> the mappings would be trivial mappings of the same value on the same path.
>
> Not all changes can be mapped, some would have to just fail (perhaps could
> be covered by deviations).
>
> are changes, or support for software is removed, etc.  But they might still
> help.
>
> that this is generally a complex problem to solve.  Operators will likely
> argue that it is better that the complexity goes in the server to keep the
> client simple.  Server vendors will likely argue for the reverse.
>

Sounds very complicated to implement in the server, but at least you avoid
multiple variants of a datastore.
Instead the server is providing various transformations between data models.

This will make the standards much more complicated and heavyweight to
implement.
If it was so easy and so important, vendors would already support it in
their proprietary APIs.
Instead vendors decide when to end-of-life products and features.

Andy

---

From: Kent Watsen <[email-masked]>
Date: Tue, 24 Jul 2018 00:25:38 +0000

Before RESTCONF, I implemented a versioned REST API that maintained constant object URIs, while allowing the objects themselves to be versioned, by using the Content-Type and Accept headers (yes, we created a media type for every "object" in the system).  The server always natively understood the "latest", while being able to translate to/from the last few versions of the product.  It was effort to update the translators each release but, thankfully, there were only a few of them each time, and the unit-tests from the previous releases could be used to test correctness of the translators.

What's being discussed now sounds similar, with similar associated costs.  Whether or not we use a new module-name per "major" version (essentially what we have today, but further refined by Chris's idea) won't affect this cost much.  The primary advantage to using the same module name across major versions is that is gives to client more clue behind what is going on.  Perhaps similar clue can be achieved via an extension statement:

  module foo-3 {
    …
    replaces-module foo-2;
    …
  }

Kent // contributor

On 7/23/18, 2:46 PM, "netmod on behalf of Andy Bierman" <[email-masked]<mailto:[email-masked]> on behalf of [email-masked]<mailto:[email-masked]>> wrote:

On Mon, Jul 23, 2018 at 7:32 AM, Robert Wilton <[email-masked]<mailto:[email-masked]>> wrote:

On Mon, Jul 23, 2018 at 6:24 AM, Robert Wilton <[email-masked]<mailto:[email-masked]>> wrote:

On Mon, Jul 23, 2018 at 2:50 AM, Robert Wilton <[email-masked]<mailto:[email-masked]>> wrote:
Hi Chris, Andy,

I think that you have made an assumption here that the server will continue to support both old and new major revision (with different name) of the module at the same time.  However, these is nothing in the existing YANG upgrade rules that requires that.

Ultimately, there is a choice whether supporting older module versions is the servers problem or the clients problem, or perhaps a combination of the two.

The aim of requirement 3.1 is to ensure that there is a standard mechanism available so that server implementations that want the flexibility of supporting older client versions have a standard way of doing so.  My intention is that this part of the solution would be optional to implement and hence decided by the market, which is why the text in the requirement is "to allow servers" rather than "to require servers".

API versioning is usually done on the message exchanges.
Trying to do the same for datastore contents is not going to work.
A YANG schema can be considered an API.  Particularly looking at say the OpenConfig YANG schema.  I doubt all implementations will store all their configuration and operational state in a central place.

I disagree.  Marking a requirement as a MUST means that requirement has to be met for a solution to be considered viable.

I previously had some text in the draft explaining how RFC 2119 text translates to evaluating the requirements, but was asked to take it out because it is obvious.  Perhaps it should go back in ...

So you can answer the question how YANG validation works when multiple revisions of a
module are implemented?

Ok, so the scheme that I was considering is:
 - The device implements only one version of the schema (i.e. probably all of the latest modules revisions/versions).

However, the protocols are extended to allow clients to select to use an older version set of the modules for that session.  YANG library for that session would report the chosen set of modules as "implemented" by the server for that session.

The server chooses how many different sets of modules are supported, and exactly what module revisions, features are included in each of those module sets.  Normally I would expect exact module sets to align with a previous software release.  The different module-sets can be exposed via YANG library bis.  New RPCs or protocol extensions are required to choose which version is being used for the session.

The server then has code to map from the older module set paths to the latest version that is "implemented" by the device.  The vast majority of the mappings would be trivial mappings of the same value on the same path.

This mapping is exactly the same as would have to be done on a client if it has to support servers running different revisions.

Not all changes can be mapped, some would have to just fail (perhaps could be covered by deviations).

  I do not doubt that you can find a leaf somewhere that can
be changed.  Not at all convinced the validation rules can be rewritten to account
for actual incompatible changes, like changing the type of data node or replacing nodes
with completely different configuration.
The mapping above will not be perfect in all cases, particularly if keys are changes, or support for software is removed, etc.  But they might still help.

Well the complexity ends up going in the client or the server.  I think that this is generally a complex problem to solve.  Operators will likely argue that it is better that the complexity goes in the server to keep the client simple.  Server vendors will likely argue for the reverse.

Note, that I'm still somewhat open to what the right solution should be here.

Sounds very complicated to implement in the server, but at least you avoid multiple variants of a datastore.
Instead the server is providing various transformations between data models.

This will make the standards much more complicated and heavyweight to implement.
If it was so easy and so important, vendors would already support it in their proprietary APIs.
Instead vendors decide when to end-of-life products and features.

Thanks,
Rob

Andy

Thanks,
Rob

Andy

Thanks,
Rob

Andy

Thanks,
Chris.

Andy Bierman <[email-masked]<mailto:[email-masked]>> writes:
Hi,

Andy
_______________________________________________
netmod mailing list
[email-masked]<mailto:[email-masked]>
https://www.ietf.org/mailman/listinfo/netmod<https://urldefense.proofpoint.com/v2/url?u=https-3A__www.ietf.org_mailman_listinfo_netmod&d=DwMFaQ&c=HAkYuh63rsuhr6Scbfh0UjBXeMK-ndb3voDTXcWzoCI&r=9zkP0xnJUvZGJ9EPoOH7Yhqn2gsBYaGTvjISlaJdcZo&m=NLKzB3RRvGkAdBdSqsbPf9vbI3OBcyg6nz2Pb0SjZEc&s=Uhv31M1fvzhyys-4tCgiHGkxvk-w-dKbAaehPUeQ_hY&e=>

_______________________________________________
netmod mailing list
[email-masked]<mailto:[email-masked]>
https://www.ietf.org/mailman/listinfo/netmod<https://urldefense.proofpoint.com/v2/url?u=https-3A__www.ietf.org_mailman_listinfo_netmod&d=DwMFaQ&c=HAkYuh63rsuhr6Scbfh0UjBXeMK-ndb3voDTXcWzoCI&r=9zkP0xnJUvZGJ9EPoOH7Yhqn2gsBYaGTvjISlaJdcZo&m=NLKzB3RRvGkAdBdSqsbPf9vbI3OBcyg6nz2Pb0SjZEc&s=Uhv31M1fvzhyys-4tCgiHGkxvk-w-dKbAaehPUeQ_hY&e=>
.

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Tue, 24 Jul 2018 11:29:08 +0200

On Sat, Jul 21, 2018 at 05:47:45PM -0400, Christian Hopps wrote:

> There are actual instances where small perhaps non-disruptive but
> incompatible changes are required. The example given to me for this
> type of change was when the original specification had an obvious
> bug (e.g., a range was incorrectly specified).

I strongly believe that fixing bugs is not a reason to change the
current versioning rules. Bugs come essentially in three flavors:

- A definition is messed up (i.e., a range, a pattern, a must
  expression) but the original intention of the definition is clear
  from the context (description clauses, references, ...). In this
  case, implementors will likely have done the right thing (or when
  they observed the problem they will likely have done the right
  thing).

- A definition is messed up but it is not clear from the context what
  the original intention of the definition was. In this case, there is
  a true ambiguity and implementors can rightfully have come to
  different conclusions how to deal with the conflict in the
  definition.

In the first case, I believe there is no issue with simply fixing the
messed up definition. I believe this kind of bug fixes is not
constrained by the YANG update rules.

In the second case, there is true ambiguity what implementations may
do and hence the safest approach is to deprecate the messed up
definition and to create a replacement.

Of course, in reality, things are often not so clear cut and hence it
takes some informed judgement what is the reasonable way to deal with
things. (A type two bug caught very early may be different from a type
two bug caught after several months of implementation and deployment.)

Sometimes we also have situations where a definition that was
originally OK turs out over time to be problematic as technology has
evolved. So after some time, the original definition starts to look
like a bug but it actually is not. The safe path forward is again to
create new definitions and to deprecate the old ones.

Now, for those in favour of moving from (module, path) to (module,
path, version), you loose the deprecated definition. So if you wan't
to allow for a transition period, there is a need to allow an old
client to work with the old definition and a new client to work with
the new definition. In the current naming scheme, this is not a
problem, with a (module, path, version) naming scheme this requires
some extra complexity.

/js

---

From: Andy Bierman <[email-masked]>
Date: Tue, 24 Jul 2018 08:11:54 -0700

> problem, with a (module, path, version) naming scheme this requires

The problem with versioning the "YANG API" is that it is not possible to
isolate
individual modules and say "I pick version 1.0.3 of module foo and version
2.1.1
of module bar". And every client can pick a different arbitrary subset of
mix-and-match YANG modules.

Well YANG does not work that way.  There is no concept of a YANG package.
There is no concept of a group of modules/versions/features that are
not divisible within a server implementation.

The other problem is what you are pointing out.
It would be far easier to just fix the clients and the servers, not just
the servers.
Why is it OK for the client developer to decide "we are sticking with the
defective version of the module and not going to upgrade to
the fixed version like the server developers have done."

/js

Andy

---

From: Robert Wilton <[email-masked]>
Date: Tue, 24 Jul 2018 16:32:05 +0100

On 24/07/2018 16:11, Andy Bierman wrote:
>
>
> On Tue, Jul 24, 2018 at 2:29 AM, Juergen Schoenwaelder 
> <[email-masked] 
> <mailto:[email-masked]>> wrote:
>
> The problem with versioning the "YANG API" is that it is not possible 
> to isolate
> individual modules and say "I pick version 1.0.3 of module foo and 
> version 2.1.1
> The other problem is what you are pointing out..
> It would be far easier to just fix the clients and the servers, not 
> just the servers.

One of the aims of the YANG versioning work is to give more information 
to the client about whether they are likely to be impacted by upgrading 
to a new set of modules.  For me, I think that the most useful thing is 
if this is done by comparing the full schema between old and new 
releases (including module versions, enabled features, and deviations), 
and then identifying the data nodes that have been changed in a 
backwards compatible way, and those that have been changed in a non 
backwards compatible way (if that is allowed).

E.g. even it is a change is an obvious bugfix, it still makes sense to 
flag that change so that client implementations can be checked to ensure 
that they don't break.

But if fixing a definition requires a whole new module name then I think 
that causes lots of problems (e.g. consider needing to change 
ief-interfaces to ietf-interfaces-v2 because of changing one random 
leaf).  The YANG 1.1 way is to define a new definition and then 
deprecate the broken one.  But this has negative consequences as well, 
e.g. does writing to the old leaf automatically also write to the new 
leaf at the same time?  Are both returned in a get request? What if a 
different client only writes to the new leaf?

Thanks,
Rob

>     Fax:   +49 421 200 3103         <https://www.jacobs-university.de/
>     <https://www.jacobs-university.de/>>
>
>
>
>

---

From: Andy Bierman <[email-masked]>
Date: Tue, 24 Jul 2018 09:07:11 -0700

On Tue, Jul 24, 2018 at 8:32 AM, Robert Wilton <[email-masked]> wrote:

> One of the aims of the YANG versioning work is to give more information to
> the client about whether they are likely to be impacted by upgrading to a
> new set of modules.  For me, I think that the most useful thing is if this
> is done by comparing the full schema between old and new releases
> (including module versions, enabled features, and deviations), and then
> identifying the data nodes that have been changed in a backwards compatible
> way, and those that have been changed in a non backwards compatible way (if
> that is allowed).
>
> ief-interfaces to ietf-interfaces-v2 because of changing one random leaf).
> The YANG 1.1 way is to define a new definition and then deprecate the
> broken one.  But this has negative consequences as well, e.g. does writing
> to the old leaf automatically also write to the new leaf at the same time?
> Are both returned in a get request?  What if a different client only writes
> to the new leaf?
>
>
I agree a new module is not required.
I like SEMVER. It is still better to follow the YANG update rules, but I am
OK
with using the major version to indicate a non-backward-compatible change.
IMO it should not be fine-grained (e.g., SEMVER per object).
The scope of the standard should just be to identify versions with SEMVER
and fix import-stmt.

I think a server could version the API (all modules, not client-picked).
Not convinced this is a high priority at all, or that it would be easy to
standardize.

Thanks,
Andy

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

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Wed, 25 Jul 2018 13:03:08 +0200

On Tue, Jul 24, 2018 at 04:32:05PM +0100, Robert Wilton wrote:
> that causes lots of problems (e.g. consider needing to change ief-interfaces
> to ietf-interfaces-v2 because of changing one random leaf).

I assume this depends a lot on how clients are written but chances are
that a significant portion of clients are written such in such a way
that dealing with multiple namespaces is difficult. (But yeah, dealing
with multiple versions in the same namespace likely is also difficult
for them.)

What really chances here is the adaptation process: Today, a client
will not bother to use a new namespace (a new version) unless it was
programmed to do so (opt-in). The proposed new versioning scheme
effectively means that client will automatically use new versions
until the client got told to be careful where necessary (and I assume
that in most cases this means until the client failed and then got
fixed, an opt-out process).

I can understand why some people believe a conservative opt-in
approach is desirable for them and I can understand why some other
people believe an optimistic approach opt-out approach is desirable
for them. There are likely good arguments for both and this makes it
difficult to pick one.

At the end, code that needs to support multiple versions is always
going to be to some extend ugly. Whether the uglyness is in namespace
bindings or version checks is likely more a question of taste. I
believe code uglyness is not really driving this but the desire to be
more agile and "lets release and then fix clients when they break" may
be more dynamic than "lets release and then wait for clients to get
updated".

> The YANG 1.1 way is to define a new definition and then deprecate
> the broken one. But this has negative consequences as well,
> e.g. does writing to the old leaf automatically also write to the
> new leaf at the same time? Are both returned in a get request? What
> if a different client only writes to the new leaf?

Sure, duplicate or overlapping config objects is something we usually
try to avoid. In general, I assume a server would try to keep such
overlapping leafs in sync. But then, this is an issue that appears in
any scheme that allows access to multiple versions of a leaf (or
overlapping leafs in general, i.e. a standard object and a vendor
version of it).

The point I was trying to make was a different one, namely that today
we have a way to expose multiple versions of a leaf by using a new
(module, path) name while with a (module, path, version) naming
system, our protocols need extensions to expose multiple versions of a
leaf (or we declare that servers will never expose multiple versions
and that clients must always adapt to the version currently offered by
a server).

/js

---

From: Robert Wilton <[email-masked]>
Date: Wed, 25 Jul 2018 17:25:32 +0100

> with multiple versions in the same namespace likely is also difficult
Yes, I think that this comes down to client implementation.

If clients are looking for a universally unique identifier for a given 
datanode then I think that they already have to consider the triple 
(module, path, X), where X potentially covers:
(i) per device/vendor/release deviations,
(ii) possibly which revision a data node was first introduced in, or 
obsoleted in,
(iii) different YANG features enabled on different devices,
(iv) semantic versioning - at least in the case of the OpenConfig YANG 
modules,
(v) non backwards compatible changes (both bug fixes, and more 
significant refactoring).

Hence, I'm still not really convinced that adding a semantic version 
number is introducing something that robust clients don't have to 
already have handle today (even if they didn't have to cope with (iv) or 
(v), they still may have to cope with (i) and (ii) and (iii) regardless.

One alternative way to build a robust client would be to have an 
internally defined schema by the client (perhaps based on open models, 
or perhaps a particular version of vendor models, possibly with some 
deviations, or their own model) which they can then map onto one or more 
per device schema.  So within a particular schema (internal or device 
specific) then (module name, path) uniquely resolves to a data node with 
particular properties; but between different schema (e.g. for each 
different device) then the same (module name, path) pair is allowed to 
resolve to a different uniquely defined property.

A layer of mapping is performed between the internal schema and the 
device schema for whichever devices/sw-versions it needs to interoperate 
with.  The more closely the two schema align, the easier the mapping is 
to achieve.  This is also why, ultimately, that determining whether 
changes are backwards compatible or not needs to be done at the schema 
level (which takes into account deviations and features), and also the 
per data node level.

It is also worth pointing out that the version selection scheme that I 
described is really just a way to potentially move the mapping layer 
from the client code to the server.  Fundamentally it is doing the same 
job and serving the same purpose.

> fixed, an opt-out process).
My main concern with using module name for major version changes is that 
it forces a name change for each data node in that module, regardless of 
whether that node has actually changed.  This inherently feels like the 
wrong this to do.  If a data node hasn't changed then ideally you want 
it to remain unchanged on the same path.  So the alternative way that 
RFC 7950 supports today is to keep the module name the same but 
introduce new names for all identifiers that have been changed in a non 
backwards compatible way, making use of status deprecated/obsolete.

However, it isn't clear to me that handling the old and new values 
within the same schema is always a good thing to do.  I generally prefer 
the idea of doing version selection (if anyone chooses to support this) 
so that a given value is only reported once.

> for them. There are likely good arguments for both and this makes it
My feeling (and I don't have hard evidence to back this up) is that 
clients are generally less impacted by keeping the name the same rather 
than changing the module name for every major version change.

> be more dynamic than "lets release and then wait for clients to get
With version selection, servers would still have the opportunity of not 
breaking clients, although it doesn't seem that likely to me that 
vendors will spend the effort to implement this.  But I still see that 
allowing the option to do this is a good idea (perhaps as a separate 
experimental draft).

> overlapping leafs in general, i.e. a standard object and a vendor
I still think that clients may struggle to process configuration in a 
get request that they had not configured, and hence were not expecting.

> and that clients must always adapt to the version currently offered by
So, I think that constraint should be that for a given schema (i.e. set 
of implemented modules) there can be only a single definition for a 
(module, path) pairing.  I see the version information, much like 
deviations, as just a mechanism to help clients (and readers) to spot 
where the definition may deviate from what they were previously 
anticipating.

In all cases, I think that minimizing backwards incompatible changes is 
the right thing to do, and I suspect that as YANG gains more traction, 
more of the latent bugs will get fixed, models will harden, and churn 
will decrease.  But I think that vendors will always want an easy way to 
fix bugs, and to change the model in the case that the implementation 
has radically changed, or when the schema is being cleaned up.

Thanks,
Rob

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Wed, 25 Jul 2018 18:59:46 +0200

On Wed, Jul 25, 2018 at 05:25:32PM +0100, Robert Wilton wrote:
> 
> 
> One alternative way to build a robust client would be to have an internally
> defined schema by the client (perhaps based on open models, or perhaps a
> particular version of vendor models, possibly with some deviations, or their
> own model) which they can then map onto one or more per device schema.  So
> within a particular schema (internal or device specific) then (module name,
> path) uniquely resolves to a data node with particular properties; but
> between different schema (e.g. for each different device) then the same
> (module name, path) pair is allowed to resolve to a different uniquely
> defined property.
> 
> A layer of mapping is performed between the internal schema and the device
> schema for whichever devices/sw-versions it needs to interoperate with.  The
> more closely the two schema align, the easier the mapping is to achieve. 
> This is also why, ultimately, that determining whether changes are backwards
> compatible or not needs to be done at the schema level (which takes into
> account deviations and features), and also the per data node level.
>

This is what NMSes used to do and well still nasty work. But I assume
people think about much simpler clients, the scripts that often clue
the things together.

> My main concern with using module name for major version changes is that it
> forces a name change for each data node in that module, regardless of
> wrong this to do.  If a data node hasn't changed then ideally you want it to
> remain unchanged on the same path.  So the alternative way that RFC 7950
> supports today is to keep the module name the same but introduce new names
> for all identifiers that have been changed in a non backwards compatible
> way, making use of status deprecated/obsolete.

Yes, you can decide between the two options today. If only leaf foo
needs an non-backwards compatible update, you create a new leaf
bar. If the majority of leafs in a module need a non-backwards
compatible update, you create a new module.

> However, it isn't clear to me that handling the old and new values within
> the same schema is always a good thing to do.  I generally prefer the idea
> of doing version selection (if anyone chooses to support this) so that a
> given value is only reported once.

I wonder how this will ever work with vendor modules, ietf modules,
ieee modules, openconfig modules, etc. all overlapping, sometimes more
and sometimes less. You would have to create distinct views onto the
same instrumentation if you do not want to have overlapping values.

> My feeling (and I don't have hard evidence to back this up) is that clients
> are generally less impacted by keeping the name the same rather than
> changing the module name for every major version change.

Not sure I parse this correctly...

> I still think that clients may struggle to process configuration in a get
> request that they had not configured, and hence were not expecting.

Maybe, maybe not. Perhaps things get simpler if the relationship of
foo replacing bar is machine readable.

> So, I think that constraint should be that for a given schema (i.e. set of
> implemented modules) there can be only a single definition for a (module,
> path) pairing.  I see the version information, much like deviations, as just
> a mechanism to help clients (and readers) to spot where the definition may
> deviate from what they were previously anticipating.
> 
> In all cases, I think that minimizing backwards incompatible changes is the
> right thing to do, and I suspect that as YANG gains more traction, more of
> the latent bugs will get fixed, models will harden, and churn will
> decrease.  But I think that vendors will always want an easy way to fix
> bugs, and to change the model in the case that the implementation has
> radically changed, or when the schema is being cleaned up.

Well, part of the story line is that it is necessary to produce half
baked modules faster and then to fix them iteratively. And there is
likely some truth to it since implementation of models helps to
understand how to do them better. But once you are in production, you
hate moving APIs and stability is suddenly a big value.

Perhaps all we need is a marker that says "this module is still
experimental and hence it does not provide any backwards compatibility
promises". Clients using these modules then know that newer revisions
can break things.

 module ietf-foo {
    stability alpha;
 }

/js

---

From: Robert Wilton <[email-masked]>
Date: Thu, 26 Jul 2018 11:19:07 +0100

> compatible update, you create a new module.
But my main objection is that changing the name of the module forces a 
name change for all data nodes in the module, even for those that have 
not changed.  I'm just not convinced that this is a good thing to do.

I think that there is an assumption here that if the module is published 
with a new name then servers can implement both old and new modules at 
the same time.  But I'm not sure that vendors will actually do this, nor 
will this necessary work that well in practice.

E.g. if we consider a non backwards compatible change to ietf-interfaces 
that it is decided needs a new module name.  Not only do we need 
ietf-interfaces-v2, but we also need v2 versions of all 70 modules that 
augment from ietf-interfaces, either directly or indirectly.  Now if 
someone makes a get request without a sufficient filter then will twice 
as much data.

> same instrumentation if you do not want to have overlapping values.
Yes, I think that they have to be kept as discrete views.  Or perhaps 
the server is configured as to which external management model it should 
use.  Even with discrete views there are problems due to different 
hierarchies or list keys.  There is no perfect technical solution here, 
although over time I think that things will get better as management 
models slowly converge.

But representing multiple models in one combined view doesn't really 
seem to be a good idea.

I think that some aspects of versioning are the same problem.  E.g. I 
think that there is a difference between a major release where more 
backwards compatible changes could be expected, vs maintenance releases 
where one would expect backwards compatibility should likely be preserved.
> Not sure I parse this correctly...
This was similar to a comment above.  I don't like the (module, path) of 
a data node having to change (due to a module name change for a major 
version) if its definition hasn't changed at all.

> foo replacing bar is machine readable.
Yes, potentially that would help.

> hate moving APIs and stability is suddenly a big value.
Yes, both of these are right.  And partly it is a chicken and egg 
problem.  We would like clients to migrate from CLI to YANG, but that 
requires stable models, but don't want to invest heavily in creating 
stable models in YANG if customers are not using it. Having two separate 
sets of standard models (e.g. IETF and OpenConfig) doesn't help either.

> promises". Clients using these modules then know that newer revisions
Possibly.  In SemVer, version numbers less than 1.0 would generally be 
regarded as experimental.

I think that regardless of what IETF decides to standardize for YANG 
versioning, I can't see OpenConfig changing their direction for their 
own models, so some part of the industry at least will likely have to 
accept semver as part of the solution.

Thanks,
Rob

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Thu, 26 Jul 2018 16:16:16 +0200

On Thu, Jul 26, 2018 at 11:19:07AM +0100, Robert Wilton wrote:
> 
> I think that some aspects of versioning are the same problem.  E.g. I think
> that there is a difference between a major release where more backwards
> compatible changes could be expected, vs maintenance releases where one
> would expect backwards compatibility should likely be preserved.
>

Well 'could be expected' and 'would expect backwards compatibility
should likely be preserved' is kind of hand-waving. There are often
situations where people are reluctant to bump major version numbers
just because a tiny bit of an API has changed in a non-backwards
compatible way - for the same reason that you brought up. Most of the
definitions did not change, so people do not want to bump the major
version.

> This was similar to a comment above.  I don't like the (module, path) of a
> data node having to change (due to a module name change for a major version)
> if its definition hasn't changed at all.

Fine. Then you deprecate the broken foo and create foo'. You do not
like that because you do not want foo and foo' at the same time. But
others want deprecated objects to stay to allow a transition period.

> Yes, both of these are right.  And partly it is a chicken and egg problem. 
> We would like clients to migrate from CLI to YANG, but that requires stable
> models, but don't want to invest heavily in creating stable models in YANG
> if customers are not using it. Having two separate sets of standard models
> (e.g. IETF and OpenConfig) doesn't help either.

So do we hit a requirement (which is independent of versioning) that a
mechanism is needed to select different module sets (or views), given
that the reality gives us overlapping and competing models? And then
as a side effect, such a mechanism may also be used to select between
different versions?

/js

---

From: Robert Wilton <[email-masked]>
Date: Thu, 26 Jul 2018 16:24:45 +0100

> definitions did not change, so people do not want to bump the major
Yes, exactly.

I think that there will always be a reluctance to change the model name 
(e.g. to "module-v2") unless it can truly be made low impact to clients, 
importing modules, etc.  And if we get to something that is low impact, 
then it may well be that we end up with something that is logically 
equivalent to semver anyway.

There may be less reluctance to bump the semver major version number - 
although I agree with you that non backwards compatible bugfixes may be 
a grey area.

E.g. one common non backwards compatible change that I see recently 
between Native YANG models was changing from int32 to uint32 for list 
indexes (mostly in config false nodes).  I don't have the history as to 
why the change was made, but for all intents and purposes the effective 
value set is the same (but not specified in the model), but the encoding 
could differ, and hence it is regarded as a non backwards compatible 
change.  As an aside, part of me wonders whether classifying this as a 
non backwards compatible change is right, although I can see why it is 
specified that way.

> others want deprecated objects to stay to allow a transition period.
Basically yes.

I also think that perhaps there is a level of pragmatism here:
  - if a particular node is widely used, but needs to be changed, then I 
think that we are far more likely to create foo', and continue to 
support foo.
  - but if the node (or nodes) were effectively broken for some reason, 
then even if it is being used by some customers, I think that there is a 
preference to just fix in place.

I think that it just goes back to stability.  The models start off 
somewhat unstable, and then gain stability over time.  We want to be to 
modify/fix them when they are new, but once there are older, we would 
expect a much greater level of stability in them.

> as a side effect, such a mechanism may also be used to select between
Yes.

Thanks,
Rob

---

From: Christian Hopps <[email-masked]>
Date: Sun, 29 Jul 2018 01:07:17 -0400

One answer to a slightly more general version of this question (why is OK for the clients to do nothing while the servers do the work) is that the client developers are often the server developers customers, they pay the bills.

Also in general there is a one to many mapping from a server to it's clients, the overall cost of updating a server and of it supporting multiple versions or transforming or whatever is much less than the overall cost of all the users of that server updating their client software.

I'm not advocating for clients never updating, but I think it's unreasonable to think that clients will be updating as fast as servers, or to design a versioning scheme that assumes anything like that.

Thanks,
Chris.

> On Jul 24, 2018, at 11:11 AM, Andy Bierman <[email-masked]> wrote:
>

---

From: Kent Watsen <[email-masked]>
Date: Tue, 31 Jul 2018 00:41:23 +0000

> as a side effect, such a mechanism may also be used to select between

Sounds compelling.  Reminds me of Andy's packages idea.  I'd like to see
the next level of analysis on this idea.

Kent // contributor