Subject: [Netmod-ver-dt] YANG versioning - Requirements

From: Robert Wilton <[email-masked]>
Date: Thu, 14 Jun 2018 14:25:42 +0100

I appreciate that we are still discussing the problem definition, but I 
thought that I would have a go a list of requirements, just as a draft.

They probably need a lot of work, but thought that they could be useful 
as a discussion starting point.  Feel free to comment, provide an 
alternative set, suggest improvements, reject them all, etc.

--- Requirements of a YANG versioning solution:

1. A mechanism is required to update a module in a non-backwards 
compatible way without forcing all modules that have dependencies on the 
updated module from being updated at the same time (e.g. to import a new 
module name).

2. A mechanism is required to update a module in a non-backwards 
compatible way without forcing all clients/servers to interact with the 
module using a new module names/paths.

3. It would be useful to have an import statement that is more 
restrictive than "import any version" and less restrictive than "import 
a specific version".  The aim of such an import statement is to allow 
for loose coupling between different modules.

4. Readers of modules, and tools that use modules, need to be able to 
determine whether changes between two revisions of a module constitute a 
backwards compatible or not backwards compatible version change.  In 
addition, it may be helpful to identify whether the change represents 
bug fixes, new functionality, or both.

5. A mechanism is required for a client to determine whether a 
deprecated node is implemented by the server.

6. A mechanism is required for a client to determine whether an obsolete 
node is implemented by the server.

7. If a node is deprecated or obsolete then it would be useful if the 
YANG module could indicate what alternatives exist, and possibly a 
timeline of when a deprecated node becomes obsolete.

8. The solution needs to facilitate servers supporting existing clients 
in a backwards compatible way.

9. The solution needs to allow servers to simultaneously support client 
using different versions of modules.  Choosing a particular version of a 
module may automatically restrict the particular versions of other 
modules that may be used in the same request, session, all sessions.

10. A solution is required to allow bug fixes to an older revision of 
the module without forcing it include all new published functionality. 
(E.g. it is desirable to hypothetically create a bugfix RFC 7223 without 
having to build on the module published in RFC 8343)

11. The solution should provide guidance to model authors on how to use 
the new YANG versioning schema.

Thanks,
Rob

---

From: Benoit Claise <[email-masked]>
Date: Thu, 14 Jun 2018 15:32:18 +0200

A longer than expected customer meeting. Therefore, I won't be able to 
join today's call.

Regards, B.
> I appreciate that we are still discussing the problem definition, but 
> I thought that I would have a go a list of requirements, just as a draft.
>
> They probably need a lot of work, but thought that they could be 
> useful as a discussion starting point.  Feel free to comment, provide 
> an alternative set, suggest improvements, reject them all, etc.
>
>
> compatible way without forcing all modules that have dependencies on 
> the updated module from being updated at the same time (e.g. to import 
> a new module name).
>
> compatible way without forcing all clients/servers to interact with 
> the module using a new module names/paths.
>
> restrictive than "import any version" and less restrictive than 
> "import a specific version".  The aim of such an import statement is 
> to allow for loose coupling between different modules.
>
> determine whether changes between two revisions of a module constitute 
> a backwards compatible or not backwards compatible version change.  In 
> 6. A mechanism is required for a client to determine whether an 
> obsolete node is implemented by the server.
>
> 8. The solution needs to facilitate servers supporting existing 
> clients in a backwards compatible way.
>
> 9. The solution needs to allow servers to simultaneously support 
> client using different versions of modules.  Choosing a particular 
> version of a module may automatically restrict the particular versions 
> of other modules that may be used in the same request, session, all 
> sessions.
>
> (E.g. it is desirable to hypothetically create a bugfix RFC 7223 
> without having to build on the module published in RFC 8343)
>
> 11. The solution should provide guidance to model authors on how to 
> use the new YANG versioning schema.
>
>
> Thanks,
> Rob
>
> _______________________________________________
> Netmod-ver-dt mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/netmod-ver-dt

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Thu, 14 Jun 2018 16:42:24 +0200

On Thu, Jun 14, 2018 at 02:25:42PM +0100, Robert Wilton wrote:
> 1. A mechanism is required to update a module in a non-backwards compatible
> way without forcing all modules that have dependencies on the updated module
> from being updated at the same time (e.g. to import a new module name).

I think this is driving this effort.
 
> 2. A mechanism is required to update a module in a non-backwards compatible
> way without forcing all clients/servers to interact with the module using a
> new module names/paths.

Same as above.

> 3. It would be useful to have an import statement that is more restrictive
> than "import any version" and less restrictive than "import a specific
> version". The aim of such an import statement is to allow for loose
> coupling between different modules.

I believe this is not 'useful' but 'needed' if you allow non-backwards
compatible changes.
 
> addition, it may be helpful to identify whether the change represents bug
> fixes, new functionality, or both.

Here is a problem: If bar imports foo and foo has non-backwards
compatible changes, than this does not necessarily mean bar breaks.
The bar module may not use stuff from foo that has non-backwards
compatible changes. Hence, the authors of foo can't really tell
whether bar will break or not.

Today we force an opt-in model for non-backwards compatible changes
(since there are new names) and this effort is moving to an opt-out
model where an update of foo may break bar and in that case bar broke
it has to opt-out from using that new version of foo.

> 5. A mechanism is required for a client to determine whether a deprecated

Yes, but this is actually independent of how we do deal with
non-backwards compatible changes.

> node is implemented by the server.

Yes, but this is actually independent of how we do deal with
non-backwards compatible changes.

> 7. If a node is deprecated or obsolete then it would be useful if the YANG
> module could indicate what alternatives exist, and possibly a timeline of
> when a deprecated node becomes obsolete.

Yes, but this is actually independent of how we do deal with
non-backwards compatible changes.

> 8. The solution needs to facilitate servers supporting existing clients in a
> backwards compatible way.

Yes, I believe this is an essential requirement. This is why we have the
current module update rules in the first place in RFC 7950.
 
> module may automatically restrict the particular versions of other modules
> that may be used in the same request, session, all sessions.

Yes, some reasoning as above.

> 10. A solution is required to allow bug fixes to an older revision of the
> module without forcing it include all new published functionality. (E.g. it
> is desirable to hypothetically create a bugfix RFC 7223 without having to
> build on the module published in RFC 8343)

I have no idea yet what this means relative to what we can do today.

> 11. The solution should provide guidance to model authors on how to use the
> new YANG versioning schema.

/js

-- 
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: Robert Wilton <[email-masked]>
Date: Thu, 14 Jun 2018 17:30:55 +0100

> I believe this is not 'useful' but 'needed' if you allow non-backwards
OK.  Balazs (or Joe?) also saw this is as needed.  Let's change this to 
a hard requirement.

> it has to opt-out from using that new version of foo.
Yes, I agree.

