Subject: [netmod] Intended status of the yang-usage draft?

From: "Joel M. Halpern" <[email-masked]>
Date: Wed, 20 May 2009 09:18:33 -0400

After reading draft-ietf-netmod-yang-usage-00.txt, I really would like 
to see that published along with the base Yang draft (or, to be 
realistic, I suppose as soon thereafter as possible.)

But I got confused when I looked at the charter for the status of the 
document.
The draft is clearly intended to tell other groups (and this group 
itself) how modules are supposed to be written.  Unless there is a very 
good reason to do otherwise, one would expect module writers to comply 
with the document.
That is about as good a definition of how we use BCP documents as there 
really is.  (Like "RFC" itself, the acronym expansion for "BCP" is 
somewhat misleading.  We have published many BCPs on new things.)

Publishing the document as Informational does not seem likely to 
communicate the desired impact to other communities.

After talking with other folks, I was told that if there was a clear 
consensus from the WG, then the document could be a BCP.  I realize this 
was discussed before, and that this is a topic on which reasonable folks 
can differ.  But I would like to see some discussion.
The "downside" i have heard of this choice is that other similar 
documents have taken a long time to finish.  If changing the status will 
increase the time significantly, then that would be a bad outcome.

But I don't see why that is so.  Either we intend other folks to follow 
the document, or we don't.  If we expect folks to follow it, then we 
should be clear about that.  If we don't, then the wording should be 
much weaker, and I doubt it is worth the effort.

Yours,
Joel M. Halpern

---

From: "Bert Wijnen \(IETF\)" <[email-masked]>
Date: Wed, 20 May 2009 15:23:33 +0200

Well, when we did a similar thing for SMI (now RFC4181), it DID take a looooong time.
We in fact took an I-D that we used for a while as MIB doctors to see how well it
was written and if it was workable.

So doing an informational, with the intention to do a bis as BCP in a year (after
we gain experience), or with the intention to just advance it to BCP if we find
no problems would be the quickest approach (I would think). We could even make 
an introductuion section explains why it starts as informational and that we plan
to make it (or its successor) a BCP in a year or 2 years after we gain more
experience.

my 2 cents.
Bert
  ----- Original Message ----- 
  From: Joel M. Halpern 
  To: NETMOD Working Group 
  Sent: Wednesday, May 20, 2009 3:18 PM
  Subject: [netmod] Intended status of the yang-usage draft?

  Yours,
  Joel M. Halpern
  _______________________________________________
  netmod mailing list
  [email-masked]
  https://www.ietf.org/mailman/listinfo/netmod

------------------------------------------------------------------------------

  No virus found in this incoming message.
  Checked by AVG - www.avg.com 
  Version: 8.5.339 / Virus Database: 270.12.35/2123 - Release Date: 05/19/09 17:59:00

---

From: "Romascanu, Dan (Dan)" <[email-masked]>
Date: Wed, 20 May 2009 15:46:55 +0200

Joel,

> After talking with other folks, I was told that if there was 
> a clear consensus from the WG, then the document could be a 
> BCP

This does not seem to be the case. My reading at the meeting in SF was
that there is no clear consensus. We know we should get sooner or later
to a BCP but we are not sure whether to jump directly into this with a
new modeling data language. 

Then the WG chairs proposed a rechartering with this document as
Informational 

http://www.ietf.org/mail-archive/web/netmod/current/msg02330.html

As no comments were received the chairs concluded Informational as
consensus and this is how the item was added to the list of deliverables
in the charter.  

As a contributor, I support doing this as Informational first. I believe
it is important to have this document together or as close as possible
to the release of YANG, so that the guidelines for editing and checking
YANG modules are a public reference. I do not believe that with almost
zero experience in editing and zero experience in reviewing we have
enough information to reach consensus at a BCP level on what is believed
to be the best way to perform some edits or reviews of YANG modules or
on the corresponding IETF process functions (I am paraphrasing from RFC
2026 - section 5). 

