Subject: Re: [Netmod-ver-dt] Import-versions proposal - GT & LT checks with branching

From: "Sterne, Jason (Nokia - CA/Ottawa)" <[email-masked]>
Date: Thu, 21 Feb 2019 14:59:06 +0000

Hi guys,

Creating a side thread for a specific topic -> the definitions & use of "greater than" and "less than".

It feels like the description below (and examples) are built with a very linear path of updates to a module.

But we allow (and need to allow) branching.

I think we should add an example of branching to the text.

(view in fixed width font).  Take this example:

module BGP:
2.0.0 ----- 2.1.0 ----- 2.2.0 ----- 2.3.0* ----- 2.4.0
              \
               \
                \
                 -4.0.0 ----- 4.1.0 ---- 4.2.0* ----- 4.3.0

Assume version 2.3.0* and 4.2.0* (the * is just to highlight the versions) have an important new container 'foo' that isn't in 3.0.0. Another module would want to import bgp version 2.3.0+ but not 4.0.0 or 4.1.0.

Rob's proposal can handle this by doing:
     import bgp {
          semver:version 2.3.0-2.MAX.MAX;
          semver:version 4.2.0-4.MAX.MAX;

I'm not super clear on whether that would exclude a future 2.5.0M.

Jason

From: Netmod-ver-dt <[email-masked]> On Behalf Of Robert Wilton
Sent: Monday, February 18, 2019 11:59 AM
To: Balázs Lengyel <[email-masked]>; Reshad Rahman (rrahman) <[email-masked]>; [email-masked]
Subject: Re: [Netmod-ver-dt] Import-versions proposal

Hi all,

Here is my proposed text for the simpler import-versions proposal based on what we discussed in Thursday's meeting:

5.  Import by Semantic Version

   RFC 7950 allows YANG module 'import' statements to optionally require

   the imported module to have a particular revision date.  In practice,

   importing a module with an exact revision date is overly burdensome

   because it requires the importing module to be updated whenever any

   change to the imported module occurs.  The alternative choice of

   using an import statement without a revision date is also not ideal

   because the importing module may not work with all possible revisions

   of the imported module.

   With semantic versioning, it is desirable for a importing module to

   specify the set of module versions of the imported module that are

   anticipated to be compatible.

   This document specifies a YANG extension for selecting which versions

   of a module may be imported.  It is designed around the assumption

   that most changes to a YANG module do not break importing modules,

   even if the changes themselves are not backwards compatible.

   The ietf-semver module defines the 'version' extension, a

   substatement to the YANG 'import' statement.  An 'import' statement

   may contain 'version' statements or a 'revision-date' statement, but

   not both.  The 'version' statement may be specified multiple times,

   requiring that the imported module version conforms to at least one

   of the 'version' statements.

   The argument to the 'version' statement takes one of three valid

   forms:

   1.  "A.B.Cc" - import the exact module version that matches "A.B.Cc".

   2.  "A.B.Cc+" - import any module version that matches, or is greater

       than, "A.B.Cc".

   3.  "A.B.Cc-X.Y.Zz" - import any module version that matches, or is

       greater than, "A.B.Cc"; and also matches, or is less than,

       "X.Y.Zz".  The word "MAX" can be used for 'Y' or 'Z' to represent

       the numerical value 32,767.

   The rules for comparing module version numbers are as follows:

   1.  Version "R.S.Tt" matches version "A.B.Cc", only if

          R = A, S = B, T = C and t = c.

   2.  Version "R.S.Tt" is greater than version "A.B.Cc", only if

          R = A, S = B and T > C; or

          R = A and S > B; or

          R > A

   3.  Version "R.S.Tt" is less than version "X.Y.Zz", only if

          R = X, S = Y, and T < Z; or

          R = X and S < Y; or

          R < X

5.1.  Module import examples

   Consider an example module "example-module" that is hypothetically

   available in the following versions: 0.1.0, 1.0.0, 1.1.0, 1.1.1m,

   1.1.2M, 1.1.3M, 1.2.0, 2.0.0, 3.0.0.

   The first example selects the specific version 1.1.2M.  A specific

   version import might be used if 1.1.2M contained changes that are

   incompatible with other versions.

   import example-module {

     semver:version 1.1.2M;

   }

   The next example selects the module versions that are match, or are

   greater than, version 1.1.0.  This form may be used if there is a

   dependency on a data node introduced in version 1.1.0.  This form of

   version import is expected to be most prevalent.

   Includes versions: 1.1.0, 1.1.1m, 1.1.2M, 1.1.3M, 1.2.0, 2.0.0 and

   3.0.0.

   import example-module {

     semver:version 1.1.0+;

   }

   The next example selects the module versions that are greater than

   1.1.0, but excluding the 1.1.2M and 1.1.3M versions.  This form may

   be needed if structural non backwards compatible changes are

   introduced in a patch 'M' version.  Generally, it is advisable to

   avoid making such changes.

   Includes versions: 1.0.0, 1.1.0, 1.1.1m, 1.2.0, 2.0.0 and 3.0.0.

   import example-module {

     semver:version 1.0.0-1.1.1m;

     semver:version 1.2.0+;

   }

   The last example selects all module versions with a major version

   number of 1.  This form may be useful if significant non backwards

   compatible changes have been introduced in version 2.0.0 that break

   import backwards compatibility.

   Includes versions: 1.0.0, 1.1.0, 1.1.1m, 1.1.2M, 1.1.3M, 1.2.0.

   import example-module {

     semver:version 1.0.0-1.MAX.MAX;

   }

Thanks,
Rob

On 14/02/2019 14:14, Balázs Lengyel wrote:

On 2019. 02. 14. 14:52, Reshad Rahman (rrahman) wrote:

     > 2) I still don't understand the rationale for allowing m/M in 5.1 (specific version import). 3.6.1m is really 3.7.1 but that's already taken, so if I import specific version 3.6.1 and I get 3.6.1m or 3.6.1M, that doesn't make sense to me. But if that's the consensus, I'll tag along.
          BALAZS: That's not how I understand this. If you have 3.6.1 already used
     you MUST NOT declare a new version 3.6.1M. You MUST use 3.6.2M. There
     can not exist two different versions that only differ in the value of
     the modifier. If you need a new modifier, take out the next Z value. So
     once you specified 3.6.1 there is only exactly one version with any
     specific x.y.z. That's why I included in my comment at the end of
     chapter 4.2.
                 If two modules versions share the same major and minor and patch
            version (X.Y.z) they MUST have the same content.
          Anyway this MUST be stated explicitly somewhere!
