Subject: [netmod] js review of draft-ietf-netmod-yang-usage-04

From: Juergen Schoenwaelder <[email-masked]>
Date: Fri, 7 May 2010 09:49:55 +0200

Hi,

here is my WG last call review of draft-ietf-netmod-yang-usage-04. The
document is in a good shape; I only have a number of minor, mostly
editorial and terminology related, comments.

- p4: This sounds odd: "MIB usage guidelines specification [RFC 4181]" since
      RFC 4181 is not about the usage of MIBs; its about the usage of SMIv2

- YANG is sometimes Yang - capitalization should perhaps be made
  consistent

- p7: What is this "YANG data model boilerplate section" that must be
      present?  Should there be a URL, similar to the URL for the
      security template?

- p7: Should section 3.1 explain the 

        <CODE BEGINS> file "[email-masked]"

      convention we have adopted lately?

- p8: s/interpretations of objects in other modules/interpretations of definitions in other modules/

- p8: http://www.ops.ietf.org/yang-security.html does not exist yet...

- p8: s/writable module objects/writable data nodes/

- p8: s/readable module objects/readable data nodes/

- p8: Should section 3.5 have a reference to RFC 5226?

- p9: I am not sure why all references statements appearing in YANG
      module are normative. OK, this guideline is a SHOULD, but even
      this seems rather strong - I do not recall we have this
      requirement in RFC 4181.

- p10: Rewrite section 4.2 to avoid talking about "data objects" since
       this is not a defined term. Should we talk about schema nodes
       instead (and import that term in section 2.3)? Or was there a
       reason to not establish length restrictions for identifiers of
       say choices?

- p11: s/Objects SHOULD NOT/Data definition SHOULD NOT/

- p11: Section 4.4 puts up requirements for XPATH expressions without
       first making it clear that the text starts talking about XPATH
       expressions. Since XPATH expressions are also used in must
       statements, perhaps this discussion should be factored out into
       a separate section "4.X XPATH Expressions".

- p11: I do not understand this guideline:

         The 'position' and 'last' functions MAY be used with caution, within
         a single server implementation.

       What is a single server implementation?

- p12: The term "header" is not well defined. In YANG, module-header
       statements just include yang version, namespace and prefix
       statements. The organization and description statements belong
       to meta statements and revision statements to well revision
       statements. OK, it seems YANG itself is not very consistent
       here. One way out could be to label 4.6 "Module Header, Meta,
       and Revision Statements".

- p14: s/Top Level Database Objects/Top Level Data Nodes/

- p15: s/Top-level database objects/Top-level data nodes/

- p15: s/object semantics SHOULD NOT/data node semantics SHOULD NOT/

- p16: I am not sure "Object Definitions" is the right heading, unless
       we define somewhere what an object is. 

- p16: I also do not follow the distinction between body statements
       and data definition statements. In the YANG spec, data
       definition statements seem to be part of the body statements. I
       suggest to collapse the two lists into one and to have the
       sentence before the list changed to:

       	 The description statement MUST be present in the statements:

- p17: s/If the object semantics/If semantics/

- p19: The security considerations could mention that the document
       establishes guidelines what needs to be covered in the security
       considerations of documents containing YANG modules.

- p23: There should be a concrete URL replacing "[YANG tool URL TBD]".

/js

-- 
Juergen Schoenwaelder           Jacobs University Bremen gGmbH
Phone: +49 421 200 3587         Campus Ring 1, 28759 Bremen, Germany
Fax:   +49 421 200 3103         <http://www.jacobs-university.de/>

---

From: Andy Bierman <[email-masked]>
Date: Tue, 18 May 2010 11:43:50 -0700

Juergen Schoenwaelder wrote:
> ...
[all comments addressed in new version, except...]

> - p23: There should be a concrete URL replacing "[YANG tool URL TBD]".

Not sure what to do about this, because
there is no ietf.org tool to point at.

I could include this:
http://www.netconfcentral.org/run_yangdump
but I doubt the IESG wants that, since I cannot
insure this URL will be around forever.

The plan was to run pyang or yangdump on an ietf.org site,
but that requires a lot of programming work.
My code is Turbogears-1 based Python and the
IETF uses Django, so there has been no progress
at all to run yangdump on an ietf.org WEB page.

I could remove the section and YANG authors can
figure it out on their own without any IETF help.

> /js

Andy