Subject: [netmod] LL review of draft-ietf-netmod-yang-usage-03

From: Ladislav Lhotka <[email-masked]>
Date: Sun, 21 Mar 2010 11:49:10 -0700

Hi,

here are my comments to YANG Usage Guidelines:

The text provides useful information for YANG module writers, users and
reviewer. Clearly, the guidelines are based on Andy's extensive
practical experience with YANG.

Specific comments:

Sec. 3.5.2:
Why must the IANA record for the *existing* module be updated if a new
submodule belonging to that module is published? The IANA registry as
defined in Sec. 14 of [YANG] doesn't keep the list of submodules for a
module.

Sec. 4.2:
If the identifier length restriction is meant only for standard-track
modules, it should be clearly stated.

Sec. 4.4:
Fifth paragraph seems to indicate that all node names in XPath
expressions must carry namespace prefixes. It should mention the special
convention for the default namespace that YANG uses.

7th paragraph: There are valid reasons for using position() and last()
for the items of an "ordered-by user" list.

10th paragraph: This is a significant restriction. What are these
misbehaving boundary conditions?

Sec. 4.6:
Paragraph 3: s/documented/document/

Sec. 4.7:
I suggest to rewrite the first paragraph as follows:

It is desirable to include only valid YANG modules in documents, 
whether they are published yet or not. This allows

   o  the module to compile correctly instead of generating
      disruptive fatal errors.

   o  early implementors to use the modules without picking a
      random value for this field.

   o  early interoperability testing since independent
      implementations will use the same namespace value.

Paragraph 4: s/RPC/RFC/

Sec. 4.8:
First paragraph: The second sentence with MAY should be removed - the
definition of SHOULD in RFC 2119 says exactly this.

Paragraph 4: I don't want to re-ignite the discussion on mandatory, but
this is not how YANG spec defines mandatory nodes.

Sec. 4.11:
I am against having a description statement as a MUST. If the YANG code
is sufficiently clear, a description statement is just a nuisance. It
may lead to trivial descriptions like "This grouping contains two
nodes."

Paragraph 4: Is the restriction on "anyxml" necessary? I can imagine a
"banner" configuration statement which is allowed to contain HTML - it
may be defined as "anyxml".

Paragraph 6: I don't understand "max-elements" statement in this way.

Lada  

-- 
Ladislav Lhotka, CESNET
PGP Key ID: E74E8C0C