Subject: [Netmod-ver-dt] Proposed updates to reqs draft

From: Joe Clarke <[email-masked]>
Date: Wed, 21 Nov 2018 09:58:25 -0500

I have started to make changes to the reqs draft based on feedback from
IETF 103.  My commit message:

Address items that arose at IETF 103.

* Acknowledge the inspiration of OpenConfig for semver [1]

* Refine the wording of requirement 1.4 to remove the notion of
  versioning YANG modules by product software releases [1]

* Add a basic definition of "bug fix"

* Refine wording of requirement 3.2

Text contributed by:    Rob Wilton [1]

Diff to txt:

https://tools.ietf.org/rfcdiff?url1=draft-verdt-netmod-yang-versioning-reqs-01&url2=https://namale.marcuscom.com:8443/~jclarke/draft-verdt-netmod-yang-versioning-reqs.txt

Comments thus far?

Joe

---

From: "Reshad Rahman (rrahman)" <[email-masked]>
Date: Wed, 21 Nov 2018 15:22:58 +0000

I like the rewording of 3.2, it has cleared my objections to 3.2.

On 2018-11-21, 9:59 AM, "Netmod-ver-dt on behalf of Joe Clarke (jclarke)" <[email-masked] on behalf of [email-masked]> wrote:

    

    

    Diff to txt:

    Comments thus far?
    
    Joe
    
    _______________________________________________
    Netmod-ver-dt mailing list
    [email-masked]
    https://www.ietf.org/mailman/listinfo/netmod-ver-dt

---

From: Balázs Lengyel <[email-masked]>
Date: Wed, 21 Nov 2018 15:32:11 +0000

Hello,

After these changes IMHO Req. 4.4 is included in REQ 1.4 so I propose 
removing 4.4

I have doubts about the bug fix definition: one man's bug is another's  
feature.
Let's see. Later if we run into problems, we could remove the word bug 
from the requirements,
but keep it in some introductory text to underline the main reason: why 
NBC changes are needed for older releases.

regards Balazs

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

---

From: Joe Clarke <[email-masked]>
Date: Wed, 21 Nov 2018 10:35:32 -0500

> After these changes IMHO Req. 4.4 is included in REQ 1.4 so I propose

Yeah, I see what you mean.  I'd be okay with that.  What do others think?

> I have doubts about the bug fix definition: one man's bug is another's 

This is why I left out any examples and tried to tie it to a defect
(which many if not all would recognize as something that was broken).

> NBC changes are needed for older releases.

At this point, I want to minimize changes to try and get to adoption.  I
think we're very close.  Once the WG owns this, then we can further
shape things.  But I'd like to think we can keep the core requirements
stable so we can make steady progress on a solution.

Joe

---

From: Joe Clarke <[email-masked]>
Date: Wed, 21 Nov 2018 10:56:05 -0500

> I like the rewording of 3.2, it has cleared my objections to 3.2.

Thanks, Reshad.  I went with a much simpler version to try and steer
away from a solution.

For completeness, Rob proposed this new text for 3.2:

            The solution MUST define a mechanism to allow servers to
            simultaneously support clients using different revisions of
            modules.  The mechanism SHOULD be optional for servers
            to implement.  The solution MAY be constrained to only
            support the client choosing between server defined sets of
            modules, where a particular session (or request) is
            constrained to using a single set of modules.

He admitted this sounded like it was leaning into a specific solution,
which is why I didn't initially use it.  But I'm open to further
comments from the DT.

Joe

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Wed, 21 Nov 2018 17:50:05 +0100

> * Add a basic definition of "bug fix"

I dislike this definition. It is not helpful. There were rather
different opinions what a bug fix is and adding a definition that
hides these differences under the carpet does not help us long term.
The definition is also way too generic. (A hardware defect is a
hardware defect and should not be fixed by messing up YANG modules.)

I am OK with the rewording of 3.2.

Comment: I read that some people make a distinction between 'revision'
and 'version'. I usually did not. We need to settle whether there is a
difference or not. The draft currently seems to use both terms
interchangeably.

/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: Wed, 21 Nov 2018 12:02:35 -0500

> hardware defect and should not be fixed by messing up YANG modules.)