My aim here was to say that there needs to be a way to find out whether 
the changes between two revisions are backwards compatible or not.  E.g. 
tooling can do this (but can't be perfect), or extra metadata (e.g. 
sem-ver YANG statements) can be introduced (but this relies on the 
author updating it correctly).

> non-backwards compatible changes.
I agree.

> non-backwards compatible changes.
I agree.

> non-backwards compatible changes.
Agree, perhaps we should group the requirements into two (or more) sub 
lists so that the closely related requirements are grouped together.

> I have no idea yet what this means relative to what we can do today.
OK.

If say, I found a misleading description statement in RFC 7223: 
[email-masked]

Ignoring the IETF document process machinery, then it would be good if I 
could generate a fixed version of ietf-interfaces that updates revision 
2014-05-08, but doesn't pull in the changes from the NMDA revision, 
2018-02-20.

Normally, my new revision, based on 2014-05-08 but with the updated 
description, would get a current revision date, like 2018-06-14. This is 
obviously later than the NMDA revision, 2018-02-20, but doesn't include 
those nodes, so presumably breaks the 7950 module update rules?

One choice would be to lie about the revision date, e.g. call it 
2014-05-09 instead.  But at that stage it is no longer a revision date, 
but a version number instead.

Thanks,
Rob

---

From: Mahesh Jethanandani <[email-masked]>
Date: Thu, 14 Jun 2018 15:50:24 -0400

Hi Robert,