I also basing my opinion on the similar experience in OPS with SNMP,
RADIUS, or DIAMETER where BCP documents appeared many years after the
protocol was approved and it took other years of debates to fine-tune
the text of the RFC. Some are actually still work-in-progress. I do not
want the same thing to happen with YANG. I prefer in this case running
code at rougher Informational consensus level to be available and tested
sooner and do the BCP later. 

This being my contributor position, as an AD I would not block the
option of doing a BCP if I am proved that my opinion is in a clear
minority by the rest of the WG.

Dan

> -----Original Message-----
> From: [email-masked] 
> [mailto:[email-masked]] On Behalf Of Joel M. Halpern
> Sent: Wednesday, May 20, 2009 4:19 PM
> To: NETMOD Working Group
> After reading draft-ietf-netmod-yang-usage-00.txt, I really 
> would like to see that published along with the base Yang 
> draft (or, to be realistic, I suppose as soon thereafter as possible.)
> 
> But I got confused when I looked at the charter for the 
> status of the document.
> itself) how modules are supposed to be written.  Unless there 
> is a very good reason to do otherwise, one would expect 
> module writers to comply with the document.
> That is about as good a definition of how we use BCP 
> documents as there really is.  (Like "RFC" itself, the 
> acronym expansion for "BCP" is somewhat misleading.  We have 
> published many BCPs on new things.)
> 
> Publishing the document as Informational does not seem likely 
> to communicate the desired impact to other communities.
> 
> After talking with other folks, I was told that if there was 
> a clear consensus from the WG, then the document could be a 
> BCP.  I realize this was discussed before, and that this is a 
> topic on which reasonable folks can differ.  But I would like 
> to see some discussion.
> The "downside" i have heard of this choice is that other 
> similar documents have taken a long time to finish.  If 
> changing the status will increase the time significantly, 
> then that would be a bad outcome.
> 
> But I don't see why that is so.  Either we intend other folks 
> to follow the document, or we don't.  If we expect folks to 
> follow it, then we should be clear about that.  If we don't, 
> then the wording should be much weaker, and I doubt it is 
> worth the effort.
> 
> Yours,
> Joel M. Halpern

---

From: "Joel M. Halpern" <[email-masked]>
Date: Wed, 20 May 2009 10:13:12 -0400

I must be misssing something.
Yes, it took a long time to write some of the earlier documents.
But, when those documents were being drafted folks treated them as 
"ideas to consider."  Other WGs were only expected to abide by them when 
they were completed.
As I understand it, we are expecting other WGs to abide by this document 
when it is published.

It seems to me that if that is so, then we are publishing a BCP, whether 
we call it that or not.

The alternative is to slap a big warning on the front of the document 
that says "we are not sure, but we think this is good advice.  We use 
MUST language only to keep clear what kinds of advice we are giving. 
Use at your own risk."

Yours,
Joel M. Halpern

---

From: "Romascanu, Dan (Dan)" <[email-masked]>
Date: Wed, 20 May 2009 16:34:36 +0200

It did not take that much time to write the documents as it took in
debating some of the painful details. I believe that this risks to be
the case here as well with almost no experience in writing YANG modules
and zero experience in reviewing. I think it is better to present this
as what it is - a proposal for code that has informational status at
this point in time, that we recommend other WGs to follow but we shall
not block approval if they do not follow. And one or two years later we
shall come with the BCP code based on the accumulated experience. 

Dan

(speaking as contributor)