I agree it's very generic.  There were two bits I wanted to have in this
definition.  One is the the word "defect" to try and differentiate a bug
fix from an enhancement.  The other was tying it to the change being
needed in a YANG module.

Yes, a hardware defect should not require a change to a YANG module.  I
also think people were getting too wound up about every change to
software requiring an equal change to a YANG module.  I gave the example
that I can fix a null pointer defref without a change to a YANG module.
 I could also add support for a new BGP header without needing a YANG
module change.

> difference or not. The draft currently seems to use both terms

In the versioned world, they may not be interchangeable if I can release
two versions of a module with the same revision date.  We tried to keep
this distinct in clacla, but I don't think I was as rigorous in my
editing of the reqs draft.

Is this needed for getting this to adoption readiness?

Joe

---

From: Mahesh Jethanandani <[email-masked]>
Date: Wed, 21 Nov 2018 10:30:35 -0800

Hi Joe,

> On Nov 21, 2018, at 6:58 AM, Joe Clarke <[email-masked]> wrote:
> 
> * Add a basic definition of "bug fix”

Do we need to use the word “bug fix”? Requirement 1.4 could as well use “changes” if the controversy is about what is a bug-fix.

The rest of the changes are fine by me.

> https://tools.ietf.org/rfcdiff?url1=draft-verdt-netmod-yang-versioning-reqs-01&url2=https://namale.marcuscom.com:8443/~jclarke/draft-verdt-netmod-yang-versioning-reqs.txt

Mahesh Jethanandani
[email-masked]

---

From: "Reshad Rahman (rrahman)" <[email-masked]>
Date: Wed, 21 Nov 2018 18:43:02 +0000

Joe, I prefer your simpler version. The part of Rob's text which makes me wince is "...simultaneously support clients using different revisions...".

On 2018-11-21, 10:56 AM, "Joe Clarke (jclarke)" <[email-masked]> wrote:

    

    
    Joe

---

From: Joe Clarke <[email-masked]>
Date: Wed, 21 Nov 2018 13:53:54 -0500

> Do we need to use the word “bug fix”? Requirement 1.4 could as well use “changes” if the controversy is about what is a bug-fix.

I think 1.4 we need to differentiate bug fix and enhancements (with the
former allowing for non-backwards-compatible).

Joe

---

From: Mahesh Jethanandani <[email-masked]>
Date: Wed, 21 Nov 2018 11:06:43 -0800

> On Nov 21, 2018, at 10:53 AM, Joe Clarke <[email-masked]> wrote:
> 

I notice that we introduced the word "backward-compatible enhancements” in the new revision of the document. This to me implies that there can be “non-backward-compatible enhancements” also. If the implicit assumption is that enhancements mean BC only, then we need to make that explicit in the document, by having a definition for “enhancement” that says just that.

Mahesh Jethanandani
[email-masked]

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Wed, 21 Nov 2018 21:17:48 +0100

> editing of the reqs draft.

revision != revision date
 
> Is this needed for getting this to adoption readiness?

Adoption means the WG is willing to work on it. Some seem to give WG
adoption an interpretation that is does not have. WG adoption is not
to be confused with WG consensus.

/js

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Wed, 21 Nov 2018 21:19:01 +0100

> I notice that we introduced the word "backward-compatible enhancements” in the new revision of the document. This to me implies that there can be “non-backward-compatible enhancements” also. If the…

I am not convinced we need new terms.

/js

---

From: "Joe Clarke (jclarke)" <[email-masked]>
Date: Wed, 21 Nov 2018 20:38:13 +0000

PGP Key : http://www.marcuscom.com/pgp.asc

> On Nov 21, 2018, at 15:17, Juergen Schoenwaelder <[email-masked]> wrote:
> 

That’s fair.  In the [semver] version world, every revision would get a new version, even if it is only a patch increment.

> to be confused with WG consensus.

I understand that.  I want to make sure this draft will satisfy the WG’s concerns for adoption.  Honestly, I though it was in 01 since adoption != consensus.

Joe

---

From: Balázs Lengyel <[email-masked]>
Date: Thu, 22 Nov 2018 08:32:07 +0000

On 2018. 11. 21. 20:06, Mahesh
Jethanandani wrote:

I think 1.4 we need to differentiate
bug fix and enhancements (with the

former allowing for
non-backwards-compatible).