> On Jun 14, 2018, at 12:30 PM, Robert Wilton <rwilton=[email-masked]> wrote:
> 
> 
> 
> OK.  Balazs (or Joe?) also saw this is as needed.  Let's change this to a hard requirement.
> 
>>  
> My aim here was to say that there needs to be a way to find out whether the changes between two revisions are backwards compatible or not.  E.g. tooling can do this (but can't be perfect), or extra metadata (e.g. sem-ver YANG statements) can be introduced (but this relies on the author updating it correctly).

I understand that this is a requirement, but I find it hard to believe that can be solved by any tool or versioning mechanism at a module level. Say module bar updates its version to indicate a backward incompatible change somewhere in the module, how does a tool decide that module foo is impacted? Module foo would have to know that the XPath for what it uses in module bar has changed in a backward incompatible way. It is quite likely that bar has not changed the path, in which case foo may not be impacted. 

It is not clear reading the requirement that the indication of backward incompatibility is at the module level or at each node, and therefore an ability to determine incompatibility at a node level. If so, can we update the requirement to say that we need indication at a node level of what has changed in a backward incompatible way?

Thanks.

> Agree, perhaps we should group the requirements into two (or more) sub lists so that the closely related requirements are grouped together.
> 
>> 
> If say, I found a misleading description statement in RFC 7223: [email-masked]
> 
> Ignoring the IETF document process machinery, then it would be good if I could generate a fixed version of ietf-interfaces that updates revision 2014-05-08, but doesn't pull in the changes from the NMDA revision, 2018-02-20.
> 
> Normally, my new revision, based on 2014-05-08 but with the updated description, would get a current revision date, like 2018-06-14. This is obviously later than the NMDA revision, 2018-02-20, but doesn't include those nodes, so presumably breaks the 7950 module update rules?
> 
> One choice would be to lie about the revision date, e.g. call it 2014-05-09 instead.  But at that stage it is no longer a revision date, but a version number instead.
> 
> Thanks,
> Rob
> 
>>

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Fri, 15 Jun 2018 12:01:51 +0200

On Thu, Jun 14, 2018 at 05:30:55PM +0100, Robert Wilton wrote:
> 
> 
> My aim here was to say that there needs to be a way to find out whether the
> changes between two revisions are backwards compatible or not.  E.g. tooling
> can do this (but can't be perfect), or extra metadata (e.g. sem-ver YANG
> statements) can be introduced (but this relies on the author updating it
> correctly).
>

I think the key here is that a module writer can indicate that there
are non-backwards compabible changes but this does not mean that all
imports are actually affected. In other words, an author importing a
module can not really constrain the version space because at the end
even the major version number may continue to work or a change of a
minor version number may actually break things. So you have to opt out
if bad things happen.

In other words, the version number that a module writer produces is
not more than a fuzzy indicator - and the bigger the module is, the
fuzzier it becomes. I hope tools will not go wild and do bad things.

Since opt-in is expensive (requires updates and this is why we are
here), opt-out is maybe cheaper but also not without costs, in
particular for organizations with non-agile processes like the IETF.
One option could be to actually factor out the import versioning stuff
such that a package or bundle or whatever you want to call it takes
care of this, i.e., a small artefact that lives outside the YANG
module definitions (like maintained by IANA for the IETF case).  This
way, if I publish a new module foo which may include non backwards
compatible changes, I can go and update the compatibility contraints
without having to actually touch the modules.

Yes, maintaining such meta-data outside the modules comes with its own
share of problems but we already do that when it comes to the question
which schemas in the different datastores supported by a server.

> One choice would be to lie about the revision date, e.g. call it 2014-05-09
> instead.  But at that stage it is no longer a revision date, but a version
> number instead.

Yes, the RFC 7950 versioning model assumes that there is a linear
evolution of a module and that essentially every newer module is
backwards compatible to older modules. This work is breaking this
assumption and this means that revision dates are less useful (and all
references to revision dates need to be carefully considered and
perhaps replaced by something else).

/js

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Fri, 15 Jun 2018 12:06:07 +0200

> It is not clear reading the requirement that the indication of backward incompatibility is at the module level or at each node, and therefore an ability to determine incompatibility at a node level…

I basically agree that a module version is a rather course grained
indicator. That said, even if a node has not changed, it may still be
impacted by semantic changes of nodes "around it". At the end, there
is going to be a need for some human intelligence or you
optimistically assume things will be fine and we are all ready to
accept that occasionally bad things may happen.

/js

---

From: Robert Wilton <[email-masked]>
Date: Fri, 15 Jun 2018 11:39:41 +0100

> I understand that this is a requirement, but I find it hard to believe that can be solved by any tool or versioning mechanism at a module level. Say module bar updates its version to indicate a bac…
But to answer your specific question, the naive answer is that you 
compile module foo (inc xpath expressions) against the new version of 
the module and check whether there are any compile errors or new warnings.

So, one observation here is that knowing whether or not a change is 
backwards compatible doesn't prevent things from breaking.  It just 
flags up the potential breakage to (i) make it easier for humans to 
update and modules that may have got broken, (ii) potentially to 
explain/justify why backwards incompatible changes have been made (e.g. 
via a revision statement), and (iii) perhaps most importantly, to flag 
up backwards incompatible changes that cannot be discovered via tooling 
(e.g. a change in the semantics defined by the description statement).

I think that RFC 7950 section 11 has a pretty good definition of what a 
backwards compatible change is, and hence by implication what a 
backwards incompatible change is.  I think that tooling (e.g. pyang) can 
generally spot a lot of backwards incompatible changes (e.g. path 
changes, type changes, value set changes).  For other changes between 
module version, tooling probably cannot spot whether a change is 
backwards compatible or not (e.g. changes to description 
statement,'must' or 'when' expressions), but a tool would at least be 
able to flag changes to those nodes to a user who can apply the rules of 
7950 sec 11 to determine whether a change is backwards compatible or 
not.  Hence, I think that having something like a semantic version 
statement is required to cover the cases that tooling cannot catch.  Of 
course, this also relies on individuals updating the version number 
appropriately.  But a user who compares two module versions potentially 
has both mechanisms at their disposal.

> It is not clear reading the requirement that the indication of backward incompatibility is at the module level or at each node, and therefore an ability to determine incompatibility at a node level…

This is sort of an interesting idea, and perhaps worth discussing further.

My instinct is that this could end up being too granular and it might be 
difficult to see the wood from the trees.  I also wonder whether this 
would make it harder for folks to get this right.  E.g. rather that just 
having to update a version number on a per module basis, it would be 
necessary to check that it is right for all nodes.  But conversely, one 
advantage is that it would then allow a module updater to flag a major 
version change due to a change in a data nodes semantics described in 
description statement, that might otherwise be missed.

If per schema data node version information was allowed, then 
consideration would be needed on how that propagates up the tree to the 
parent nodes.  E.g. if I have two sibling leaves, and leaf A is updated 
from V1.1.0 to V1.1.2 and leaf B is updated from V1.1.0 to V2.0.0 then 
what would the version of the parent node be, I would surely have to 
take V2.0.0, but is that obviously the right thing to do?

I think that this would be quite complicated.

In conclusion I think that backwards compatibility has to be flagged at 
least at the module level.  If there is a sane/pragmatic way to flag it 
on a per data node basis without causing too much complexity/noise/etc, 
that would seem like a "nice to have" rather than a "must have".

Thanks,
Rob

> .

---

From: Robert Wilton <[email-masked]>
Date: Fri, 15 Jun 2018 12:03:48 +0100

> minor version number may actually break things. So you have to opt out
Possibly this can worth both ways.

The clacla draft defines a "non backwards compatible change" as a "major 
version change".  I'm not yet 100% convinced that this is the right 
thing to do.

E.g. one particular question I have is: Does every non-backwards 
compatible change get flagged as a major version change? Specifically, I 
am thinking of a bug fix like fixing a regex to exclude a value that it 
should not have allowed.

I guess that my instinct is that this should not be a major version 
change, but instead is equated to a "patch".   If this sort of change is 
not a major version change then it may be that an import restricting it 
to a particular major version, but any minor/patch version is OK, i.e. 
if the major version is expected to churn infrequently.

> without having to actually touch the modules.
I don't know whether this is a good idea or not, but Benoit has long 
talked about allowing minor updates to YANG modules without requiring 
the weight/time of the full IETF process.

If the linkage is factored out then I think perhaps the "opt-out" or 
"opt-in" schema may both work.

>>>> module without forcing it include all new published functionality. (E..g. it
I agree.

Thanks,
Rob

---

From: Balazs Lengyel <[email-masked]>
Date: Fri, 15 Jun 2018 13:39:05 +0200

Hello,

In my world if anything in a module changes in an incompatible
way then (to be safe) we consider the whole  module incompatible.
IMHO data node level compatibility would be a hassle to document,
check, administer.

My proposed solution would allow an importer to specify which
version (semver) it accepts for importing. You would be able to
specify      import foo { semver ...}

5.x.x : any version that is compatible with 5.0.0. This means
that if  bar imports foo and foo has non-backwards
compatible (NBC) changes the semver for foo will go to 6.0.0
which can not be imported. bar has to opt-in, you have to
actually change bar to allow it to import foo 6.y.y.

5+.x.x: any version that is compatible with 5.0.0 or any other
version with major > 5. This means if foo has an NBC change
bumping its semver to 6.0.0 it is still usable. This is the
opt-out model, you have to change bar if you want to avoid using
foo 6.y.y

5.x.x - 7.x.x : any version that is compatible with 5.0.0 or
6.0.0 or 7.0.0, but no version having a major version > 7.
This could happen if you are using an opt-in model with 5.0.0
but later update your module to indicate that you accept 6.y.y
and 7.z.z. You checked the NBC changes between 5,6 and 7 and all
are fine, but changes done to 8.0.0 are not acceptable.

So as I see it semver would allow both the opt-in and the opt-out
model.

In Ericsson we also have an extension that designates a module as
an import-only library module (something like yang-types). For
this we follow very strict compatibility rules which means that
importers can freely use the opt-out model.

regards Balazs

On 6/15/2018 12:06 PM, Juergen
Schoenwaelder wrote:

/js

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

---

From: Balazs Lengyel <[email-masked]>
Date: Fri, 15 Jun 2018 13:45:34 +0200

Hello,

While requirement 5, 6, 7 could be handled without introducing
semver, I believe these are issues that both

make semver more needed as non-backwards compatible - NBC
changes are more frequent with deprecation/obsoletion

are needed to make semver work. If you don't know whether a
deprecated data node is present, you can't decide if a change is
compatible or not

regards Balazs

On 6/14/2018 4:42 PM, Juergen
Schoenwaelder wrote:

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Fri, 15 Jun 2018 13:59:00 +0200

On Fri, Jun 15, 2018 at 11:39:41AM +0100, Robert Wilton wrote:
> 
> But to answer your specific question, the naive answer is that you compile
> module foo (inc xpath expressions) against the new version of the module and
> check whether there are any compile errors or new warnings.
> 
> backwards compatible doesn't prevent things from breaking.  It just flags up
> the potential breakage to (i) make it easier for humans to update and
> modules that may have got broken, (ii) potentially to explain/justify why
> backwards incompatible changes have been made (e.g. via a revision
> statement), and (iii) perhaps most importantly, to flag up backwards
> incompatible changes that cannot be discovered via tooling (e.g. a change in
> the semantics defined by the description statement).
> 
> backwards compatible change is, and hence by implication what a backwards
> incompatible change is.  I think that tooling (e.g. pyang) can generally
> spot a lot of backwards incompatible changes (e.g. path changes, type
> changes, value set changes).  For other changes between module version,
> tooling probably cannot spot whether a change is backwards compatible or not
> (e.g. changes to description statement,'must' or 'when' expressions), but a
> tool would at least be able to flag changes to those nodes to a user who can
> apply the rules of 7950 sec 11 to determine whether a change is backwards
> compatible or not.  Hence, I think that having something like a semantic
> version statement is required to cover the cases that tooling cannot catch. 
> Of course, this also relies on individuals updating the version number
> appropriately.  But a user who compares two module versions potentially has
> both mechanisms at their disposal.

The semantic version number is only a fuzzy indicator; only a concrete
usage context can determine whether a given change is backwards
compatible for this usage context or not.

> difficult to see the wood from the trees.  I also wonder whether this would
> make it harder for folks to get this right.  E.g. rather that just having to
> update a version number on a per module basis, it would be necessary to
> check that it is right for all nodes.  But conversely, one advantage is that
> it would then allow a module updater to flag a major version change due to a
> change in a data nodes semantics described in description statement, that
> might otherwise be missed.
> 
> If per schema data node version information was allowed, then consideration
> would be needed on how that propagates up the tree to the parent nodes. 
> E.g. if I have two sibling leaves, and leaf A is updated from V1.1.0 to
> V1.1.2 and leaf B is updated from V1.1.0 to V2.0.0 then what would the
> version of the parent node be, I would surely have to take V2.0.0, but is
> that obviously the right thing to do?
> 

Perhaps it helps to look at other systems. When OSes moved to dynamic
shared libraries, they started to version the library. Meanwhile, the
Gnu C library even has versions at the symbol level and a mapping
mechanism that resolves an external symbol reference to a specific
versioned symbol.

> least at the module level.  If there is a sane/pragmatic way to flag it on a
> per data node basis without causing too much complexity/noise/etc, that
> would seem like a "nice to have" rather than a "must have".

I think that ultimately you will need fine grained versioning but
perhaps it is good enough to solve module versioning now and if YANG
continues to be successful, others can solve the more fine grained
versioning a couple of years down the road. But we should be careful
with our statements, semantic versioning of modules is not solving all
problems, and people should understand what a version number means and
what it does not mean (i.e., a major version number change does not
necessarily break my module and a minor version number change can, in
hopefully rare cases, break my module).

/js

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Fri, 15 Jun 2018 14:18:12 +0200

On Fri, Jun 15, 2018 at 12:03:48PM +0100, Robert Wilton wrote:
> version change".  I'm not yet 100% convinced that this is the right thing to
> do.
>

I think it is not.

> E.g. one particular question I have is: Does every non-backwards compatible
> change get flagged as a major version change? Specifically, I am thinking of
> a bug fix like fixing a regex to exclude a value that it should not have
> allowed.

We may have different understandings of the purpose of regexes. I believe
they do not have to cover all cases (and they actually can't in general
because they are restricted to regular languages).

> I guess that my instinct is that this should not be a major version change,
> but instead is equated to a "patch".   If this sort of change is not a major
> version change then it may be that an import restricting it to a particular
> major version, but any minor/patch version is OK, i.e. if the major version
> is expected to churn infrequently.

A great example from the SNMP world is this errata:

https://www.rfc-editor.org/errata_search.php?rfc=3433

I think this came up again when the corresponding YANG model was
produced (which is now RFC 8348).

> I don't know whether this is a good idea or not, but Benoit has long talked
> about allowing minor updates to YANG modules without requiring the
> weight/time of the full IETF process.

We talked about this within OPS even back in the days when MIB modules
were still a hot topic. If I would have time, I would perhaps join the
tools team to get one of the github clones running on IETF servers and
then we could slowly but surely move towards proper version controlled
development and maintenance on IETF owned infrastructure. The support
of Trac years ago was a step into the right direction, unfortunately
using a version control system that did not succeed. The only way to
change something in the IETF is to build something that works better.

> "opt-in" schema may both work.

Likely the difference between the two is much smaller then.

/js

---

From: Balazs Lengyel <[email-masked]>
Date: Fri, 15 Jun 2018 14:49:21 +0200

Hello,

IMHO we seem to agree on that

A major revision change for a module means: At least one thing
in the module changed in a non-backwards compatible (NBC) way

This means a user of the module (importer module or client
application) might break. On the other hand a user might also
"not break" depending on how it uses the changed module. If the
major version did not change (and the minor version only
increased) all users are assured that they can still use the
module.

Maybe we should differentiate between

syntactical compatibility which is about changes allowed to
the statements without considering their use and the
functionality behind them and

functional compatibility which considers the full use-case for
the data nodes.

In this sense correcting a faulty regexp is syntactically
non-backwards compatible (NBC) while functionally it is
compatible.

regards Balazs

On 6/15/2018 2:18 PM, Juergen
Schoenwaelder wrote:

I think it is not.

/js

---

From: Balazs Lengyel <[email-masked]>
Date: Fri, 15 Jun 2018 14:59:04 +0200

Hello,

From RFC 6244: "Ease
of use: YANG is designed to be human friendly, simple, and
readable."

What would happen with readability if every node could have
versioning information attached?

You could have versioning attached to just a whole network device
or you could have versioning attached to every schema node. Today
we have it attached to the modules which IMHO is a good compromise
between too much details and too little.

regards balazs

On 6/15/2018 1:59 PM, Juergen
Schoenwaelder wrote:

/js

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Fri, 15 Jun 2018 15:16:44 +0200

On Fri, Jun 15, 2018 at 02:49:21PM +0200, Balazs Lengyel wrote:
>      * A major revision change for a module means: At least one thing in the
>        module changed in a non-backwards compatible (NBC) way
>      * This means a user of the module (importer module or client
>        application) might break. On the other hand a user might also "not
>        break" depending on how it uses the changed module. If the major
>        version did not change (and the minor version only increased) all
>        users are assured that they can still use the module.

I am not sure there is an assurance or you have to explain what that
exactly means. I believe bug fixes may actually then be NBCs. There
are subtle corner cases where the module maintainer may decide the
change is a minor bug fix but still some application will be surprised
by the changed (fixed) behavior. The subtle cases are usually forms of
contradictions where you end up speculating what people might have
implemented (a wrongly labeled enum, a contradiction between a type
restriction and the description statement, ...).

I personally believe that the categorization into major, minor, ... is
at the end of the day a judgement call for certain changes and hence
for me "users are assured" sounds too strong for me.

/js

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Fri, 15 Jun 2018 15:22:14 +0200

On Fri, Jun 15, 2018 at 02:59:04PM +0200, Balazs Lengyel wrote:
> 
>    You could have versioning attached to just a whole network device or you
>    could have versioning attached to every schema node. Today we have it
>    attached to the modules which IMHO is a good compromise between too much
>    details and too little.
>

Yes, but then a module version number does not tell you whether
another module is affected by a version number change or not. As I
said, this granularity is likely fine for now and I am not proposing
anything more granular - as long as we do not fall into the trap to
make claims about version numbers that are not necessarily always
true.

/js

---

From: Robert Wilton <[email-masked]>
Date: Fri, 15 Jun 2018 14:36:52 +0100

> for me "users are assured" sounds too strong for me.
This is perhaps the way that I'm leaning too.

Strict semver (as described by https://semver.org/) defines:

Given a version number MAJOR.MINOR.PATCH, increment the:

 1. MAJOR version when you make incompatible API changes,
 2. MINOR version when you add functionality in a backwards-compatible
    manner, and
 3. PATCH version when you make backwards-compatible bug fixes.

However, I wonder whether a better definition for YANG versioing isn't a 
bit softer than that, e.g, something along the lines of:

Given a version number MAJOR.MINOR.PATCH, increment the:

 1. MAJOR version when significant changes are made, or changes that are
    likely to cause version incompatibilities for clients or other
    importing YANG modules.
 2. MINOR version when new functionality is added that is not expected
    to cause version incompatibilities for clients or other importing
    YANG modules.
 3. PATCH version when bug fixes are made that are not expected to cause
    version incompatibilities for clients or other importing YANG modules.

Thanks,
Rob

---

From: Balazs Lengyel <[email-masked]>
Date: Fri, 15 Jun 2018 15:49:45 +0200

> for me "users are assured" sounds too strong for me.
BALAZS: Yes and yes.
Keeping the major number should be an assurance that things don't break. 
If I used module foo version x.y.z and I move to using version x.a.b 
instead my functionality (importing module or client SW) will not be 
affected as long it is the same x major version and a > y minor version.
Yes it is a judgement. People may use or misuse strange behavior or even 
faults. In some cases it is easy to say an IPv4 address starting with 
444. is a bug. In other cases it is more difficult. So we have a rule: 
If in doubt, declare it NBC increase the major version.
regards Balazs

---

From: Balazs Lengyel <[email-masked]>
Date: Fri, 15 Jun 2018 15:55:21 +0200

On 6/15/2018 3:36 PM, Robert Wilton wrote:

Hello,

Strict semver (as described by https://semver.org/)
defines:

Given a version number
MAJOR.MINOR.PATCH, increment the:

MAJOR version when you make incompatible API changes,

MINOR version when you add functionality in a
backwards-compatible manner, and

PATCH version when you make backwards-compatible bug fixes.

However, I wonder whether a better definition for YANG versioing
isn't a bit softer than that, e.g, something along the lines of:

Given a version number
MAJOR.MINOR.PATCH, increment the:

MAJOR version when significant changes are made, or changes
that are likely to cause version incompatibilities for clients
or other importing YANG modules.

MINOR version when new functionality is added that is not
expected to cause version incompatibilities for clients or
other importing YANG modules.

PATCH version when bug fixes are made that are not expected
to cause version incompatibilities for clients or other
importing YANG modules.

Thanks,

Rob

Significant is not a well defined term. Also if I add 100 new
typedefs to ietf-yang-types that's a significant update, but still a
backward compatible one, so why increase the major version.

IMHO semver is fine with the addition of the rule: If in doubt about
compatibility increase the major version.

I want to ASSURE users that if major number is not changed they are
safe, so if there is any doubt increase the major number.

regards Balazs

---

From: Robert Wilton <[email-masked]>
Date: Mon, 18 Jun 2018 11:47:39 +0100

Hi Balazs,

On 15/06/2018 14:49, Balazs Lengyel wrote:
> Keeping the major number should be an assurance that things don't 
> break. If I used module foo version x.y.z and I move to using version 
> x.a.b instead my functionality (importing module or client SW) will 
> not be affected as long it is the same x major version and a > y minor 
> version.

I don't think that this statement is quite true.  I.e. even in this 
scenario the semantic version number is not sufficient to ensure 
compatibility:

What if the client is relying on a bug fix that is present in x.y.z, but 
not in x.a.b?  This could cause a client to break.  E.g. because a 
particular leaf value is allowed in x.y.z (by the ".z" bug fix revision) 
but not x.a.b (because the ".z" bug fix hasn't been merged into x.a.b).

It is also the case that a major version change may not cause a problem 
to a client, since it depends on which subset of a module it is actually 
using.  E.g. if a non backwards compatible change is made to a leaf that 
a client doesn't use then it probably doesn't care that the module has 
been updated in a backwards incompatible way.  This is why I think that 
there is some merit to Mahesh's suggestion of allowing some level of 
versioning information to be specified on a per data node basis (and no, 
I don't think that we should be labeling every data node, only where it 
is necessary ;-).

Hence, I don't think semantic versioning gives a hard guarantee between 
compatibility.

This is also why I am suggesting that the versioning triple provided at 
the module level should perhaps be there to providing guidance and 
assistance (to a human), rather than being definitive.  Instead, can we 
rely on tooling to determine what has changed between two revisions, and 
determine whether or not those changes are backwards compatible between 
two module revisions?  I know that under some circumstances a 
programmatic diff between two schema isn't sufficient today (e.g. 
changes in description, must, when), but if we added a new per data node 
version statement that is used to flag non backwards compatible changes 
that won't be detected by tooling, then would we be able to get to the 
point where a tool based approach is entirely robust?

I.e. so a client could use tooling to definitively answer the question: 
Are there any non backward compatible changes going from x.y.z. to 
a.b.c, when using a particular subset of the schema nodes?

Thanks,
Rob

> Yes it is a judgement. People may use or misuse strange behavior or 
> even faults. In some cases it is easy to say an IPv4 address starting 
> with 444. is a bug. In other cases it is more difficult. So we have a 
> rule: If in doubt, declare it NBC increase the major version.
> regards Balazs
>

---

From: Joe Clarke <[email-masked]>
Date: Mon, 18 Jun 2018 10:21:54 -0400

> but not x.a.b (because the ".z" bug fix hasn't been merged into x.a.b).

But if the bug fix breaks backwards compatibility, then x must become
x+1.  That is, if the leaf definition shrinks in scope, then this gets a
major bump.

There's been a lot of discussion on this thread while I was out of the
office last week.  I've said on calls before that I see no reason not to
bump major version numbers for even small NBC changes.  To me, this is
more like a shared object version and less like a software application
revision.

> a.b.c, when using a particular subset of the schema nodes?

I would not be opposed to _eventually_ moving to something akin to
symbol versioning down the line.  I can see value there as well.  I
think we should skip to module-level versioning for now.

Joe

---

From: Robert Wilton <[email-masked]>
Date: Mon, 18 Jun 2018 16:38:34 +0100

Hi Joe,

> x+1.  That is, if the leaf definition shrinks in scope, then this gets a
Alas, it breaks even if it is backwards compatible change!

E.g.
in x.y.(z-1) leaf "foo" supports range 1-10.

However, it turns out this is a mistake in the model, and the range 
should be 1-12 instead, so a fix is made in version x.y.z to increase 
the range to 1-12.   This is a backwards compatible change, so no bump 
to the major version number is required.  The client is coded to support 
version x.y.z with the increased range.

Now the client wants to move to a new release of the software that is 
running version x.a.b, a > y.  Unfortunately, this software doesn't have 
the fix to increase the range to 1-12 yet, so when the client goes to 
write 12 to leaf foo the config fails, it isn't compatible.  The client 
has been broken even though the version numbers indicate that upgrade 
should be safe ...

I.e. the semantic version numbers do not give you upgrade safety.

> more like a shared object version and less like a software application
I'm still not sure that is a good idea.

Let's consider a variant of the example above.

This time, it turns out that the bug was that the range should have been 
1-8 rather than 1-10 that was specified in the original model. OK, so 
fixing this is clearly an NBC change, so you can force the version 
change to be (x+1).0.0.  But now this new major version is missing the 
new nodes introduced in x.a.b.  Hum, that seems strange, it seems that 
we are going backwards.  So, perhaps this means that version (x+1) also 
has to include the changes in x.a.b.  But that may not be what is wanted 
at all.  All that was wanted was a version of the original version x.y.z 
that had the bug fix.

So, I think that forcing a major version change on a NBC bug fix is not 
necessarily the right thing to do.  Sometimes it might be, other times 
perhaps not.

I guess that I'm saying that I'm not convinced that semantic versioning, 
e.g. as defined by https://semver.org/, quite works for YANG.  I think 
that it sort of close, but I think (at least) that non-backwards 
compatible bug fixes should be allowed without forcing a major version 
change.  Instead, if it is a bug fix to version x.y.z then the right 
solution is to call the version with the bug fix x.y.z+1, which seems 
intuitively correct, and handle the non backwards compatibility of the 
change in a different way (e.g. as proposed below).

> think we should skip to module-level versioning for now.
As per my comments above, I don't think that module level versioning is 
sufficient to robustly solve the versioning problem.

Hence I think that the solution could use module level versioning to 
express the authors intent, and also per data node level versioning is 
used to determine whether nbc changes to the data model are being made.

Thinking about this some more, I think that perhaps all is required is a 
statement like "nbc-change <rev-date>" that can be added under any leaf, 
leaf-list, container, etc.  This statement is used only when a 
description, must, or when statement has been changed in a non-backwards 
compatible way.

So now, when two versions of a model are being compared, if the 
description, must, or when statements have been changed between the two 
versions, then it can also check if one of the data node has a 
nbc-change statement, or both have nbc-change statements with different 
revision dates, and in either of these cases it declares the node 
difference as being nbc.  So tooling can determine whether a particular 
node has been changed in an nbc way, and hence whether the module has 
any nbc changes.

This same mechanism can also be used by tooling to help ensure (through 
appropriate warnings) that the module level "major.minor.patch" is being 
updated correctly.

Thanks,
Rob

---

From: Joe Clarke <[email-masked]>
Date: Mon, 18 Jun 2018 12:01:25 -0400

> I.e. the semantic version numbers do not give you upgrade safety.

In the clacla draft, we have proposed an imports scheme that attempts to
address this.  When Balasz and I spoke with Martin after netmod 101, we
discussed this kind of branching and merging, and thus the scheme in
clacla allows to be very specific in how a module is imported by its
version.

In your example above, let's assume X = 1, Y = 1, and Z = 1.  So, the
buggy version is 1.1.0.  1.1 was branched to 1.2 to do some feature
work.  The bug was fixed in 1.1.1, but 1.2.3 (on the dev branch) doesn't
have it yet.  A client could therefore be coded with needing 1.1.n where
n >= 1 or 1.2.r where r >= 4 (let's say 1.2.4 incorporated the fix).

An import by version can be incorporated even if NBC is not considered.
Meaning, I think we have to look at something like this (maybe not
exactly how clacla specifies it, but it is lacking).

> description, must, or when statement has been changed in a non-backwards

Well, the 'c' in this case is already "change", so maybe nb-change :-).

> node has been changed in an nbc way, and hence whether the module has

In your previous post, you said that semver breaks down for a _subset_
of the nodes (or rather the types of changes).  I agree with this.
Because even if I see an X+1 major version, the nodes I use may not be
affected.  And while I could diff those nodes functionally, I wouldn't
detect changes to, for example, description.

This per-node flag seems reasonable to me for cases where tooling cannot
already determine NBC.

Joe

---

From: Robert Wilton <[email-masked]>
Date: Mon, 18 Jun 2018 18:00:50 +0100

> clacla allows to be very specific in how a module is imported by its
I think that fixing the import statement only solves a tangential 
problem.  It doesn't solve the problem that a client cannot determine 
from a version number alone whether an upgrade is safe or not, and I 
thought that was meant to be the major benefit of using semantic 
versioning in the first place.

In short, I think that the premise behind semantic versioning is 
somewhat flawed, and an implication of the semantic versioning scheme is 
that you can _never_ make a non backwards compatible bug fix to an older 
release (major or minor).  The only option that works with the semver 
scheme is that the client migrates to the latest module version, which 
can then have the bug fix applied, potentially as a major version change.

Here is an issue on the semver github repro that describes the problem 
in more detail: https://github.com/semver/semver/issues/395, also 
https://github.com/zzzprojects/html-agility-pack/issues/74

> n >= 1 or 1.2.r where r >= 4 (let's say 1.2.4 incorporated the fix).
Yes, but they can't determine this from the version numbers alone.

> Well, the 'c' in this case is already "change", so maybe nb-change :-).
I was assuming it was "compatible", but I'm not wedded to any particular 
naming ;-)

Thanks,
Rob

---

From: Joe Clarke <[email-masked]>
Date: Mon, 18 Jun 2018 15:42:53 -0400

> https://github.com/zzzprojects/html-agility-pack/issues/74

Agreed that import itself is tangential, but the problem it's trying to
solve is similar.  I can't assume that because 2.0.0 is greater than
1.3.4 that all of the fixes in 1.3.4 have been merged into 2.0.0.
You're right that especially with an API this gets messy if you have to
do some non-backwards compatible in 1.x

While Martin, Balasz, and I discussed parallel branches of a given YANG
module, that requirement is currently not on the list.  Today, there is
only a single "released" version and typically a single development
branch (such as in a bis).

Not that we have to follow that model, but how does OpenConfig address
this in their development?

> I was assuming it was "compatible", but I'm not wedded to any particular

Ha, yeah.  I guess in my head, I was creating a German aggregation word.
 That's why I've tended to spell it out in the past.

Joe

---

From: Robert Wilton <[email-masked]>
Date: Tue, 19 Jun 2018 11:57:16 +0100

> do some non-backwards compatible in 1.x
Yes, and a YANG model is effectively acting as an API between client and 
server.
> module, that requirement is currently not on the list.
This requirement was meant to be captured by "10. A solution is required 
to allow bugfixes to an older revision of the module without forcing it 
include all new functionality. (E.g. is it possible to fix a bug in RFC 
7223 without having to build on RFC 8343)"

I will try and rewrite this to be a bit more clear, Juergen had also 
questioned what it meant.

>    Today, there is
For RFCs there are also errata which seem to be broadly equivalent to a 
bug fix.

I think that it will always be the case that standard models will change 
relatively slowly.  But if NMDA had happened 2 years later, and YANG 
versioning had happened, then I could easily imagine a pre-NMDA set of 
models coexisting with a post-NMDA set of models. Possibly the answer 
for that scenario would have been to use separate module names for 
pre-NMDA models vs post-NMDA models.  But then it is a bit unclear 
exactly when using a new major version number is the right choice vs a 
new module name.  My thinking had been that if they can sensibly coexist 
in the same implementation at the same time then they should be 
different module names, otherwise the same module name is better.

Considering vendor models I think that it is very likely that they will 
be multiple active releases, and customers want longevity in both the 
models and releases.  It seems very likely that a customer may want a 
bug fix for an existing model without needing to upgrade to the latest 
model, which would quite probably also necessitate them upgrading to the 
latest release of the software.  So, I think that there is a important 
requirement to be able to add bug fixes to older software.

It seems to me that semver works OK if everyone can move to the latest 
version quite quickly, and mostly support is focused on the latest version.

But the semver rule about a nbc bugfix requiring a major version change 
seems disingenuous to me, in that I don't think that it really works 
well.   Or to put it another way, it means that all major version 
numbers are not really related to each other (e.g. you cannot assume 
that version 16.0.0 of the software is "more advanced" than version 
9_._, because version 16 might have been a bug fix for version 7.x.y.  
This feels very counter intuitive to me.

Perhaps the generic semver rules could have been better stated as 
"projects must not release code with any bugs, but bug fixes are not 
allowed by the versioning scheme" ;-)

> this in their development?
I don't know.  My instinct is that they would do whatever is needed to 
solve the issue, regardless of whether that broke the semver rules.  
E.g. if the choice is whether to do a small non backwards compatible bug 
fix that is unlikely to break anyone vs having to rev everything as a 
major version, I know which option I would put my money on them doing ;-).

Thanks,
Rob

---

From: Joe Clarke <[email-masked]>
Date: Tue, 19 Jun 2018 09:59:35 -0400

> Yes, and a YANG model is effectively acting as an API between client and

Fully agree.

> questioned what it meant.

Thanks.  This was not clear to me, either.

> For RFCs there are also errata which seem to be broadly equivalent to a

But there would still only be one "active" module version.  That is, if
1.1.0 was out and errata was found, it would move to 1.1.1 or maybe even
2.0.0.  Even if a bis version was in the works, it wouldn't be released,
and it could move to 3.0.0 before final publication.

I did read ahead, and you're right that in the vendor world, this is not
as clean.

> different module names, otherwise the same module name is better.

That does make sense.  Where it breaks down is with the desire to move
users to new pastures.  This points to the requirement about clearly
pointing users to new implementations.

> This feels very counter intuitive to me.

While I have always been in the camp of using semver as a hint to
identify the type of changes between modules, I agree that these types
of jumps are counter-intuitive.

But if the goal is to hint to a client that specific types of changes
have happened between versions, this still works.

> allowed by the versioning scheme" ;-)

Perfect.  You solved it! :-).

> major version, I know which option I would put my money on them doing ;-).

That may very well be the case.

Joe

---

From: Robert Wilton <[email-masked]>
Date: Tue, 19 Jun 2018 16:15:14 +0100

> and it could move to 3.0.0 before final publication.
It's not this jump that concerns me.

My concern is that the bis version becomes version 2.0.0, and the 
patched 1.1.0 because version 3.0.0.  This seems like a bad thing to 
do.  Folks are naively going to assume that 3.0.0 is the latest and 
greatest version, when it is not.

> of jumps are counter-intuitive.

I think that there are two plausible solutions here (if we want 
something like semver, but also want to ensure the major version number 
is sane):

(1) Ban non backwards compatible bug fixes to anything except the latest 
major.minor release (which can still sanely be represented as a major 
version change).
(2) Introduce a new variant of semver that allows non backwards 
compatible bug fixes to be flagged.

---

Explaining option (1) in more detail, I think that the rules would be 
(e.g. modified from the clacla draft, and with the PATCH version rules 
closer to  how they are defined in semver.org):

    o  x is the MAJOR version.  It is incremented when the new version of
       the specification is incompatible with previous versions.

    o  y is the MINOR version.  It is incremented when new functionality
       is added in a manner that is backward-compatible with previous
       versions.  This includes backwards compatible bug fixes, such as
       increasing the range of values allowed by a leaf.

    o  z is the PATCH version.  It is incremented only for bug fixes that
       do no change the semantic meaning of the YANG definition in anyway.
       E.g. it can be used to fix spelling mistakes or grammatical errors
       in description statements.

None backwards compatible bug fixes are only allowed for the most current MAJOR.MINOR version, and must be reported by incrementing the MAJOR version number, i.e. going from x.y.z to x+1.0.0.

Note, using the above definition also effectively fixes the import 
versioning issue of going from x.y.z to x.y+1.a, since the YANG model 
for x.y.z must be identical to x.y.0, and hence x.y+1.s must contain all 
content in x.y.0.

----

(2) My second proposed solution is to have an explicit way to indicate 
that a bug fix is not backwards compatible, which I have named 
"Semver-X", and allows non backwards compatible bug fixes to older 
versions :-)

    o  x is the MAJOR version.  It is incremented when new functionality
       is added in a manner that is not backwards compatible with
       previous versions.

    o  y is the MINOR version.  It is incremented when new functionality
       is added in a manner that is backward-compatible with previous
       versions.

    o  z is the PATCH version.  It is incremented when bug fixes are made
       in a backward-compatible manner.  If the bug fix is not backwards
       compatible then this PATCH version, and all future PATCH versions
       for the given "x.y._" version number is appended with the
       letter 'X' to indicate that it is not backwards compatible with
        x.y.0 .  E.g. a non backwards compatible bug fix to version
       "1.3.1" would be indicated using version "1.3.2X"

This variant of Semver allows non backwards compatible bug fixes to be 
easily reported without forcing a new major version number.

----

Which variant may be more appropriate probably depends on whether 
supporting non backwards compatible bug fixes to older releases is a 
requirement or not.

> have happened between versions, this still works.
But I think that it will cause too much confusion.

Consider XR, which release is newer: 3.0.1, or 4.5.1?  Most people would 
think that release 4.5.1 is the more current software, but if XR was 
using semver that might not be the case at all.  As a concept I think 
that this is really counter intuitive (aka wrong).

> Perfect.  You solved it! :-).
Excellent.  Design team done ;-)