> Sent: Wednesday, May 20, 2009 5:13 PM
> To: NETMOD Working Group
> Subject: Re: [netmod] Intended status of the yang-usage draft?
> 
> But, when those documents were being drafted folks treated 
> them as "ideas to consider."  Other WGs were only expected to 
> abide by them when they were completed.
> As I understand it, we are expecting other WGs to abide by 
> this document when it is published.
> 
> It seems to me that if that is so, then we are publishing a 
> BCP, whether we call it that or not.
> 
> The alternative is to slap a big warning on the front of the 
> document that says "we are not sure, but we think this is 
> good advice.  We use MUST language only to keep clear what 
> kinds of advice we are giving. 
> Use at your own risk."
> 
> Yours,
> Joel M. Halpern
> 
> >> consensus from the WG, then the document could be a BCP
> > 
> > that there is no clear consensus. We know we should get sooner or 
> > later to a BCP but we are not sure whether to jump directly 
> into this 
> > with a new modeling data language.
> > 
> > consensus and this is how the item was added to the list of 
> > deliverables in the charter.
> > 
> > As a contributor, I support doing this as Informational first. I 
> > believe it is important to have this document together or 
> as close as 
> > possible to the release of YANG, so that the guidelines for editing 
> > and checking YANG modules are a public reference. I do not believe 
> > that with almost zero experience in editing and zero experience in 
> > reviewing we have enough information to reach consensus at 
> a BCP level 
> > on what is believed to be the best way to perform some edits or 
> > reviews of YANG modules or on the corresponding IETF 
> process functions 
> > (I am paraphrasing from RFC
> > 2026 - section 5). 
> > 
> > the text of the RFC. Some are actually still work-in-progress. I do 
> > not want the same thing to happen with YANG. I prefer in this case 
> > running code at rougher Informational consensus level to be 
> available 
> > and tested sooner and do the BCP later.
> > 
> >> After reading draft-ietf-netmod-yang-usage-00.txt, I really would 
> >> like to see that published along with the base Yang draft 
> (or, to be 
> status of the 
> >> itself) how modules are supposed to be written.  Unless there is a 
> >> very good reason to do otherwise, one would expect module 
> writers to 
> >> comply with the document.
> >> That is about as good a definition of how we use BCP documents as 
> >> there really is.  (Like "RFC" itself, the acronym 
> expansion for "BCP" 
> >> is somewhat misleading.  We have published many BCPs on 
> new things.)
> >>
> >> consensus from the WG, then the document could be a BCP.  
> I realize 
> >> this was discussed before, and that this is a topic on which 
> >> reasonable folks can differ.  But I would like to see some 
> >> discussion.
> >> documents have taken a long time to finish.  If changing 
> the status 
> >> will increase the time significantly, then that would be a bad 
> >> outcome.
> >>
> >> But I don't see why that is so.  Either we intend other folks to 
> >> follow the document, or we don't.  If we expect folks to 
> follow it, 
> >> then we should be clear about that.  If we don't, then the wording 
> >> should be much weaker, and I doubt it is worth the effort.
> >>
> >> Yours,
> >> Joel M. Halpern

---

From: "Joel M. Halpern" <[email-masked]>
Date: Wed, 20 May 2009 10:46:12 -0400

if the intended or expected usage is as Dan describes below, then 
somewhat more text in the introduction of the document is needed to 
provide context for the use of MUST and SHOULD in the document.
I actually think the "advice" in the document is clear enough and simple 
enough that it should have stronger standing than Dan describes.
Yes, we could argue extensively about additional advice we can give. 
But if we keep it simple (as the document does currently) we can make a 
much stronger statement.

Yours,
Joel

---

From: Andy Bierman <[email-masked]>
Date: Wed, 20 May 2009 07:46:33 -0700

> I must be misssing something.

me too.

I wrote this draft because the YANG standard is
very weak wrt/ promoting inter-operability.
A valid YANG module does not need to contain
one word of documentation.  Every single form
of descriptive annotation is optional to use.

It is not clear to me why agreement on the contents
of this document will go faster if the resulting status
is Informational instead of BCP.

By the time RFC 4181 was written,
there were so many bad practices and bad MIB modules
in play, that it was a monster effort.

Waiting 5 - 10 years to offer any guidance on the usage
of YANG will produce the same result.

We know enough about NM to make some decisions
about how the IETF is going to use YANG.
We know that YANG modules are going to be reviewed
for RFC publication, and the reviewers are going to use
some sort of review criteria.

Removing all the RFC 2119 text (MUST, SHOULD, MAY)
seems like a really bad idea.  I do not see any
point to publishing a guidelines draft that has watered
down advice like "description strings are good.
You might want to use them."

Andy

