Subject: [Netmod-ver-dt] Review of solution draft

From: Joe Clarke <[email-masked]>
Date: Sun, 17 Mar 2019 16:15:53 -0400

Sorry it's taken me so long to get around to a fresh read.  And sorry
I'll ask some questions that had I been able to join recent calls, I'd
know the answers to.

* I see a mix of semver:version and semver:module-version throughout
this draft.  Given the YANG module defines the latter, I think the
former instances should be corrected.

* Similarly, the YANG module defines import-versions, but in the
examples semver:version is used.

* I don't like the idea of "unchanged".  It's only defined and never
used in the draft.  I think "unchanged" is the same as editorial for all
intents and purposes.  I propose we remove its definition from the draft.

* Why was 32767 chosen to be the max of a version component?  Yes, it
seems high enough, but why limit it at all?  It's hard/impossible to
check for in a regexp.  Why not leave this as the max unsigned integer
and use MAX to stand for that?

* The description of the third example in Section 3.1 seems confusing to
me.  It states that the import clause is "excluding all 1.1.x and 1.2.x
'M' versions".  But it does import 1.1.0 and 1.1.1.  There doesn't
happen to be any 'M' versions of 1.1.0 and 1.1.1, but the imports clause
isn't what's limiting that.

More on the nit side, I found a few typos.  I can fix/change these and
anything else the team agrees with in git if you want.

Joe

---

From: "Rob Wilton (rwilton)" <[email-masked]>
Date: Mon, 18 Mar 2019 10:26:06 +0000

Hi Joe,

Comments inline (sorry, marked RW, slightly mangled due to Outlook).

-----Original Message-----
From: Netmod-ver-dt <[email-masked]> On Behalf Of Joe Clarke
Sent: 17 March 2019 20:16
To: [email-masked]
Subject: [Netmod-ver-dt] Review of solution draft

Sorry it's taken me so long to get around to a fresh read.  And sorry I'll ask some questions that had I been able to join recent calls, I'd know the answers to.

* I see a mix of semver:version and semver:module-version throughout this draft.  Given the YANG module defines the latter, I think the former instances should be corrected.

[RW]

My intention is that "semver:module-version" should be used when defining the module version, and "semver:version" is used for imports, so 2 separate statements with different allowed values.

* Similarly, the YANG module defines import-versions, but in the examples semver:version is used.

[RW]

That is a bug, it should be just "version".

* I don't like the idea of "unchanged".  It's only defined and never used in the draft.  I think "unchanged" is the same as editorial for all intents and purposes.  I propose we remove its definition from the draft.

[RW]

The idea here is related to performing a tooling comparison between two revisions.  Two different versions could have exactly the same content (except for their revision dates and version-numbers).  From a tooling perspective I would want it to be able to distinguish between two things being the same, or two things having editorial changes.  That doesn't mean that it necessarily needs to go in this draft through.

* Why was 32767 chosen to be the max of a version component?  Yes, it seems high enough, but why limit it at all?  It's hard/impossible to check for in a regexp.  Why not leave this as the max unsigned integer and use MAX to stand for that?

[RW]

It just seemed like a reasonable bound, and means that implementations can reasonably encode a version into a 64 bit field (3 x 16 bits, + 2 bits for m|M flag).

I'm not sure whether the hard to check in a regexp matters.  I've always questioned whether using regex syntax to check number bounds within strings is really a sensible strategy.  The version field ends up being a string anyway, so whatever bound we use is verbose to represent in the regex unless we use a decimal limit rather than binary limit.

When you say max unsigned integer, do you mean uint16 max, uint32 max, uint64 max, rather than the int16 max that I've chosen?

Finally, the reason why I used int16 max rather than uint16 max is because the range seemed reasonable, because I generally regard using signed numbers as safer/easier.

* The description of the third example in Section 3.1 seems confusing to me.  It states that the import clause is "excluding all 1.1.x and 1.2.x 'M' versions".  But it does import 1.1.0 and 1.1.1.  There doesn't happen to be any 'M' versions of 1.1.0 and 1.1.1, but the imports clause isn't what's limiting that.