Rob

---

From: "Reshad Rahman (rrahman)" <[email-masked]>
Date: Tue, 19 Jun 2018 15:27:15 +0000

<Just caught up with the email discussions>

My understanding (summarized) of the consensus so far:
- We're not looking into node level versioning "for now", goal is still module-level versioning
- We need to consider branches of YANG modules, a backwards-compatible fix (e.g. range increase) which goes in 1.1.3 isn't necessarily in 1.2.0. 

Regards,
Reshad,

On 2018-06-19, 6:57 AM, "Netmod-ver-dt on behalf of Robert Wilton" <[email-masked] on behalf of rwilton=[email-masked]> wrote:

    

    

    

    Thanks,
    Rob

---

From: "Reshad Rahman (rrahman)" <[email-masked]>
Date: Tue, 19 Jun 2018 15:30:07 +0000

Rob, I’ll read your proposed solutions later today. One question I have is wrt use of tools (we’ve discussed this a bit on the alias). I realize tools won’t be able to catch everything but I do hope that, whatever strategy/recommendation we end up with, we will have requirements for tools also?

Regards,
Reshad.

From: Netmod-ver-dt <[email-masked]> on behalf of Robert Wilton <rwilton=[email-masked]>
Date: Tuesday, June 19, 2018 at 11:15 AM
To: Joe Clarke <jclarke=[email-masked]>, Balazs Lengyel <[email-masked]>, Juergen Schoenwaelder <[email-masked]>
Cc: "[email-masked]" <[email-masked]>
Subject: Re: [Netmod-ver-dt] YANG versioning - Requirements