I notice that we introduced the word "backward-compatible
enhancements” in the new revision of the document. This to me
implies that there can be “non-backward-compatible enhancements”
also. If the implicit assumption is that enhancements mean BC
only, then we need to make that explicit in the document, by
having a definition for “enhancement” that says just that.

Mahesh Jethanandani

BALAZS: At the head of the development line NBC enhancements ARE
allowed, you just take out a new major number for it.

As I understand Joe,  NBC enhancements are prohibited only  in older
releases.

---

From: Robert Wilton <[email-masked]>
Date: Thu, 22 Nov 2018 09:37:18 +0000

On 22/11/2018 08:32, Balázs Lengyel wrote:
>
>
> On 2018. 11. 21. 20:06, Mahesh Jethanandani wrote:
>>> On Nov 21, 2018, at 10:53 AM, Joe Clarke <[email-masked] 
>>> <mailto:[email-masked]>> wrote:
>>>
>> enhancements” in the new revision of the document. This to me implies 
>> that there can be “non-backward-compatible enhancements” also. If the 
>> implicit assumption is that enhancements mean BC only, then we need 
>> to make that explicit in the document, by having a definition for 
>> “enhancement” that says just that.
>>
>> Mahesh Jethanandani

I don't think that the requirement means that NBC enhancements MUST be 
prohibited in older releases, only that there is no requirement for the 
solution to support NBC enhancements in older releases.

Specifically, I see this as:
  - modified semver allows nbc updates in older releases and doesn't 
differentiate between bug and enhancement.
  - the guidelines that go with versioning scheme should state something 
like "NBC enhancements SHOULD* not be made in older releases".  * Or 
maybe MUST instead of SHOULD.

Thanks,
Rob

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

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Thu, 22 Nov 2018 10:45:10 +0100

Can someone explain to me why we need the term 'NBC enhancement'? Why
is NBC not sufficient? What is the benfit of classifying changes and
if so how many classes do we need and how do we decide which change
belongs to which class? I prefer to keep things simple.

/js

On Thu, Nov 22, 2018 at 09:37:18AM +0000, Robert Wilton wrote:
> > > also. If the implicit assumption is that enhancements mean BC only,
> > > then we need to make that explicit in the document, by having a
> > > definition for “enhancement” that says just that.
> > > 
> > > Mahesh Jethanandani
>  - the guidelines that go with versioning scheme should state something like
> "NBC enhancements SHOULD* not be made in older releases".  * Or maybe MUST
> instead of SHOULD.
> 
> Thanks,
> Rob
> 
> 
> > --

---

From: Robert Wilton <[email-masked]>
Date: Thu, 22 Nov 2018 10:46:20 +0000

For me, from a practical level, I don't think the versioning scheme 
needs to differentiate.

However, I do think that it reasonable to differentiate between new 
functionality vs fixing existing functionality in sensible guidance on 
how the scheme should be used.

No, I don't think that we need to define NBC enhancement.

Thanks,
Rob

---

From: Robert Wilton <[email-masked]>
Date: Thu, 22 Nov 2018 10:47:02 +0000

On 21/11/2018 18:43, Reshad Rahman (rrahman) wrote:
> Joe, I prefer your simpler version.

LGTM.

---

From: Robert Wilton <[email-masked]>
Date: Thu, 22 Nov 2018 10:47:46 +0000

> Yeah, I see what you mean.  I'd be okay with that.  What do others think?

Yes, I was thinking the same thing and agree that we can remove 4.4

Thanks,
Rob

---

From: Robert Wilton <[email-masked]>
Date: Thu, 22 Nov 2018 10:52:28 +0000

If we need to define bug fix at all then I would propose this 
alternative definition:

   o  Bug fix: A bug fix within the context of this document means a
            change to a YANG module that is made solely to rectify a 
mistake in the
            original YANG module definition.

Thanks,
Rob

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Thu, 22 Nov 2018 13:20:50 +0100

On Thu, Nov 22, 2018 at 10:46:20AM +0000, Robert Wilton wrote:
> For me, from a practical level, I don't think the versioning scheme needs to
> differentiate.
> 
> functionality vs fixing existing functionality in sensible guidance on how
> the scheme should be used.

