Subject: [netmod] optional char in yang-semver

From: "Sterne, Jason (Nokia - CA/Ottawa)" <[email-masked]>
Date: Mon, 8 Jun 2020 14:38:19 +0000

Hello all,

In our weekly YANG versioning calls we discussed the 'm' and 'M' modifiers in the yang-semver draft.

While we still believe that the extra char modifier is a useful addition, we are now leaning towards a different location for the letter and different characters as the indicator.

The current draft uses 'm' or 'M' at the end, e.g.   2.1.1m  or 3.3.3M.  Here are the latest thoughts from the weekly call.

As a high level summary -> we're basically down to options p1, p2 or p3 below. Looking for other opinions to debate amongst those.

We should avoid having any semantic meaning that depends on the case of the letter. Hence having 'm' and 'M' mean different things isn't a good idea. So in our latest proposal the case of the letter is not significant.

As before, two different letters/symbols should be used:
1) one to signify a major (NBC) change
2) one to signify a minor (BC) change

Our current 'favorites' are:
p = major (NBC)
c = minor (BC)

Other letters considered but rejected were:
X, Y, Z: have connotations of wildcard  (1.2.3x implies "any 1.2.3*")
N: has connotations of wildcard
A, B: alpha, beta
i, j, k: common iterators - better to avoid?
nc = non-compatible. Better to stick to 1 letter?

We also feel that it may actually be a useful property to "break" tools (i.e. have them error, halt, etc) when they don't know how to handle the letter - in particular for major changes (so they don't accidently assume 2 versions are compatible). So perhaps placing the "p" should be up adjacent to the major version:
p1.1.1 or 1p.1.1

We're undecided on where the "c" should go.  We're down to a few favorites.  Here are combinations of p & c that we're considering most strongly (examples below show a Major Change / Minor Change):
p1) p1.1.1 / 1.1.1c    nice bookends
p2) 1p.1.1 / 1.1c.1    letter goes with the part of the version it is associated with
p3) 1p.1.1 / 1.1.1c

We debated a number of other locations & formats. Pasting them here so you can get a quick visual of what they look like:

NBC Changes:
n1) 1.1.0 --- p1.1.1   not quite as likely to "break" tools as 1p.1.1?
n2) 1.1.0 --- 1.1.1M
n3) 1.1.0 --- 1p.1.1   more likely to "break" tools, more likely to trigger people to lookup what it means
n5) 1.1.0 --- 1nc.1.1
n6) 1.1.0 --- 1.1.1(p)
n7) 1.1.0 --- 1(p).1.1
n8) 1.1.0 --- X.1.1.1

BC Changes:
b1) 1.1.0 --- 1.1c.1
b2) 1.1.0 --- 1c.1.1
b3) 1.1.0 --- C1.1.1

Rgds,
Jason

---

From: "Sterne, Jason (Nokia - CA/Ottawa)" <[email-masked]>
Date: Tue, 9 Jun 2020 14:16:52 +0000

Hi all,

An update on this. We had further discussions on the weekly revision call just now. Thanks to an interesting new suggestion from Jan L. we're changing tack on our favorite "extra indicators".

We're basically down to three very similar options.

The underscore "_" helps differentiate these from the standard semver "-" or "+" and will help cause tools that don't understand it to signal that something unusual needs to be looked at (warning or error).

Reminder -> this is only in those cases in the draft where the "M" and "m" were used. Check the draft to see the use cases for these:
https://datatracker.ietf.org/doc/draft-ietf-netmod-yang-semver/?include_text=1

###########
Option J1
###########
use the following suffixes:
_non_compatible  (instead of the old "M", for an NBC change)
_compatible (instead of the old "m", for a BC change)

e.g. for NBC:
1.1.0 -> 1.1.1_non_compatible
e.g. for BC:
1.1.0 -> 1.1.1_compatible

###########
Option J2
###########
- same as J1, just one fewer underscore

e.g. for NBC:
1.1.0 -> 1.1.1_noncompatible
e.g. for BC:
1.1.0 -> 1.1.1_compatible

###########
Option J3
###########
- use nbc and bc instead of spelling out words
- shorter but not as good for anyone unfamiliar with the spec

e.g. for NBC:
1.1.0 -> 1.1.1_nbc
e.g. for BC:
1.1.0 -> 1.1.1_bc

Rgds,
Jason

From: Sterne, Jason (Nokia - CA/Ottawa)
Sent: Monday, June 8, 2020 10:38 AM
To: [email-masked]
Subject: optional char in yang-semver

Hello all,

NBC Changes:

BC Changes:
b1) 1.1.0 --- 1.1c.1
b2) 1.1.0 --- 1c.1.1
b3) 1.1.0 --- C1.1.1

Rgds,
Jason

---

From: Erik Auerswald <[email-masked]>
Date: Tue, 9 Jun 2020 19:10:14 +0200

Hi all,

> https://datatracker.ietf.org/doc/draft-ietf-netmod-yang-semver/?include_text=1

I like this.  It clearly shows what is meant.  No special context or
knowledge is needed to understand the meaning, or at least to understand
that trouble might lie ahead.

I like this a little bit less than J1, because it is a little bit less
easy to distinguish between the two words.

I do not like this as much as J1 and J2, because both _n_on _b_ackwards
_c_ompatible and _n_on (or _n_o) _b_reaking _c_hanges could be shortened
to NBC.  Thus the reader needs to know the specific context where the
NBC abbreviation is used.

Thanks,
Erik

---

From: "Joe Clarke (jclarke)" <[email-masked]>
Date: Wed, 10 Jun 2020 21:36:02 +0000

> that trouble might lie ahead.

I like this, too, but I like J2 a bit better as I don’t like the double ‘_’.  That said, I see your point about what the eye distinguishes.

Still, I can live with both, but I prefer J2.

> easy to distinguish between the two words.

Joe

---

From: "Reshad Rahman (rrahman)" <[email-masked]>
Date: Thu, 11 Jun 2020 19:39:48 +0000

I'm fine with either J1 or J2.

Regards,
Reshad.

    Joe

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