[RW]

I don't follow.   Perhaps the explanation isn't quite clear, but it is mean to just exclude the 'M' versions, i.e. the intention is to exclude 1.1.2M, 1.2.1M and 1.2.2M.

More on the nit side, I found a few typos.  I can fix/change these and anything else the team agrees with in git if you want.

[RW]

Sure.

I've added a tag to the current version, and also squash-merged it into master.  I presume that we can continue doing updated on develop.

Thanks,

Rob

Joe

_______________________________________________

Netmod-ver-dt mailing list

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

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

---

From: Joe Clarke <[email-masked]>
Date: Mon, 18 Mar 2019 06:33:25 -0400

On 3/18/19 06:26, Rob Wilton (rwilton) wrote:
> *[RW] *
> *My intention is that "semver:module-version" should be used when
> defining the module version, and "semver:version" is used for imports,
> so 2 separate statements with different allowed values.*

This is fine.  The bug below makes this not-right :-).  Would you like
me to fix?

> *[RW] *
> *That is a bug, it should be just "version".*
> 
>  
> 
> *[RW] *
> *The idea here is related to performing a tooling comparison between two
> revisions.  Two different versions could have exactly the same content
> (except for their revision dates and version-numbers).  From a tooling
> perspective I would want it to be able to distinguish between two things
> being the same, or two things having editorial changes.  That doesn't
> mean that it necessarily needs to go in this draft through.*

I see whitespace changes and spelling changes as editorial.  So I'd
still vote for removing this "unchanged" thing from the draft.

> *[RW] *
> *It just seemed like a reasonable bound, and means that implementations
> can reasonably encode a version into a 64 bit field (3 x 16 bits, + 2
> bits for m|M flag).*
> 
> * *
> 
> *I'm not sure whether the hard to check in a regexp matters.  I've
> always questioned whether using regex syntax to check number bounds
> within strings is really a sensible strategy.  The version field ends up
> being a string anyway, so whatever bound we use is verbose to represent
> in the regex unless we use a decimal limit rather than binary limit.*
> 
> * *
> 
> *When you say max unsigned integer, do you mean uint16 max, uint32 max,
> uint64 max, rather than the int16 max that I've chosen?*

I think we should use a uint64 and let MAX stand for that.  If a vendor
wants to use version 45345834573 because it makes sense for them, we
should let them.  I didn't see a need to artificially limit this, at
least not at this point.

> 
> * *
> 
> *Finally, the reason why I used int16 max rather than uint16 max is
> because the range seemed reasonable, because I generally regard using
> signed numbers as safer/easier.*

Since this would never be negative, I would think unsigned would be fine.

> *[RW] *
> *I don't follow.   Perhaps the explanation isn't quite clear, but it is
> mean to just exclude the 'M' versions, i.e. the intention is to exclude
> 1.1.2M, 1.2.1M and 1.2.2M.*

Yes.  The explanation is not clear.  I can take a stab at clearing this
up if you want.

Joe

---

From: "Rob Wilton (rwilton)" <[email-masked]>
Date: Mon, 18 Mar 2019 10:57:14 +0000

-----Original Message-----
From: Joe Clarke <[email-masked]> 
Sent: 18 March 2019 10:33
To: Rob Wilton (rwilton) <[email-masked]>; [email-masked]
Subject: Re: [Netmod-ver-dt] Review of solution draft

> so 2 separate statements with different allowed values.*

This is fine.  The bug below makes this not-right :-).  Would you like me to fix?
[RW] 
Sure.

> used in the draft.  I think "unchanged" is the same as editorial for 
> all intents and purposes.  I propose we remove its definition from the draft.
> 
> *[RW] *
> 
> *The idea here is related to performing a tooling comparison between 
> two revisions.  Two different versions could have exactly the same 
> content (except for their revision dates and version-numbers).  From a 
> tooling perspective I would want it to be able to distinguish between 
> two things being the same, or two things having editorial changes.  
> That doesn't mean that it necessarily needs to go in this draft 
> through.*

