Subject: [netmod] module update rules

From: Ladislav Lhotka <[email-masked]>
Date: Fri, 18 Dec 2015 16:49:16 +0100

Hi,

if we want people to take YANG modules appearing in I-Ds seriously and implement them, then we should apply the revisioning rules to them. That is, if a module changes between two I-D revisions, then its revision-date has to be bumped and a new entry added to the revision history. As it is now, the I-D-based modules are esentially revisionless.

Lada

--
Ladislav Lhotka, CZ.NIC Labs
PGP Key ID: E74E8C0C

---

From: Andy Bierman <[email-masked]>
Date: Fri, 18 Dec 2015 08:06:00 -0800

On Fri, Dec 18, 2015 at 7:49 AM, Ladislav Lhotka <[email-masked]> wrote:

> Hi,
>
> if we want people to take YANG modules appearing in I-Ds seriously and
> implement them, then we should apply the revisioning rules to them. That
> is, if a module changes between two I-D revisions, then its revision-date
> has to be bumped and a new entry added to the revision history. As it is
> now, the I-D-based modules are esentially revisionless.
>
>

The revision rules only apply to published modules.
In IETF-speak, that means an RFC.  An Internet Draft
is a work-in-progress.  We update the revision date every time
the module changes, but the numerous incremental changes
for a work-in-progress should not be recorded in the module
revision history.  They should be recorded in the Change Log appendix.

I will try to make this procedure more clear in the YANG guidelines draft.

> Lada
Andy

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

---

From: Ladislav Lhotka <[email-masked]>
Date: Fri, 18 Dec 2015 17:32:11 +0100

> On 18 Dec 2015, at 17:06, Andy Bierman <[email-masked]> wrote:
> 
> 
> 

Update rules of sec. 10 offer no such excuse.

> revision history.  They should be recorded in the Change Log appendix.

Revision numbers are critical for interoperability. If we want vendors to implement modules such as ietf-routing now, the revisions must be solid and reliable.

> I will try to make this procedure more clear in the YANG guidelines draft.

I think it should be the other way around: YANG spec should not contain the update rules (because we all ignore them for I-D-based modules, right?), but the IETF guidelines should specify the policy you describe.

Lada

---

From: Christian Hopps <[email-masked]>
Date: Fri, 18 Dec 2015 11:47:47 -0500

Versioning has come up in previous conversations I've been a part of,
and I was led to believe that it does not really exist for yang
modules. That is, if you update a published module it's a completely new
model with no-expectation of compatibility with previous models.

Is it the case that there's no way to "bump the minor version" of a
model (i.e., you make only additions, but no deletions or changes to
meaning so that the model can be considered backward compatible)?

Thanks,
Chris.

---

From: Andy Bierman <[email-masked]>
Date: Fri, 18 Dec 2015 09:00:48 -0800

> Update rules of sec. 10 offer no such excuse.

That is a flaw in the draft

> Revision numbers are critical for interoperability. If we want vendors to
> implement modules such as ietf-routing now, the revisions must be solid and
> reliable.
>

Vendors implement work-in-progress at their own risk.
IMO we should do a better job publishing RFCs on time,
and implement RFCs.

> I think it should be the other way around: YANG spec should not contain
> the update rules (because we all ignore them for I-D-based modules,
> right?), but the IETF guidelines should specify the policy you describe.
>
>
This is a closed issue in YANG 1.1

Andy

---

From: Martin Bjorklund <[email-masked]>
Date: Fri, 18 Dec 2015 19:42:38 +0100 (CET)

> Update rules of sec. 10 offer no such excuse.

It says:

  For any published change, ...

I agree w/ Andy that 6087bis could clarify what this means in terms of
IETF.

/martin

> Revision numbers are critical for interoperability. If we want
> vendors to implement modules such as ietf-routing now, the
> revisions must be solid and reliable.
> 
> > 
> I think it should be the other way around: YANG spec should not
> contain the update rules (because we all ignore them for I-D-based
> modules, right?), but the IETF guidelines should specify the
> policy you describe. 
> 
> Lada
> 
> > 
> > 
> >  
> > Lada
> > 
> > 
> > Andy
> > 
> >  
> > --

---

From: Martin Bjorklund <[email-masked]>
Date: Fri, 18 Dec 2015 19:45:26 +0100 (CET)

> model with no-expectation of compatibility with previous models.

Please see section 10 of RFC 6020.

> meaning so that the model can be considered backward compatible)?

All rules in section 10 of RFC 6020 are backwards compatible.

Also note that you can deprecate and obsolete nodes and define new
nodes in the same module.

/martin

---

From: Christian Hopps <[email-masked]>
Date: Fri, 18 Dec 2015 14:11:45 -0500

> Please see section 10 of RFC 6020.

Ok, so I either misunderstood, or was misled. :)

So my reading of section 10 is that a new revision is the "bump the
minor" action, and a new module is required for "bump the major".

Thanks,
Chris.

---

From: Nadeau Thomas <[email-masked]>
Date: Fri, 18 Dec 2015 14:13:29 -0500

It would help to define this outside of the IETF context.
As we are all well aware, there are many organizations outside
of the IETF such as ODL, OpenConfig, IEEE, MEF, etc… that are now creating 
modules.

	—Tom

> On Dec 18, 2015:1:42 PM, at 1:42 PM, Martin Bjorklund <[email-masked]> wrote:
>

---

From: Andy Bierman <[email-masked]>
Date: Fri, 18 Dec 2015 11:22:54 -0800

> minor" action, and a new module is required for "bump the major".

