Subject: [Netmod-ver-dt] Guidelines text

From: "Reshad Rahman (rrahman)" <[email-masked]>
Date: Thu, 17 Jan 2019 15:46:00 +0000

Hi,

Yesterday I added some text very quickly (the text isn’t “polished”) but would like to have feedback on it before continuing in that direction:

  *   Do you agree on the guideline for removing a node?
  *   What examples of NBC changes would you like to see?

Regards,
Reshad.

3.1.2.  Making non-backwards-compatible changes to a YANG module

   There are various valid situations where a YANG module has to be
   modified in a non-backwards-compatible way, such changes SHOULD be
   done gradually.  Here are some examples and guidelines on how the
   changes should be made:

   o  Removing a node from the data tree, e.g. because support for the
      corresponding feature is being removed:

      1.  The node's status SHOULD be changed to "deprecated" and it
          MUST be supported for a mandatory amount of time acceptable to
          the consumers of the YANG model.  This is a backwards-
          compatible change.

      2.  When the mandatory amount of time has passed, the node's
          status MAY be changed to "obsolete" and it is not supported
          anymore.  This is a non-backwards-compatible change.

   o  Changing the type of a leaf-node

   o  Reducing the range of a leaf node

   o  Changing the key of a list

---

From: "Sterne, Jason (Nokia - CA/Ottawa)" <[email-masked]>
Date: Thu, 17 Jan 2019 21:47:56 +0000

See below.

Jason

From: Netmod-ver-dt <[email-masked]> On Behalf Of Reshad Rahman (rrahman)
Sent: Thursday, January 17, 2019 10:46 AM
To: [email-masked]
Subject: [Netmod-ver-dt] Guidelines text

Hi,

Regards,
Reshad.

[>>JTS: ] I think we need to separate this into two sections:
A) general description of guidelines for making MBC changes
B) A bunch of examples (perhaps in an appendix)

I see most of what you have here as (B)

      2.  When the mandatory amount of time has passed, the node's
          status MAY be changed to "obsolete" and it is not supported
          anymore.  This is a non-backwards-compatible change.
[>>JTS: ] Agree with this approach in general. Exact wording needs debate (e.g. mandatory amount of time)

[>>JTS: ] Other transformations that might be useful to illustrate:
- renaming an enum name when it has a 'value' statement (my suggestion is to remove the 'value' statement when marking the enum obsele so the replacement enum can reuse that value)
- changing a leaf to a container (have to select a new name for the new container)
- renaming a typedef (BC change)

---

From: "Reshad Rahman (rrahman)" <[email-masked]>
Date: Fri, 18 Jan 2019 03:04:25 +0000

Thanks Jason, inline.

From: "Sterne, Jason (Nokia - CA/Ottawa)" <[email-masked]>
Date: Thursday, January 17, 2019 at 4:48 PM
To: "Reshad Rahman (rrahman)" <[email-masked]>, "[email-masked]" <[email-masked]>
Subject: RE: Guidelines text

See below.

Jason

Hi,

Regards,
Reshad.

<RR> I do have section 3.1.1 which maybe maps to what you have in mind for A. By general description, are you referring to how to change semver or are you referring to something else such as “when to do an NBC change”?

<RR> Ack. To my defence I wrote this while watching the Sens-Avs game…. I didn’t want to mention s/w releases, I’ll think about how to re-phrase this.

Regards,
Reshad.

---

From: Joe Clarke <[email-masked]>
Date: Fri, 18 Jan 2019 16:05:20 -0500

On 1/17/19 10:46, Reshad Rahman (rrahman) wrote:
> Hi,
> 
>  
> 
> Yesterday I added some text very quickly (the text isn’t “polished”) but
> would like to have feedback on it before continuing in that direction:
> 

Why gradually?  Why couldn't I make a bunch of NBC changes at once?

>           the consumers of the YANG model.  This is a backwards-

We should fold in the status reasons when one has to do this (introduced
in this draft as well).  For example:

A status reason MUST(?) always be added to explain why the node is being
deprecated and when it is expected to become obsolete.

===

Additionally, what about implementation of deprecated nodes?  Should we
also state that deprecated nodes SHOULD be implemented and point to the
yang-library leaf we're introducing?

>           anymore.  This is a non-backwards-compatible change.

What about outright renaming a node to fix a bad name?  For example:

OLD:

leaf support-nbc {
  type boolean;
...
}

NEW:

leaf supports-nbc {
  type boolean;
...
}

We have cases where this happens.  Sure, you could have both nodes, and
maybe some guidance to do that (deprecating the old one).

>    o  Changing the key of a list

We've talked about node semantics changing as well.  My example has been
that the old node measured temp in degrees F, and the new node measures
temp in degrees C.  Assuming no units and only the description was
changed, that is a tough-to-find NBC.  Are we going to have per-node
semvers for this to aid tooling?  I forgot where we landed on that.