I see whitespace changes and spelling changes as editorial.  So I'd still vote for removing this "unchanged" thing from the draft.

[RW] 
Yes, significant whitespace and spelling changes are editorial.  Hence why I want to distinguish between the two cases.

Case 1: The two schema trees/subtrees are semantically identical.
Case 2: The two schema trees/subtrees have differences, but the differences are only editorial.

Perhaps raise an issue for this (https://github.com/netmod-wg/yang-ver-dt/issues), and we can discuss in Prague?

> *It just seemed like a reasonable bound, and means that 
> implementations can reasonably encode a version into a 64 bit field (3 
> x 16 bits, + 2 bits for m|M flag).*
> 
> * *
> 
> within strings is really a sensible strategy.  The version field ends 
> up being a string anyway, so whatever bound we use is verbose to 
> represent in the regex unless we use a decimal limit rather than 
> binary limit.*
> 
> * *
> 

I think we should use a uint64 and let MAX stand for that.  If a vendor wants to use version 45345834573 because it makes sense for them, we should let them.  I didn't see a need to artificially limit this, at least not at this point.

[RW] 
This just makes these harder/less efficient to handle.

Noting that this is a string, there has to be some limit.

Perhaps it is worth also raising so we can discuss this in Prague?

Off topic, but what does this C program print?

#include <stdio.h>
int main (void)
{
  long a = -1; 
  unsigned b = 1; 
  printf ("%d\n", a > b); 
  return 0;
}

> 
>  
> 
>  
> 
> * The description of the third example in Section 3.1 seems confusing 
> to me.  It states that the import clause is "excluding all 1.1.x and 
> 1.2.x 'M' versions".  But it does import 1.1.0 and 1.1.1.  There 
> doesn't happen to be any 'M' versions of 1.1.0 and 1.1.1, but the 
> imports clause isn't what's limiting that.
> 
> *[RW] *
> 
> *I don't follow.   Perhaps the explanation isn't quite clear, but it 
> is mean to just exclude the 'M' versions, i.e. the intention is to 
> exclude 1.1.2M, 1.2.1M and 1.2.2M.*

Yes.  The explanation is not clear.  I can take a stab at clearing this up if you want.
[RW] 
Sure.

Thanks,
Rob

Joe

---

From: Joe Clarke <[email-masked]>
Date: Mon, 18 Mar 2019 07:03:43 -0400

> Perhaps raise an issue for this (https://github.com/netmod-wg/yang-ver-dt/issues), and we can discuss in Prague?

Okay.

> This just makes these harder/less efficient to handle.

Handle by whom?  Module authors will use the version of the depending
module as it is defined or use MAX.

> Noting that this is a string, there has to be some limit.

Agree.  And I'm just saying we make the limit higher.

Sure.

> Off topic, but what does this C program print?

Depends.  On some platforms/compilers, 0 and on others 1.  But usually
if you see 1 you'll also get a compiler warning of conversion.

Joe

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Mon, 18 Mar 2019 12:43:48 +0100

> should let them.  I didn't see a need to artificially limit this, at

An astronomic year has 31557600 seconds. So if you make a new major
version every second, then a uint32 gives you 136 years until you have
to invent a new module name. With one release every minute, you get
8165 years. With a uint16 and an average rate of one major release per
day, you still survive 179 years until you have to invent a new module
name. It seems 16 bits are sufficient as long as you do not have
programs create modules automatically (e.g. individually for each
device).

When we designed YANG, we settled on a revision date since we did not
really think it is necessary to support multiple publications of a
module in a single day. (And if it ever happens, you borrow some dates
from the future until time has catched up.) SMIv2 required more fine
grained timestamps but most people did not want to fill in
hours/minutes/seconds so we got rid of them in YANG (perhaps we could
have left them optional but so far I have not seen reports that the
revision date is too coarse grained).

/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: Joe Clarke <[email-masked]>
Date: Mon, 18 Mar 2019 07:46:03 -0400

> programs create modules automatically (e.g. individually for each

It's this type of thing I think could/will happen.  And I was thinking
more about MINOR and PATCH.

Joe

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Mon, 18 Mar 2019 12:53:05 +0100

> more about MINOR and PATCH.

If you run out of patch numbers, you bump the minor number, no? (And
likewise a roll-over of the minor number bumps the major number.)

If the end result of this is that every commit gets turned into a
version number, then we may leave the priority principle of readers
come first, writers come second, tool makers come last.

/js

---

From: "Rob Wilton (rwilton)" <[email-masked]>
Date: Mon, 18 Mar 2019 12:08:02 +0000

I'm still not really convinced that we need more than 16 bits.  These version strings are also meant to be human readable/consumable.

E.g. this version string is not that user friendly:
"2103.195.291834m"

If we increase the range, then I would argue to keep it less than int32 max, since this should be enough of a range and still works well/easily with all languages.

Also noting that languages like Javascript, Xpath, cannot handle the full range of 64 bit integers, because they handle them as doubles. 

Thanks,
Rob

-----Original Message-----
From: Joe Clarke <[email-masked]> 
Sent: 18 March 2019 11:46
To: Juergen Schoenwaelder <[email-masked]>
Cc: Rob Wilton (rwilton) <[email-masked]>; [email-masked]
Subject: Re: [Netmod-ver-dt] Review of solution draft

On 3/18/19 07:43, Juergen Schoenwaelder wrote:
>> I think we should use a uint64 and let MAX stand for that.  If a 
>> vendor wants to use version 45345834573 because it makes sense for 
>> them, we should let them.  I didn't see a need to artificially limit 
>> this, at least not at this point.
> 

It's this type of thing I think could/will happen.  And I was thinking more about MINOR and PATCH.

Joe

---

From: Balázs Lengyel <[email-masked]>
Date: Mon, 18 Mar 2019 13:18:49 +0000

I think this is the kind of thing Andy used to label "CRL, crappy
little rules". If you don't see a need to limit the number, don't.

+1 for Joe.

regards Balazs

On 2019. 03. 18. 11:57, Rob Wilton
(rwilton) wrote:

*[RW] *

* *

* *

*When you say max unsigned integer, do you mean uint16 max, uint32
max,
uint64 max, rather than the int16 max that I've chosen?*

[RW]

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

---

From: "Rob Wilton (rwilton)" <[email-masked]>
Date: Mon, 18 Mar 2019 13:44:33 +0000

So, clients should be expected to handle the following version number?

12345678901234567890123456789012345678901234567890. 1234567890123456789012345678901234567890. 1234567890123456789012345678901234567890M?

Thanks,
Rob

From: Netmod-ver-dt <[email-masked]> On Behalf Of Balázs Lengyel
Sent: 18 March 2019 13:19
To: Rob Wilton (rwilton) <[email-masked]>; Joe Clarke (jclarke) <[email-masked]>; [email-masked]
Subject: Re: [Netmod-ver-dt] Review of solution draft - version number limits

I think this is the kind of thing Andy used to label "CRL, crappy little rules". If you don't see a need to limit the number, don't.
+1 for Joe.

regards Balazs
On 2019. 03. 18. 11:57, Rob Wilton (rwilton) wrote:

*[RW] *

* *

binary limit.*

* *

max,

[RW]

--

Senior Specialist

Mobile: +36-70-330-7909              email: [email-masked]<mailto:[email-masked]>

---

From: Balázs Lengyel <[email-masked]>
Date: Mon, 18 Mar 2019 13:50:00 +0000

There are many ways to shoot yourself in the foot. I don't think
we need to worry about each of them.

For the code, this is just a number for a human, I will never buy
anything from Acme Corp. if I see this.

I don't see a real need to regulate this. For me a negative number
is much more confusing.

Still I don't insist on anything, this is not important for me.
:-)

regards Balazs

On 2019. 03. 18. 14:44, Rob Wilton
(rwilton) wrote:

So,
clients should be expected to handle the following version
number?

12345678901234567890123456789012345678901234567890.
1234567890123456789012345678901234567890.
1234567890123456789012345678901234567890M?

Thanks,

Rob

From: Netmod-ver-dt
<[email-masked]> On Behalf Of
Balázs Lengyel

To: Rob Wilton (rwilton)
<[email-masked]>; Joe Clarke (jclarke)
<[email-masked]>; [email-masked]

Subject: Re: [Netmod-ver-dt] Review of solution
draft - version number limits

I think this is the kind of thing
Andy used to label "CRL, crappy little rules". If you don't
see a need to limit the number, don't.

+1 for Joe.

regards Balazs

On 2019. 03.
18. 11:57, Rob Wilton (rwilton) wrote:

*[RW] *

* *

binary limit.*

* *

max,

[RW]

--

Senior Specialist

---

From: "Rob Wilton (rwilton)" <[email-masked]>
Date: Mon, 18 Mar 2019 14:20:53 +0000

I don’t think that this is a CLR at all.  It is just trying to put a reasonable constraint on the value space to make implementations easier.

If we think that “2^15 – 1” is too small, then we use “2^16 – 1”, “2^31 – 1” or “2^32 – 1”.
If we want values that are also easy for regex to check/limit then we could use a decimal rather than a binary limit, e.g. “10^9 – 1” which still fits into the int32 datatype.

We don’t need negative version numbers, but that doesn’t mean that isn’t a good idea to allow them to fit into one of the signed integer types.

I see no justification to use int64/uint64 or larger – it just means that interop between clients and servers is likely to be reduced.

If we end up with billions or major, minor, or patch versions of a YANG model then somewhere something has gone very wrong.

Thanks,
Rob

From: Netmod-ver-dt <[email-masked]> On Behalf Of Balázs Lengyel
Sent: 18 March 2019 13:50
To: Rob Wilton (rwilton) <[email-masked]>; Joe Clarke (jclarke) <[email-masked]>; [email-masked]
Subject: Re: [Netmod-ver-dt] Review of solution draft - version number limits

There are many ways to shoot yourself in the foot. I don't think we need to worry about each of them.

For the code, this is just a number for a human, I will never buy anything from Acme Corp. if I see this.
I don't see a real need to regulate this. For me a negative number is much more confusing.

Still I don't insist on anything, this is not important for me. :-)

regards Balazs
On 2019. 03. 18. 14:44, Rob Wilton (rwilton) wrote:
So, clients should be expected to handle the following version number?

Thanks,
Rob

From: Netmod-ver-dt <[email-masked]><mailto:[email-masked]> On Behalf Of Balázs Lengyel
Sent: 18 March 2019 13:19
To: Rob Wilton (rwilton) <[email-masked]><mailto:[email-masked]>; Joe Clarke (jclarke) <[email-masked]><mailto:[email-masked]>; [email-masked]<mailto:[email-masked]>
Subject: Re: [Netmod-ver-dt] Review of solution draft - version number limits

regards Balazs

*[RW] *

* *

binary limit.*

* *

max,

[RW]

--

Senior Specialist

--

Senior Specialist

---

From: Joe Clarke <[email-masked]>
Date: Mon, 18 Mar 2019 11:09:58 -0400

> If we increase the range, then I would argue to keep it less than int32 max, since this should be enough of a range and still works well/easily with all languages.

I'm fine with this.  If there are technical reasons to limit things that
makes sense.  Else, I don't think we should limit just because it may
look cleaner.

Joe

---

From: "Rob Wilton (rwilton)" <[email-masked]>
Date: Mon, 18 Mar 2019 15:24:30 +0000

I'm coming round to the idea of limiting it to 10^9 - 1, because that check is easy to express in the regex, 

i.e. something like this for 999,999,999:  "(0|[1-9][0-9]{0,8})",

instead of something like this, which is what a tool generates for 0-2147483648.  Probably slightly short, but more complex versions exist as well.

" ([0-9]|[1-8][0-9]|9[0-9]|[1-8][0-9]{2}|9[0-8][0-9]|99[0-9]|[1-8][0-9]{3}|9[0-8][0-9]{2}|99[0-8][0-9]|999[0-9]|[1-8][0-9]{4}|9[0-8][0-9]{3}|99[0-8][0-9]{2}|999[0-8][0-9]|9999[0-9]|[1-8][0-9]{5}|9[0-8][0-9]{4}|99[0-8][0-9]{3}|999[0-8][0-9]{2}|9999[0-8][0-9]|99999[0-9]|[1-8][0-9]{6}|9[0-8][0-9]{5}|99[0-8][0-9]{4}|999[0-8][0-9]{3}|9999[0-8][0-9]{2}|99999[0-8][0-9]|999999[0-9]|[1-8][0-9]{7}|9[0-8][0-9]{6}|99[0-8][0-9]{5}|999[0-8][0-9]{4}|9999[0-8][0-9]{3}|99999[0-8][0-9]{2}|999999[0-8][0-9]|9999999[0-9]|[1-8][0-9]{8}|9[0-8][0-9]{7}|99[0-8][0-9]{6}|999[0-8][0-9]{5}|9999[0-8][0-9]{4}|99999[0-8][0-9]{3}|999999[0-8][0-9]{2}|9999999[0-8][0-9]|99999999[0-9]|1[0-9]{9}|20[0-9]{8}|21[0-3][0-9]{7}|214[0-6][0-9]{6}|2147[0-3][0-9]{5}|21474[0-7][0-9]{4}|214748[0-2][0-9]{3}|2147483[0-5][0-9]{2}|21474836[0-3][0-9]|214748364[0-8])"

Although, I would still be happy, or perhaps even happier if the limit could be set lower, e.g. to 999,999.

Thanks,
Rob

-----Original Message-----
From: Joe Clarke <[email-masked]> 
Sent: 18 March 2019 15:10
To: Rob Wilton (rwilton) <[email-masked]>; Juergen Schoenwaelder <[email-masked]>
Cc: [email-masked]
Subject: Re: [Netmod-ver-dt] Review of solution draft

> If we increase the range, then I would argue to keep it less than int32 max, since this should be enough of a range and still works well/easily with all languages.

I'm fine with this.  If there are technical reasons to limit things that makes sense.  Else, I don't think we should limit just because it may look cleaner.

Joe

>> version every second, then a uint32 gives you 136 years until you 
>> have to invent a new module name. With one release every minute, you 
>> get
>> 8165 years. With a uint16 and an average rate of one major release 
>> per day, you still survive 179 years until you have to invent a new 
>> module name. It seems 16 bits are sufficient as long as you do not 
>> have programs create modules automatically (e.g. individually for 
>> each device).
>

---

From: Joe Clarke <[email-masked]>
Date: Mon, 18 Mar 2019 11:31:19 -0400

> instead of something like this, which is what a tool generates for 0-2147483648.  Probably slightly short, but more complex versions exist as well.

I'm happier with this because it is nice for tooling to check.  And that
makes a good technical reason for why this was chosen to be the limit.

Joe

---

From: "Rob Wilton (rwilton)" <[email-masked]>
Date: Mon, 18 Mar 2019 16:41:15 +0000

I suggest that we settle on, and update the draft and regex to '0-999,999'.   We can always debate this further in Prague.

Note, I probably won't update the draft until Prague any way, but will update the issue tracking this ...

Thanks,
Rob

-----Original Message-----
From: Joe Clarke <[email-masked]> 
Sent: 18 March 2019 15:31
To: Rob Wilton (rwilton) <[email-masked]>; Juergen Schoenwaelder <[email-masked]>
Cc: [email-masked]
Subject: Re: [Netmod-ver-dt] Review of solution draft

> instead of something like this, which is what a tool generates for 0-2147483648.  Probably slightly short, but more complex versions exist as well.

I'm happier with this because it is nice for tooling to check.  And that makes a good technical reason for why this was chosen to be the limit.

Joe

>>>> them, we should let them.  I didn't see a need to artificially 
>>>> limit this, at least not at this point.
>>>