<RR> My mistake, you are correct. But my point was that the m and M (especially) are important indicators which seem to be ignored here. if you are importing a specific version and want 3.6.1M, why not import 3.6.1M? Import 3.6.1 should fail IMO if 3.6.1 does not exist but 3.6.1M exists, otherwise it is misleading.
BALAZS: OK. I will require m/M as correct.

     > 3) The + in 5.2 doesn't accept m/M but the + in 5.4/5.5 does accept m/M, I think this inconsistency will be confusing.
     BALAZS: Think about what the use-case is: We want a specific
     functionality. m or M would change that, so disallowed. 5.4 and 5.5 are
     about cases where we are not worried about compatibility. 5.2 is a case
     where we want to specify the functionality we want.  It is consistent in
     that if you specify x.y you don't want something else.
<RR> I understand the use-cases, I just wish we could have different symbols for when we want compatibility and when we don't.

     > 4) Not a fan of 3.6# in 5.3, but I don't have a better proposal. Use C for compatible?
     BALAZS: I am OK with C if the group says so, IMHO BC would be even better.
<RR> Ack.

BALAZS: So how about

         The version-clause argument MUST follow one of the below patterns:
         (\d+\.\d+\.\d+([mM])?)|      // specific version
                               // e.g. 3.6.1m
         (\d+\.\d+\.\d+\BC)|    // specific functionality and minimum patch level
                               // e.g. 3.6.1BC
         (\d+\.\d+BC)|          // compatible version
                               // e.g. 3.6BC
         (\d+\.\d+\+)|         // assumed compatible version
                               // e.g. 3.6+
         (\d+\+)|              // newer than a specific major version
                               // e.g. 3+
         (\d+\.\d+-\d+\.\d+)   // range of versions
                               // e.g. 3.6-7.8

     > 5) 5.4, I might be alone in this but not a fan of this assumption. What makes an M change usable v/s a +1 major version unsable?
     BALAZS: I could get rid of this, it would simplify the solution. It was
     Rob who wanted it, even stated that it is more important than 5.3 the
     real compatible case.
<RR> If that's what the group wants I think we should spell out what M changes are acceptable and which ones aren't. Just saying "will not be drastic" sounds too much like a Brexit election promise to me (sorry Rob).
BALAZS: I am not a fan either

Regards,
Reshad.

     > Regards,
     > Reshad.
     >
     > On 2019-02-13, 10:32 AM, "Netmod-ver-dt on behalf of Balázs Lengyel" <[email-masked] on behalf of [email-masked]><mailto:[email-masked]@ericsson.com> wrote:
     >
     >      Hello,
     >
     >      I have updated my proposal for import-versions.  See attachment. It
     >      includes the relevant part of the YAM too.
     >
     >      Regards Balazs
     >
     >      --
     >      Balazs Lengyel                       Ericsson Hungary Ltd.
     >      Senior Specialist
     >      Mobile: +36-70-330-7909              email: [email-masked]<mailto:[email-masked]>
     >
     >
     >
     --
     Balazs Lengyel                       Ericsson Hungary Ltd.
     Senior Specialist
     Mobile: +36-70-330-7909              email: [email-masked]<mailto:[email-masked]>

_______________________________________________

Netmod-ver-dt mailing list

[email-masked]<mailto:[email-masked]>

https://www.ietf.org/mailman/listinfo/netmod-ver-dt