can then have the bug fix applied, potentially as a major version

change.

server.

Fully agree.

   Today, there is

bug fix.

My concern is that the bis version becomes version 2.0.0, and the patched 1.1.0 because version 3.0.0.  This seems like a bad thing to do.  Folks are naively going to assume that 3.0.0 is the latest and greatest version, when it is not.

as clean.

I think that there are two plausible solutions here (if we want something like semver, but also want to ensure the major version number is sane):

(1) Ban non backwards compatible bug fixes to anything except the latest major.minor release (which can still sanely be represented as a major version change).
(2) Introduce a new variant of semver that allows non backwards compatible bug fixes to be flagged.

---

Explaining option (1) in more detail, I think that the rules would be (e.g. modified from the clacla draft, and with the PATCH version rules closer to  how they are defined in semver.org):

Note, using the above definition also effectively fixes the import versioning issue of going from x.y.z to x.y+1.a, since the YANG model for x.y.z must be identical to x.y.0, and hence x.y+1.s must contain all content in x.y.0.

----

(2) My second proposed solution is to have an explicit way to indicate that a bug fix is not backwards compatible, which I have named "Semver-X", and allows non backwards compatible bug fixes to older versions :-)

      previous versions.

      versions.

This variant of Semver allows non backwards compatible bug fixes to be easily reported without forcing a new major version number.