Does the difference affect versioning? If not, we should not go
there.

> No, I don't think that we need to define NBC enhancement.

Good.

/js

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Thu, 22 Nov 2018 14:13:15 +0100

On Thu, Nov 22, 2018 at 10:52:28AM +0000, Robert Wilton wrote:
> If we need to define bug fix at all then I would propose this alternative
> definition:
> 
>            change to a YANG module that is made solely to rectify a mistake
> in the

While better, this still hides the different viewpoints that people
have on this and hence I rather have no definition than a definition
that allows different interpretations.

If we have to define 'bug fix' (and this may be unavoidable at some
point in time), we likely need to distinguish different flavors of
bug fixes:

- Fixes for definitions that could have been implemented only in a
  particular way since the context of the definition was anambiguous.

- Fixes for definitions that could have in principle been implemented
  in more than one way but where a certain evidence exists that a
  certain interpretation of the definition is very common. (And
  yes this is a judgement call.)

- Fixes for definitions that could be implemented but are a plain
  design error (could be implemented but would not be useful or
  incomplete). (Again a judgement call.)

- Fixes for definitions that could be implemented but would be very
  awkward to use. (Again a judgement call.)

Probably I could come up with more categories if I spent more time
thinking about it. But things move gradually from a strict notion of a
bug fix (restricted like an RFC errata) to an enhancement. In concrete
YANG terms, situations like "the index of this list is not flexible
enough" are real challenges to deal with.

/js

---

From: "Reshad Rahman (rrahman)" <[email-masked]>
Date: Thu, 22 Nov 2018 13:13:36 +0000

+1 on removing 4.4, good catch Balasz.

On 2018-11-22, 5:48 AM, "Netmod-ver-dt on behalf of Robert Wilton -X (rwilton - ENSOFT LIMITED at Cisco)" <[email-masked] on behalf of [email-masked]> wrote:

    
    Thanks,
    Rob

---

From: "Sterne, Jason (Nokia - CA/Ottawa)" <[email-masked]>
Date: Thu, 22 Nov 2018 15:21:28 +0000

I'm really not a fan of us defining a bug fix, or of having different rules in the doc for bugs vs enhancements. I think we could just say that the scheme:
- MUST handle BC changes in older versions
- SHOULD handle NBC changes in older versions
And we can make the recommendation that:
- model authors SHOULD avoid NBC changes in older versions

Jason

> -----Original Message-----
> From: Netmod-ver-dt <[email-masked]> On Behalf Of
> Juergen Schoenwaelder
> Sent: Thursday, November 22, 2018 8:13 AM
> To: Robert Wilton <[email-masked]>
> Cc: Joe Clarke <[email-masked]>; [email-masked]
> Subject: Re: [Netmod-ver-dt] Proposed updates to reqs draft
>

---

From: Mahesh Jethanandani <[email-masked]>
Date: Thu, 22 Nov 2018 07:29:42 -0800

> On Nov 22, 2018, at 4:20 AM, Juergen Schoenwaelder <[email-masked]> wrote:
> 

Precisely the point I was trying to make. If a “bug fix” or a “enhancement” does not affect the versioning scheme, let us drop these words and just keep BC or NBC. 1.4 in that case would read as:

The solution MUST allow for backwards-compatible as well as non-backwards-compatible changes in non-latest-release modules.

Thanks.

---

From: "Sterne, Jason (Nokia - CA/Ottawa)" <[email-masked]>
Date: Thu, 22 Nov 2018 15:36:45 +0000

Perhaps instead of "allow for" (which may be seen by operators as encouraging this behavior), we could say:

The solution MUST be able to indicate backwards-compatible as well as non-backwards-compatible changes to the non-latest version of a module.

or 

The solution MUST be able to indicate BC changes to the non-latest version of a module, and SHOULD be able to indicate NBC changes to the non-latest version of a module.

