Subject: [netmod] Recording Motivation

From: Phil Shafer <[email-masked]>
Date: Tue, 19 Aug 2008 14:21:14 -0400

Andy Bierman writes:
>As Joel pointed out, it would be nice to capture
>the design motivations for various details, instead
>of just the details.

My question is:  is the yang draft the appropriate place to record
the "why" and motivation for the outcome?  Should this be in distinct
sections?  Should we have an associated FAQ where the questions are
of the form "what the heck where you thinking when you ...."?  Should
we make an "Annotated YANG Standard" document with the draft/rfc
text plus the history/rationale/defense/motivation/etc?

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

---

From: Andy Bierman <[email-masked]>
Date: Tue, 19 Aug 2008 12:30:59 -0700

> text plus the history/rationale/defense/motivation/etc?

An appendix in the YANG draft is fine unless lots of text is needed.
Maybe a YANG FAQ, outside this draft, is a good idea.

   - Why doesn't YANG support XML attributes?
   - Why doesn't YANG support the xsd:list data type?
   - Why doesn't YANG support reusable complex data types?
   - Why doesn't YANG use the RelaxNG instance qualifiers
     (?, *, +) instead of leaf-list?
   - What are the differences between P and NP containers and
     why should I care?
   - Why does YANG require that every version of every module
     be maintained by all users, instead of identifying version
     contents within one (most current) file per module?
   - Why doesn't YANG support nested key leafs?
   - Why does YANG require list keys to be encoded first
     in all NETCONF PDUs?
   - Why can't a leaf be used more than once in the same key?
   - Why doesn't it make sense to use the type 'empty' in a key?
   - Why can't choices be nested?
   - Why does the leaf-list represent a conceptual container
     of N successive instances of 1 leaf, but there is no
     corresponding conceptual container for 'list'?
   - Do augmented nodes with 'when' statements always exist
     for 'must' XPath evaluation purposes in other nodes?
   - What are the differences between instance-identifiers
     and keyref?
   - What happens if keyref objects loop?
   - Why does YANG have a keyref, but no leafref?
   - Why do keyrefs need to match the config value (T/F)
     of the leaf they point at?

I support we could come up with 50 more questions, given
enough time to think about it ;-)

>  Phil

Andy

---

From: David Partain <[email-masked]>
Date: Tue, 19 Aug 2008 21:34:09 +0200

> enough time to think about it ;-)

Hi,

I'm sure we could :-)

We have a wiki we can use and I would strongly support doing so.  If it needs 
to be turned into a document later, that's easy.

Unless someone objects, I'll create a wiki page tomorrow for this purpose and 
populate it with these questions.   We can work out who answers them 
later :-)

Cheers,

David

---

From: Martin Bjorklund <[email-masked]>
Date: Tue, 19 Aug 2008 22:16:34 +0200 (CEST)

Phil Shafer <[email-masked]> wrote:
> the "why" and motivation for the outcome? 

That's my concern as well.  This can't be a new issue within the IETF.
I know that there are lots of RFCs that don't document design
decisions, but are there examples of standards track rfcs that do
document design decisions?

/martin

---

From: David Partain <[email-masked]>
Date: Tue, 19 Aug 2008 23:31:38 +0200

> document design decisions?

Hi all,

I am completely certain you won't get a single answer or even a small number 
of answers to that question.  Ad-hoc is probably the nice way of putting it; 
chaos might be more true :-)

Perhaps we can set a good trend here: the WG's wiki has a FAQ page that 
answers exactly this kind of question.  I think it's worth giving a shot 
since I think wikis are the best way to record collective memory.

Maybe we should also appoint a WG FAQ General whose job it is to keep an eye 
out for recurring questions and put them in the FAQ list...

Cheers,

David

---

From: "tom.petch" <[email-masked]>
Date: Wed, 20 Aug 2008 10:09:03 +0200

----- Original Message -----
From: "Martin Bjorklund" <[email-masked]>
To: <[email-masked]>
Cc: <[email-masked]>
Sent: Tuesday, August 19, 2008 10:16 PM
Subject: Re: [netmod] Recording Motivation

> document design decisions?

I notice the shift, that Joel raised the question of 'design motivations' which
Martin has commuted into 'design decisions' and I think the latter is the more
accurate: and that the discussions on details may be inconclusive or go round in
circles because there is an underlying design decision (eg on reuse, on OO-ness,
...) which I do see clearly spelt out anywhere.  I would write the I-D on these
design decisions  if I could, but do not have the wit to discern these decisions
clearly from the detail of the current I-D.

Likewise Andy's list of "Why doesn't .." seems to me could be paraphrased as
"Someone seems to have decided that ... " ie a design decision has been taken
but not discussed or recorded.

And yes, I think it should be an I-D to best help the current process (and it
may or may not become an RFC) and yes, I think that you do have something
similar in introductory RFC, eg for SNMPv1 and, to a lesser extent, SNMPv3.  In
a different field, I see RFC4984 in a similar role as providing a valuable
backdrop to the discussions on RRG on how to fix the future of routing (another
incredibly active list, albeit an IRTF one).

Tom Petch

---

From: Andy Bierman <[email-masked]>
Date: Wed, 20 Aug 2008 08:42:30 -0700

tom.petch wrote:
....
> but not discussed or recorded.

The purpose of the list was to get people aware of many
decisions that went into the individual submission.
It is time to get buy-in from the WG, or change some things.

I personally agree with many of the decisions, and I can live
with the rest of them. I'm almost done implementing YANG and I
am trying to point out some details from this experience.
IMO, YANG is probably 10X - 50X harder than implementing
SNMP.  I know some of the complexity will go away (like
getting the prefix for a sub-module from its 'belongs-to'.)
I suspect when other implementers figure out how hard it is
to align YANG nodes with XML nodes, more big changes will occur.

Andy

---

From: David Partain <[email-masked]>
Date: Thu, 21 Aug 2008 16:10:06 +0200

Hi all,

Just to close out this thread...

I've created a FAQ page 
(http://wiki.tools.ietf.org/wg/netmod/trac/wiki/YANG_FAQ) as a place to do 
some of this work.  The genesis of this FAQ list is to try to document things 
that are not documented in WG documents ("design decisions").

A few caveats...

1. This FAQ must not distract from getting the WG items done.  If it does, 
we'll just get rid of it.  This must not be the focus of the working group...

2. It's only questions at this point (largely).  If you want to fill in 
answers, please do.

3. It's entirely possible that some of this should make it into documents we 
produce; time will tell.

Cheers,

David