Re: [netmod] rfc6087bis shepherd writeup issues

[Andy Bierman <[e-mail]>]

Hi,

I posted draft-16 which has all changes below except the unused reference
for RFC 5378.
The idnits tool is wrong. It ignores usage in an appendix.

Andy


On Mon, Jan 15, 2018 at 2:15 PM, Kent Watsen <[e-mail]> wrote:

> Hi Andy,
>
>
> 1) before I forget, could you please confirm one more time (the last time
> being in 2016, sheesh!) that you are unaware of any IPR that needs to be
> filed for this draft, according to BCPs 78 and 79?
>
>
>
> 2) Idnits found three warnings, only the first might require thought for
> how best to fix it:
>
>   == Unused Reference: 'RFC5378' is defined on line 2502, but no explicit
>      reference was found in the text
>
>   == Outdated reference: A later version (-10) exists of
>      draft-ietf-netmod-revised-datastores-07
>
>   == Outdated reference: A later version (-04) exists of
>      draft-ietf-netmod-yang-tree-diagrams-02
>
>
>
> 3) in the Introduction, would this be better?
>  OLD
>    The standardization of network configuration interfaces for use with
>    ***the Network Configuration Protocol [RFC6241] and RESTCONF
> [RFC8040]***
>    requires a modular set of data models, which can be reused and
>    extended over time.
>  NEW
>    The standardization of network configuration interfaces for use with
>    network configuration management protocols, such as NETCONF [RFC6241]
>    and RESTCONF [RFC8040], requires a modular set of data models, which
>    can be reused and extended over time.
>
>
> 4) In the next paragraph, should "server" be qualified?
>    A *NETCONF or RESTCONF* server that supports
>    a particular YANG module will support client NETCONF and/or RESTCONF
>    operation requests, as indicated by the specific content defined in
>    the YANG module.
>
>
> 5) The next paragraph is no longer accurate and, given its value is
> unless, maybe it should be removed altogether?
>  OLD
>    This document is similar to the Structure of Management Information
>    version 2 (SMIv2) usage guidelines specification [RFC4181] in intent
>    and structure.  However, since that document was written a decade
>    after SMIv2 modules had been in use, it was published as a 'Best
>    Current Practice' (BCP).  This document is not a BCP, but rather an
>    informational reference, intended to promote consistency in documents
>    containing YANG modules.
>
>
> 6) In the next paragraph, something seems off with the "may require"
> language.  Should it be just "requires" or perhaps "entails"?   Also, is it
> really to "maximize interoperability of NETCONF and RESTCONF
> implementations", or more just to make YANG modules more useful?
>  OLD
>    Many YANG constructs are defined as optional to use, such as the
>    description statement.  However, in order to ***maximize
>    interoperability of NETCONF and RESTCONF implementations utilizing
>    YANG data models***, it is desirable to define a set of usage guidelines
>    that ***may require*** a higher level of compliance than the minimum
> level
>    defined in the YANG specification.
>
>
> 7) In the Terminology Section, please add a normative reference to RFC
> 8174, Section 2.  The expected result follows:
>       The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
>       NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED",
>       "MAY", and "OPTIONAL" in this document are to be interpreted as
>       described in BCP 14 [RFC2119] [RFC8174] when, and only when, they
>       appear in all capitals, as shown here.
>
>
> 8) Should the reference to RFC 6991 be informative instead?
>
>
> 9) The reference to the tree-diagrams draft being informative caught my
> eye. Looking into it revealed more:
> 9a) I think that Section 2.5.1 should be deleted, as the draft itself does
> not define any tree diagrams outside of sections 3.4, which already has a
> reference to that draft (as it should).
> 9b) should the guidelines make the Section 3.3 recommendation anymore?  -
> I thought that one of the main benefits of having the tree-diagrams draft
> was so that other drafts could easily inline-reference it, so as to avoid
> needing to say anything in their Terminology sections.
> 9c) I think Section 3.4 should 1) say that drafts should prefix each
> tree-diagram with a *normative* reference to the tree-diagrams draft and 2)
> update the example illustrating how it might be done.
> 9d) Finally, back to the tree-diagrams draft being informative, yes, I
> guess it is informative after all.  c'est la vie  ;)
>
>
> 10) Should Section 8 (Changes to RFC 6087) be moved to the Introduction?
> Note that the shepherd checklist says "If publication of this document
> changes the status of any existing RFCs, are those RFCs listed on the title
> page header, and are the changes listed in the abstract and discussed
> (explained, not just mentioned) in the introduction?"
>
>
> 11) I think that Section 6 (Security Considerations) should be largely
> moved into Section 3.7.  For this document, Section 6 should probably just
> say something like "This document only defines guidelines for YANG module
> designers and therefore does not itself have any Security considerations
> that need to be listed here."  What do you think?
>
>
> Thanks,
> Kent  // shepherd
>
>
>
> _______________________________________________
> netmod mailing list
> [e-mail]
> https://www.ietf.org/mailman/listinfo/netmod
>