----

Which variant may be more appropriate probably depends on whether supporting non backwards compatible bug fixes to older releases is a requirement or not.

Consider XR, which release is newer: 3.0.1, or 4.5.1?  Most people would think that release 4.5.1 is the more current software, but if XR was using semver that might not be the case at all.  As a concept I think that this is really counter intuitive (aka wrong).

Rob

Joe

..

---

From: Robert Wilton <[email-masked]>
Date: Tue, 19 Jun 2018 16:42:13 +0100

> - We're not looking into node level versioning "for now", goal is still module-level versioning
I don't think that we need to attach a version number to a node, but I 
do think that we need to be able to robustly compare two trees and 
identify all backwards compatible and non backwards compatible 
differences between the two trees.  This is by far the most robust way 
of knowing whether client software should just work with a new software 
version, or whether it will require changes.

> - We need to consider branches of YANG modules, a backwards-compatible fix (e.g. range increase) which goes in 1.1.3 isn't necessarily in 1.2.0.
When I re-read the semver.org rules, I think that my mistake here is the 
range increase is an API change and hence must increase the minor 
version number.  I think that this then solves the branching issue, 
since all patch versions have to be compatible with their parent minor 
version.

Thanks,
Rob

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Tue, 19 Jun 2018 17:59:14 +0200