Joe

---

From: "Reshad Rahman (rrahman)" <[email-masked]>
Date: Fri, 18 Jan 2019 23:00:11 +0000

Joe, inline.

On 2019-01-18, 4:05 PM, "Joe Clarke" <[email-masked]> wrote:

By gradual I meant for each NBC change, first do the BC change (deprecated etc) and then NBC (obsolete). Yes a bunch can be made at once. I'll see how to reword this.  

    

Ack.
    
    ===
    
    Additionally, what about implementation of deprecated nodes?  Should we
    also state that deprecated nodes SHOULD be implemented and point to the
    yang-library leaf we're introducing?
I thought we wanted to change this into a MUST? I recall Balasz brought this up.

    
    OLD:
    
    leaf support-nbc {
      type boolean;
    ...
    }
    
    NEW:
    
    leaf supports-nbc {
      type boolean;
    ...
    }
    
 Ack.   
    
From what I recall, no per-node semver. I did add some text (in the previous section which I didn't copy in the email) which states that we can't just rely on tools to determine semver value. Agree it's a tough to find NBC. Might recommend deprecate + new leaf.

Regards,
Rehjad.
    
    Joe

---

From: Joe Clarke <[email-masked]>
Date: Tue, 22 Jan 2019 11:08:42 -0500

> By gradual I meant for each NBC change, first do the BC change (deprecated etc) and then NBC (obsolete). Yes a bunch can be made at once. I'll see how to reword this. 

Got you.  Maybe incrementally change things when it comes to removing nodes.

> I thought we wanted to change this into a MUST? I recall Balasz brought this up.

MUST works for me, too.

> From what I recall, no per-node semver. I did add some text (in the previous section which I didn't copy in the email) which states that we can't just rely on tools to determine semver value. Agree…

Okay.  I couldn't remember where we landed on per-node iff there was an
NBC change that couldn't be picked up easily in tooling.

Thanks for getting started on this, Reshad.

Joe

---

From: "Reshad Rahman (rrahman)" <[email-masked]>
Date: Wed, 30 Jan 2019 22:44:08 +0000

I've made updates/additions based on comments from Joe and Jason.
https://github.com/netmod-wg/yang-ver-dt/blob/develop/yang-semver/draft-verdt-netmod-yang-semver.txt

Regards,
Reshad.

On 2019-01-22, 11:08 AM, "Joe Clarke" <[email-masked]> wrote:

    
    MUST works for me, too.

    
    
    Joe

---

From: Robert Wilton <[email-masked]>
Date: Thu, 31 Jan 2019 14:42:26 +0000

Hi Reshad,

I've taken a look at section 9.  Here are some comments, we can also 
discuss them later:

1) I think that we may want to merge section 9.1.1 and section 4.3, 
although they are written from a different perspective, e.g. section 
9.1.1 is written from the perspective of how the module number changes, 
whereas 4.3 is written from the perspective of what type of change has 
been made.  I think that section 4.3 needs to be fixed as you have 
pointed out previously, but section 9.1.1 also needs to cover the "m" 
and "M" scenario.

2) In section 9.1.1, I think that we should be defining how the version 
number MUST be updated rather than SHOULD.  But then this is in a 
guidance section of the document, and a MUST doesn't sound like 
guidance, it sounds like required behaviour.

3) In section 9.1.1, it might be better to refer to editorial changes 
rather than "bug fixes", since a bug fix could be NBC, BC, or editorial, 
depending on the nature of the change; also when talking about semver.

4) I don't really agree with the paragraph at the end of 9.1.1. I wonder 
if this can be reworded something along the lines of:
  - The semantic version changes can be determined by a person examining 
the module changes, or via tooling.  Either approach is fine as long as 
the semantic version number is updated accurately.  Using a combination 
of tooling and manual validation may be advisable.

5) On section 9.1.2:
- I'm not sure that I support the first paragraph, I think that it 
depends on the changes, and the likely impact.  It may also depend on 
whether the server supports version selection.  E.g. if it is native 
modules being updated, and the server still supports the old version, 
this just fixing a mistake in an NBC way should be fine.

But I do like the idea of setting out different scenarios for examples, 
as you have, on the types of changes that are being made and how they 
should be best handled.

Thanks,
Rob

On 30/01/2019 22:44, Reshad Rahman (rrahman) wrote:
> _______________________________________________
> Netmod-ver-dt mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/netmod-ver-dt

---

From: "Reshad Rahman (rrahman)" <[email-masked]>
Date: Thu, 31 Jan 2019 14:47:14 +0000

Thanks Rob. Sure can discuss in the meeting if we have time. By section 9, did you mean section 3?

Regards,
Reshad.

On 2019-01-31, 9:42 AM, "Robert Wilton" <[email-masked]> wrote:

    Hi Reshad,

    

    
    5) On section 9.1.2:

    Thanks,
    Rob