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

From: Juergen Schoenwaelder <[email-masked]>
Date: Fri, 19 Mar 2010 16:34:29 +0100

Hi,

here is my review of draft-ietf-netmod-yang-usage-03.

a) RFC 4741 (and also 4741bis) state that "client" and "application"
   mean the same. Given this, I suggest to only use one term and
   I think this should be "client".

b) RFC 4741 and YANG have confusion concerning the terms "operation"
   and RPC. I suggest we use "operation" when we talk about
   definitions of "operations" using the "rpc" keyword, this not even
   importing the definition of "RPC" (see also h) below).

c) Section 3.1 is confusing:

     This section MUST contain a verbatim copy of the latest approved
     Internet-Standard Management Framework boilerplate, which is
     available on-line, in section 4 of the Trust Legal Provisions (TLP)
     document, at: http://trustee.ietf.org/license-info/

   I assume the "Internet-Standard Management Framework boilerplate"
   is this here <http://ops.ietf.org/mib-boilerplate.html> and hardly
   applicable to YANG modules. Will there be a new one? That said, the
   quoted sentence then starts talking about the TLP stuff, which is
   clearly confusing two separate things.

d) s/Internet Draft or RPC MUST/Internet Draft or RFC MUST/

e) Do we really have to mention NETCONF capabilities?

     A module may be conceptually partitioned in several ways, using the
     'if-feature' and/or 'when' statements.  In addition, NETCONF
     capabilities are designed to identify optional functionality.

   I suggest the last sentence to be removed. Also in the light of
   this text:

     Objects SHOULD NOT directly reference NETCONF capabilities, in order
     to specify optional behavior.  Instead, a 'feature' statement SHOULD
     be defined to represent the NETCONF capability, and the 'if-feature'
     statement SHOULD be used within the object definition.

f) Section 4.6. requires this:

     The description statement MUST be present.  If the module is
     contained in an unpublished document, then the file name of this
     document SHOULD be identified in the description statement.  This
     text MUST be removed when the document is published. 

   It turns out that the sample module in Appendix B has this wrong
   and I also checked the YANG data types modules - they also have
   this wrong. So my conclusion is that the requirement to list the
   filename is a good idea in principle but since authors are lazy,
   the rule will do more harm than being useful. So I suggest to
   remove the requirement to list the file name.

g) Section 4.7 defines a requirement how to choose namespaces for
   unpublished YANG modules. Again, the goals behind this idea are
   good ones, but both the YANG usage guidelines document and the YANG
   data types document fail to comply - they both have an old version
   number in the namespace. Again, I am concerned that we introduce
   rules that would be nice to have but will likely not work in
   practice. I suggest that all text starting with "An unpublished
   module namespace ..." until the end of the section gets removed
   since I doubt these rules will work in practice. (The only way to
   make these rules work would be to completely automate this so that
   xml2rfc ensures the right values are put in place.)

   If the text is not removed, s/RPC/RFC/ in 4.7.

h) Rewrite of 4.12 to avoid "RPC":

   4.12.  Operation Definitions

      The description statement MUST be present in 'rpc' statements
      defining new operations.

      If the operation semantics are defined in an external document, then
      a reference statement SHOULD be present.

      If the operation impacts system behavior in some way, it SHOULD be
      mentioned in the description statement.

      If the operation is potentially harmful to system behavior in some
      way, it MUST be mentioned in the Security Considerations section of
      the document.

i) Appendix A: SNMP boilerplate

   The text says:

     3.   YANG Module Boilerplate -- verify that the draft contains the
          latest approved SNMP Network Management Framework boilerplate
          from the OPS area web site
          (http://www.ops.ietf.org/mib-boilerplate.html). [ed: real URL
          TBD]

   This is related to issue c) above. I doubt we need the SNMP
   boilerplate.

j) Appendix A: MIB security boilerplate

     4.   Security Considerations Section -- verify that the draft uses
          the latest approved template from the OPS area web site
          (http://www.ops.ietf.org/mib-security.html) and that the
          guidelines therein have been followed.

   Again, we might need our own text instead of refering to the MIB
   security boilerplate.

k) Appendix A: Copyright / IPR notices

     7.   Copyright Notices -- verify that the draft contains an
          abbreviated copyright notice in the description statement of
          each YANG module or sub-module, and that it contains the full
          copyright notice and disclaimer specified in Sections 5.4 and
          5.5 of RFC 3978 at the end of the document.  Make sure that the
          correct year is used in all copyright dates.

     8.   IPR Notice -- if the draft does not contains a verbatim copy of
          the IPR notice specified in Section 5 of RFC 3979, recommend
          that the IPR notice be included.

   I think both items need updates to recognize the trust. I have no
   clue what the replacement text should be though. ;-)

l) Appendix B: copyright notice

   I believe we can use a shorter copyright statement but I leave it
   to TLP experts to figure out which one is the right template to
   use.

done :)

/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/>