On Tue, Jun 19, 2018 at 04:15:14PM +0100, Robert Wilton wrote:
> 
> I think that there are two plausible solutions here (if we want something
> like semver, but also want to ensure the major version number is sane):
> 
> Explaining option (1) in more detail, I think that the rules would be (e.g.
> modified from the clacla draft, and with the PATCH version rules closer to 
> how they are defined in semver.org):
> 

The interesting 'bug fixes' are stemming from situations where a
document is internally inconsistent and hence different
interpretations have been possible (and the longer the document is out
there, the harder it is to declare one broken). In the IETF, we
sometimes declare such an inconsistency as something to be prepared
for and we wait for a fix for the next version of the document.
Sometimes there is rough consensus to declare one interpretation to be
the right one and things may be done with an errata. I guess my point
is that whatever rules you invent, there will be judgement calls and
rules may be ignored or lets say interpreted.

I believe the whole idea of semver is to have a by definition fuzzy
agreement between parties what to expect and what not to expect and
since the agreement is fuzzy, semver does not replace human
engineering (and opt outs using explicit version checks on client code
if found necessary).

> Which variant may be more appropriate probably depends on whether supporting
> non backwards compatible bug fixes to older releases is a requirement or
> not.

Inconsistent and at times contradicting specifications are a reality.
This happens easily with pattern, must/when expressions, etc. The
question for me is whether semver is targeting such bug fixes or
not. I am entirely fine to declare bug fixes something engineers have
to think about and they have to come up with an appropriate solution.
And this is fine as long as we understand version numbers as fuzzy
agreement indicators.

