Re: [netmod] Adam Roach's No Objection on draft-ietf-netmod-rfc6087bis-18: (with COMMENT)

[Andy Bierman <[e-mail]>]

On Thu, Mar 8, 2018 at 1:33 AM, Adam Roach <[e-mail]> wrote:

> Adam Roach has entered the following ballot position for
> draft-ietf-netmod-rfc6087bis-18: No Objection
>
> When responding, please keep the subject line intact and reply to all
> email addresses included in the To and CC lines. (Feel free to cut this
> introductory paragraph, however.)
>
>
> Please refer to https://www.ietf.org/iesg/statement/discuss-criteria.html
> for more information about IESG DISCUSS and COMMENT positions.
>
>
> The document, along with other ballot positions, can be found here:
> https://datatracker.ietf.org/doc/draft-ietf-netmod-rfc6087bis/
>
>
>
> ----------------------------------------------------------------------
> COMMENT:
> ----------------------------------------------------------------------
>
> 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.
>
>
I added text that says consistent indentation and formatting SHOULD be used.



> ------------------------------------------------------------
> ---------------
>
> §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.
>


This does not appear to be a WG document, so it seems premature to include
it



>
> ------------------------------------------------------------
> ---------------
>
> §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.
>
>
OK



> ------------------------------------------------------------
> ---------------
>
> §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.
>
>
This was just changed to "might be removed"

Is that good enough?



> ------------------------------------------------------------
> ---------------
>
> §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.
>
>
OK



> ------------------------------------------------------------
> ---------------
>
> §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.
>
>
Not changing any text since the pattern complexity depends on the structure
of the text that is being modeled.



> ------------------------------------------------------------
> ---------------
>
> §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.
>
>

changed top http://www.rfc-editor.org/styleguide/



Andy


>