Guidelines for Authors and Reviewers of Documents Containing YANG Data Models
draft-ietf-netmod-rfc6087bis-20

Thanks for this document. It is well-written and I believe it will be helpful.
Comments follow.

---------------------------------------------------------------------------

General:

I've reviewed a couple of YANG modules where the indentation and/or wrapping was
awkward and inconsistent. I would love to see guidance in this document that
authors be careful to run their modules through pyang (or a similar tool) to
ensure consistent formatting. It may be worthwhile to give an example of the
exact commandline invocation of pyang to achieve a formatting that is consistent
with existing published modules.

---------------------------------------------------------------------------

§3:

>  YANG data model modules under review are likely to be contained in
>  Internet-Drafts.  All guidelines for Internet-Draft authors MUST be
>  followed.  The RFC Editor provides guidelines for authors of RFCs,
>  which are first published as Internet-Drafts.  These guidelines
>  should be followed and are defined in [RFC7322] and updated in
>  [RFC7841] and "RFC Document Style" [RFC-STYLE].

Maybe include a pointer to draft-flanagan-7322bis also, as this document is in
the process of being revised.

---------------------------------------------------------------------------

§3.6:

>  Example YANG modules and example YANG fragments MUST NOT contain any
>  normative text, including any reserved words from [RFC2119]

Please clarify that this means only all-uppercase reserved words.

---------------------------------------------------------------------------

§3.8:

>  If there are no
>  IANA considerations applicable to the document, then the IANA
>  Considerations section stating that there are no actions is removed
>  by the RFC Editor before publication.

I believe that the current state of play is that removal is left to the authors'
discretion, and that the IANA has a weak preference for leaving in sections that
say "No actions are requested of IANA." This may change. Rather than try to
capture the (potentially changing) state of play, my suggestion is to
remove the text I quote above.

---------------------------------------------------------------------------

§3.12:

>  Each specification that defines one or more modules SHOULD contain
>  usage examples, either throughout the document or in an appendix.

Many of the YANG documents I've reviewed over the past year have contained
examples that show only IPv4 addresses. The IAB has issued guidance that
examples in standards track documents use either a mix of IPv4 and IPv6
addresses or IPv6 addresses exclusively (see
<https://www.iab.org/2016/11/07/iab-statement-on-ipv6/>). This section would do
authors and reviewers a great favor by reiterating or pointing to this guidance.

---------------------------------------------------------------------------

§4.11.2:

>  The following typedef from [RFC6991] demonstrates the proper use of
>  the "pattern" statement:
>
>      typedef ipv4-address-no-zone {
>        type inet:ipv4-address {
>          pattern '[0-9\.]*';
>        }
>        ...
>      }

By contrast, RFC 6021 has a somewhat more complex production:

     pattern
         '(([0-9]|[1-9][0-9]|1[0-9][0-9]|2[0-4][0-9]|25[0-5])\.){3}'
       +  '([0-9]|[1-9][0-9]|1[0-9][0-9]|2[0-4][0-9]|25[0-5])'
       + '(%[\p{N}\p{L}]+)?';

Is there any consensus on how complex the pattern validation should be? I've
seen some YANG modules with patterns that occupied more than half a page. Is
that encouraged, discouraged, or neither? It seems some guidance on this
specific issue would be useful, as the currently published modules appear to be
all over the map on this topic.

---------------------------------------------------------------------------

§10.2:

>   [RFC-STYLE]
>              Braden, R., Ginoza, S., and A. Hagens, "RFC Document
>              Style", September 2009,
>              <http://www.rfc-editor.org/rfc-style-guide/rfc-style>.

This URL returns a 404.

(1) This sentence in the Introduction caught my attention: "This document defines a set of usage guidelines for Standards Track documents containing YANG...data models."    The Abstract extends to say that "Applicable portions may be used as a basis for reviews of other YANG data model documents."  

I don't remember a non-Standards Track document off the top of my head [*], but I'm sure the guidelines apply to any IETF document containing a module.  Is that true?  

I see, for example, that in 4.1 (Module Naming Conventions) it is clear how modules published by the IETF should be named...and a note is included about what other SDOs might do.  Are there cases where the guidelines are only applicable to Standards Track documents, but would not apply to other IETF documents?

This may be a nit, but I think it is good to close this door before the justification for non-compliance starts being the Status of a document.

[*] I do remember the IESG talking about whether a document with a module for an Experimental protocol should be in the Standards Track or not.  IMHO, what matters is for the module to be used (i.e. correct, implementable, implemented, etc.) and not the status of the document it is in.

(2) The second paragraph in 2.1. (Requirements Notation) is not needed: "RFC 2119 language...as if it were describing best current practices."  This document is now a BCP.

draft-ietf-netmod-rfc6087bis.txt:500
   normative, if the module itself is considered normative, and not an
   example module or example YANG fragment.  The use of keywords defined
   in [RFC2119] apply to YANG description statements in normative
I think you probably want to rewrite this as:

"Note that if the module itself is considered normative and not an example module or example YANG fragment, then all YANG statements..."



   o  Prefixes are never allowed for built in data types and YANG
      keywords.
I'm not sure I understand what this means. Is the idea that I can't use "example-import" somewhere?



   character MAY be used if the identifier represents a well-known value
   that uses these characters.
Is this text saying that only characters in these two subsets are allowed and therefore, for instance "." is forbidden



   It is RECOMMENDED that only valid YANG modules be included in
   documents, whether or not they are published yet.  This allows:
For clarify, I assume you mean "the modules are published yet"



   The NETCONF Access Control Model (NACM) [I-D.ietf-netconf-rfc6536bis]
   does not support parameter access control for RPC operations.  The
   user is given permission (or not) to invoke the RPC operation with
This might be slightly clearer if you said "parameter-based access control"

Thanks for addressing my DISCUSS and COMMENT points.