> think that release 4.5.1 is the more current software, but if XR was using
> semver that might not be the case at all. As a concept I think that this is
> really counter intuitive (aka wrong).

I agree - there should be reasonably defined order on the version
number space.

/js

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Tue, 19 Jun 2018 18:01:22 +0200

On Tue, Jun 19, 2018 at 04:42:13PM +0100, Robert Wilton wrote:
> I don't think that we need to attach a version number to a node, but I do
> think that we need to be able to robustly compare two trees and identify all
> backwards compatible and non backwards compatible differences between the
> two trees. This is by far the most robust way of knowing whether client
> software should just work with a new software version, or whether it will
> require changes.

Right now, we try to summarize changes in the module revision
statement and I would not mind having more inline and machine readable
annotations instead. It takes discipline however to write them and to
check that they have been written...

/js

---

From: Joe Clarke <[email-masked]>
Date: Tue, 19 Jun 2018 12:04:33 -0400

> - We need to consider branches of YANG modules, a backwards-compatible fix (e.g. range increase) which goes in 1.1.3 isn't necessarily in 1.2.0. 

I think this is right.  Though Rob mentioned node-level "flagging" for
non-backwards compatible changes in things that cannot be easily
determined with tooling (e.g., a description of a node changes its
semantics).

I do not know if this is a hard requirement, though.

Joe