> MUST language only to keep clear what kinds of advice we are giving. Use 
> at your own risk."
> 
> Yours,
> Joel M. Halpern
> 
>>> From: [email-masked] [mailto:[email-masked]] On 
>>> Behalf Of Joel M. Halpern
>>> like to see that published along with the base Yang draft (or, to be 
>>> very good reason to do otherwise, one would expect module writers to 
>>> there really is.  (Like "RFC" itself, the acronym expansion for "BCP" 
>>> is somewhat misleading.  We have published many BCPs on new things.)
>>>
>>> consensus from the WG, then the document could be a BCP.  I realize 
>>> reasonable folks can differ.  But I would like to see some discussion.
>>> documents have taken a long time to finish.  If changing the status 
>>> will increase the time significantly, then that would be a bad outcome.
>>>
>>> follow the document, or we don't.  If we expect folks to follow it,

---

From: Andy Bierman <[email-masked]>
Date: Wed, 20 May 2009 08:15:42 -0700

Joel M. Halpern wrote:
> Yes, we could argue extensively about additional advice we can give. But 
> if we keep it simple (as the document does currently) we can make a much 
> stronger statement.
> 

What if there aren't any big debates over the content?

I purposely avoided mentioning anything that I thought
would lead to deadlock (like camelCase vs. cli-case,
NP vs. P containers, augment, modules vs. submodules, etc.)

There is a baked-in assumption that agreement on the
details of this draft will take forever.  That would
be true if we tried to add a guideline for every
possible detail (no matter how small) that anybody
can possibly imagine.

Andy

---

From: David Kessens <[email-masked]>
Date: Wed, 20 May 2009 12:02:58 -0700

Joel,

> realistic, I suppose as soon thereafter as possible.)

As a working group chair, I prefer that we first focus our attention
on the document itself as opposed to administrative matters like the
precise status of the document. It is pretty clear that there is
something to be said for either informational or bcp status but when
we adopted the document the decision was made to go for informational.

I don't believe it is very productive to reopen the discussion on the
status of this document until we are a bit closer to the finish line
and we all have a better idea on how strong the consensus behind this
document is.

There is nothing in the way for proposing a status change to our Area
Director later down the line when we are getting closer to submitting
this document to the IESG and lets consider that at that time.

David Kessens
---

---

From: Andy Bierman <[email-masked]>
Date: Wed, 20 May 2009 12:42:01 -0700

> this document to the IESG and lets consider that at that time.

What about the concern Joel raised wrt/ RFC 2119 text?
If the intended status (BCP vs. Informational) has an
impact on the content of the document, then it matters.
I did not object to Informational because I thought it
would not impact the content.

The obvious issue is whether this paragraph can appear
in Informational RFCs:

    2.1.  Requirements Notation

       The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
       "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
       document are to be interpreted as described in [RFC2119].

So, does the intended status impact the content or not?
I suppose I should look it up myself, but maybe somebody
on the list already knows the relevant RFC section with
the answer.

My re-read of RFC 2119 seems to support Joel's concern that
this RFC applies to standards-track documents, because
non-standards-track documents are not explicitly mentioned.

Andy

---

From: David Kessens <[email-masked]>
Date: Wed, 20 May 2009 13:55:51 -0700

Andy,

> would not impact the content.

Again, let's not get hung up on things like the document status. Just
use the terms that you want to use in this document and we as a
working group decide whether we like the outcome and give you feedback
on possible improvements. We will then figure out whether
informational status is still appropriate or whether BCP makes more
sense.

David Kessens
---

---

From: "Bert Wijnen \(IETF\)" <[email-masked]>
Date: Thu, 21 May 2009 00:40:13 +0200

Again, add some introductory text that this document is wriotten with the intent 
to make it a BCP at a later stage and explain that that is why we use the RFC2119 language.

Easy as far as I am concerned.

Bert
  ----- Original Message ----- 
  From: Andy Bierman 
  To: David Kessens 
  Cc: NETMOD Working Group 
  Sent: Wednesday, May 20, 2009 9:42 PM
  Subject: Re: [netmod] Intended status of the yang-usage draft?

  Andy

  No virus found in this incoming message.
  Checked by AVG - www.avg.com 
  Version: 8.5.339 / Virus Database: 270.12.35/2124 - Release Date: 05/20/09 06:22:00