There are no major or minor revision numbers in YANG.
There are on revision date strings YYYY-MM-DD.

Andy

---

From: Nadeau Thomas <[email-masked]>
Date: Fri, 18 Dec 2015 14:49:43 -0500

> On Dec 18, 2015:11:06 AM, at 11:06 AM, Andy Bierman <[email-masked]> wrote:
> 
> 
> 
> On Fri, Dec 18, 2015 at 7:49 AM, Ladislav Lhotka <[email-masked] <mailto:[email-masked]>> wrote:
> Hi,
> 

	The question is one of “published”.  So at the IETF that means an RFC
today, but Lada makes a good point in that in our new rapid development
environment we may never get to RFCs for most of the models being worked
on today - or not for some time. If we want those I-Ds to be used in
production, it might make sense to define an I-D as “published”.

	As I pointed out earlier, for other organizations, they have different
definitions of “published”, so we should consider a more flexible definition of
“published” to encompass those.  Its probably not a big deal to just say
something like, “other organizations that define models will define their
own definition of stable/published, and in those cases, that will 
suffice as the threshold for a version and following the updating
rules described herein."

	—Tom

> [email-masked] <mailto:[email-masked]>
> https://www.ietf.org/mailman/listinfo/netmod <https://www.ietf.org/mailman/listinfo/netmod>
>

---

From: Andy Bierman <[email-masked]>
Date: Fri, 18 Dec 2015 12:00:10 -0800

> suffice as the threshold for a version and following the updating

I think we should just try to focus on our own standards development
process.
Other organizations can adopt or reject IETF practices if they want.
We are using the same definition of published for about 25 years.
It means RFC in our process.  In a vendor environment, it means modules
released to customers.

We don't have a rapid development environment in the IETF.
If people want to implement half-baked YANG modules, that is their business.
They should be commended if they actually provide implementation feedback
into the RFC, but a work-in-progress is not a published module.

Andy

---

From: Nadeau Thomas <[email-masked]>
Date: Fri, 18 Dec 2015 15:23:40 -0500

> On Dec 18, 2015:3:00 PM, at 3:00 PM, Andy Bierman <[email-masked]> wrote:
> 
> 
> 
> On Fri, Dec 18, 2015 at 11:49 AM, Nadeau Thomas <[email-masked] <mailto:[email-masked]>> wrote:
> 
>> On Dec 18, 2015:11:06 AM, at 11:06 AM, Andy Bierman <[email-masked] <mailto:[email-masked]>> wrote:
>> 
>> 
>> 
> I think we should just try to focus on our own standards development process.

	That isn’t the point; the rest of the Yang universe looks to the IETF
to standardize and manage the Yang lanague and also looks here
for rules or best practices on building modules. 

	—Tom

---

From: Andy Bierman <[email-masked]>
Date: Fri, 18 Dec 2015 12:34:47 -0800

> for rules or best practices on building modules.

I don't really understand the confusion here.
Modules under development change constantly.
Almost all the changes are illegal for published modules.

Each SDO has a concept of unfinished work and finished work.
It should be easy to understand that the change rules apply
to finished work.

Andy

---

From: Christian Hopps <[email-masked]>
Date: Fri, 18 Dec 2015 16:08:59 -0500

> There are on revision date strings YYYY-MM-DD.

I thought that was the point I was making (the ""s being a reference
to my earlier mail), sorry for being confusing.

Chris.

---

From: Andy Bierman <[email-masked]>
Date: Fri, 18 Dec 2015 13:37:33 -0800

> to my earlier mail), sorry for being confusing.

YANG is a bit confusing, because it is not code, even though
we use it that way.  Major revisions do not exist because major changes
are simply not allowed to existing definitions.  You introduce new
definitions
to make major changes.  This can be in the same module or a new module.

Andy

---

From: Ladislav Lhotka <[email-masked]>
Date: Sat, 19 Dec 2015 08:41:15 +0100

> On 18 Dec 2015, at 19:42, Martin Bjorklund <[email-masked]> wrote:
> 

Well, sec. 10 (and 11 in 6020bis) only says: "For any published change, a new "revision" statement (Section 7.1.9) MUST be included in front of the existing "revision" statements." The update rules aren't conditional in any way.

Lada

---

From: Ladislav Lhotka <[email-masked]>
Date: Sat, 19 Dec 2015 09:07:01 +0100

> On 18 Dec 2015, at 18:00, Andy Bierman <[email-masked]> wrote:
> 
> 
> 

IMO, 6020(bis) is not a good place for such rules because their applicability depends on the context. Backward compatibility is a matter of policies and, above all, sound judgement of module authors/publishers/vendors. 

> Vendors implement work-in-progress at their own risk.

Yes, and that's why no vendor is very eager to do that. I actually think we should try harder to reduce the module churn already in the I-D phase, if possible.

> IMO we should do a better job publishing RFCs on time,

But doing that means there is no way back - because of the update rules. We have to accept that even modules published in RFCs may need to be changed in ways that aren't permitted by sec. 10, based on feedback from implementations. 

> This is a closed issue in YANG 1.1

You said there was a flaw in the draft.

Lada

---

From: Ladislav Lhotka <[email-masked]>
Date: Sat, 19 Dec 2015 09:12:34 +0100

> On 18 Dec 2015, at 20:11, Christian Hopps <[email-masked]> wrote:
> 
> 

Very true, this is an excellent observation! But starting a new module also means (beside all other complications) that the revision history is discontinued, which is bad. It's like demanding that each time a library API changes, a new GitHub project has to be started.

Cheers, Lada