> Sent: Thursday, November 22, 2018 10:30 AM
> To: Juergen Schoenwaelder <[email-masked]>
> Cc: Robert Wilton <[email-masked]>; Joe Clarke <[email-masked]>;
> [email-masked]; Balázs Lengyel <[email-masked]>
> > On Nov 22, 2018, at 4:20 AM, Juergen Schoenwaelder
> <[email-masked]> wrote:
> >
> Precisely the point I was trying to make. If a “bug fix” or a “enhancement”
> does not affect the versioning scheme, let us drop these words and just keep
> BC or NBC. 1.4 in that case would read as:
> 
> The solution MUST allow for backwards-compatible as well as non-
> backwards-compatible changes in non-latest-release modules.
> 
> Thanks.
> 
> >

---

From: Robert Wilton <[email-masked]>
Date: Thu, 22 Nov 2018 15:48:25 +0000

I think that we should just use the text that I proposed previously, 
otherwise we are going round in circles.  No-one on the WG alias has 
objected to the 1.4 text that I previously proposed on the WG alias, and 
Andy was supportive of the change, so do we really want to reopen this 
text again?

Chris, for example, does not want vendors to make arbitrary changes in 
older releases, nor does he want the requirements to indicate that this 
is allowed or encouraged. But he does accept the need to allow bug fixes 
for old releases.

So, I think that we should try the adoption call with the current 1.4 
text in Joe's latest draft, and not define bug fix or enhancement.  If 
we need further discussion on this on the WG alias, so be it, but 
perhaps it can just be avoided.

Thanks,
Rob

---

From: Balázs Lengyel <[email-masked]>
Date: Thu, 22 Nov 2018 16:22:38 +0000

+1 Balazs

---

From: Joe Clarke <[email-masked]>
Date: Thu, 22 Nov 2018 14:09:58 -0500

> perhaps it can just be avoided.

I'd prefer this, but I do recall the point about defining "bug fix" was
brought up in Bangkok.  And I do like Rob's definition as it more
correctly hits what I was going for in trying to limit scope to those
corrections that only affect YANG modules.

I have removed req 4.4 and the bug fix definition.  That leaves us with
this proposed change set:

Joe

>> Perhaps instead of "allow for" (which may be seen by operators as
>> encouraging this behavior), we could say:
>>
>> The solution MUST be able to indicate backwards-compatible as well as
>> non-backwards-compatible changes to the non-latest version of a module.
>>
>> or
>>
>> The solution MUST be able to indicate BC changes to the non-latest
>> version of a module, and SHOULD be able to indicate NBC changes to the
>> non-latest version of a module.
>>
>>>>> needs
>>> to

---

From: Robert Wilton <[email-masked]>
Date: Fri, 23 Nov 2018 10:42:10 +0000

LGTM.

My vote is that we give this to chairs, and then see what comes back 
during the adoption poll, to find out if we need to spend time debating 
the definition of what a bug fix is.

Thanks,
Rob

> .

---

From: Balázs Lengyel <[email-masked]>
Date: Fri, 23 Nov 2018 11:49:24 +0000

+1, go for adoption. Balazs

On 2018. 11. 23. 11:42, Robert Wilton
wrote:

I have removed req
4.4 and the bug fix definition.  That leaves us with

LGTM.

My vote is that we give this to chairs, and then see what comes
back during the adoption poll, to find out if we need to spend
time debating the definition of what a bug fix is.

---

From: "Reshad Rahman (rrahman)" <[email-masked]>
Date: Fri, 23 Nov 2018 12:20:42 +0000

Sounds good to me.

From: Netmod-ver-dt <[email-masked]> on behalf of Balázs Lengyel <[email-masked]>
Date: Friday, November 23, 2018 at 6:49 AM
To: "Robert Wilton -X (rwilton - ENSOFT LIMITED at Cisco)" <[email-masked]>, "Joe Clarke (jclarke)" <[email-masked]>, "Sterne, Jason (Nokia - CA/Ottawa)" <[email-masked]>, Mahesh Jethanandani <[email-masked]>, Juergen Schoenwaelder <[email-masked]>
Cc: "[email-masked]" <[email-masked]>
Subject: Re: [Netmod-ver-dt] Proposed updates to reqs draft

+1, go for adoption. Balazs
On 2018. 11. 23. 11:42, Robert Wilton wrote:
I have removed req 4.4 and the bug fix definition.  That leaves us with
this proposed change set:

LGTM.

My vote is that we give this to chairs, and then see what comes back during the adoption poll, to find out if we need to spend time debating the definition of what a bug fix is.

--

Senior Specialist

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