Subject: [netmod] Working Group Last Call: Guidelines for Authors and Reviewers of YANG Data Model Documents

From: David Partain <[email-masked]>
Date: Mon, 8 Mar 2010 09:50:11 +0100

Greetings,

This is a 14-day working group last call on the current working group 
document:

- Guidelines for Authors and Reviewers of YANG Data Model Documents
http://www.ietf.org/draft-ietf-netmod-yang-usage-03.txt

This WGLC will end on March 22, 2010.  Please review the document and post 
your comments on the mailing list.

Please use an appropriate Subject line so that the chairs and editor can 
easily keep track of the issues that need to be dealt with.

Thanks.

David^2

---

From: Tomasz Mikolajczyk <[email-masked]>
Date: Mon, 8 Mar 2010 09:54:16 +0100

Hi,

Seems that the link doesn't work.

Regards,
Tomasz Mikolajczyk

---

From: David Partain <[email-masked]>
Date: Mon, 8 Mar 2010 10:09:12 +0100

Greetings,

My fault, sorry.   Cut & paste silliness.

The correct link is of course:

http://www.ietf.org/id/draft-ietf-netmod-yang-usage-03.txt

Cheers,

David

On Monday 08 March 2010 09.54.16 Tomasz Mikolajczyk wrote:
> > This WGLC will end on March 22, 2010.  Please review the document and
> > post your comments on the mailing list.
> >

---

From: Martin Bjorklund <[email-masked]>
Date: Wed, 17 Mar 2010 12:36:02 +0100 (CET)

Hi,

I have reviewed this document, and here are my comments:

sec 2.2.
--------
  The term 'application' is not used (at least not in the 4741 sense)

sec 4.1.
--------  
  The text says:

    Modules contained in standards track documents SHOULD be named
    with the prefix 'ietf-'.  Other types of modules MUST NOT use the
    'ietf-' prefix string.

  But the YANG spec has a different text in its IANA Considerations:

   The module name prefix 'ietf-' is reserved for IETF stream documents
   [RFC4844] while the module name prefix 'irtf-' is reserved for IRTF
   stream documents.  Modules published in other RFC streams must have a
   similar suitable prefix.  The prefix 'iana-' is reserved for modules
   maintained by IANA.

  I suggest the text in this document is removed, or aligned with the
  YANG text, or replaced with a pointer to the YANG text.

sec 4.4.
--------
  The text says:

   All 'must' and 'when' statements MUST contain valid XPath.  If any
   name tests are present, they MUST contain valid module prefixes and
   data node names.  References to non-existent nodes are considered
   invalid in YANG, even though they are permitted in XPath.

  The last sentence is not correct and should be removed.

sec 4.5.
--------

   The text says:

     The module namespace URI value SHOULD NOT be changed, once the
     document containing the module is published.

   The YANG spec says, in sec 10:

     Furthermore, the "namespace" statement MUST NOT be changed,

   Either s/SHOULD NOT/MUST NOT/  or remove the sentence (since it is
   redundant).

sec 4.6.
--------

   The text says:

     The reference statement MUST be present.  It MUST identify the
     published document which contains the module.

     [...]

     A revision statement MUST be present for each published version of
     the module.

   This is not what we're currently using in yang-types and netconf
   monitoring.

   I suggest the first quoted paragraph is removed, and the second is
   extended with:

     The revision statement MUST have a reference substatement. It
     MUST identify the published document which contains the module.

sec 4.7
-------

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

  which field?  It seems some intro sentence is missing in this
  section.

Appendix A.
-----------

  There are quite a few TBD and missing links here.  Do we have a plan
  for fixing them?

/martin

---

From: Phil Shafer <[email-masked]>
Date: Wed, 17 Mar 2010 07:38:22 -0400

>  The last sentence is not correct and should be removed.

The first sentence is redundant (since YANG already requires valid
xpath expressions) and should be removed.  The second is also
redundant, since valid prefixes and node names are required for
valid xpath expressions (in the sense that a node name must follow
the rules of what is a valid node name, not that the node must match
a node defined in the YANG module).

Thanks,
 Phil