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

[Ballot 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.

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

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

This URL returns a 404.

[Ballot comment]
Thanks for this very readable and informative document. I am balloting YES, but I do have a few minor comments:

Substantive Comments:

§3, first paragraph:

Can there be a citation for internet-draft guidelines? Also, it seems odd to have a normative MUST for I-D guidelines, but the RFC guidelines are not normative?

§3.5: Is the referenced draft in the example likely to become an RFC prior to publication? As it is, the way it is referenced looks a lot like a citation, which are not recommended in an abstract.

§3.7:  The URL in the second paragraph is very dependent on the structure of the tools pages. Any reorganization of those pages is likely to break the link. I wonder if there is a way to alias that to something less brittle.

§4.8, 2nd paragraph: I’m surprised to see the WG mail list a MUST level requirement here. WGs (and their mailing lists) come and go. I think, in many cases, it would make more sense to list the IESG as the contact, at least for standards track models. (I’ve seen us do that more often lately for IANA registrations, and this seems in the same spirit.)

I can see that it might still make sense to reference the WG list in some circumstances, but MUST seems excessive.
.
Editorial Comments and Nits:

§3.9, last paragraph:

There are two clauses starting with “, which”, which I think are intended as restrictive clauses. Consider s/“, which”/“that”

[Ballot comment]
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"

[Ballot comment]
(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.

[Ballot discuss]
* Section 4.25

I think this might be a simple misunderstanding but I have no idea what compliance with this statement implies.

"A YANG module MUST NOT be designed such that the set of modules found on a server implementation can be predetermined in advance."

Can you please clarify?

[Ballot comment]
Section 3.2:
  The date looks to be contradictory between the explanatory text

"The following example is for the '2010-01-18' revision of the 'ietf-foo' module:"

and the actual code component defined right after

  file "ietf-foo@2016-03-20.yang"
...
        revision 2016-03-20 {
...

* Section 4.8

I went over this text several times to figure out what it means. Can you simplify this, or provide examples as to when revision dates are/are not to be updated.

  It is not required to keep the full revision history of draft
  versions (e.g., modules contained within Internet-Drafts).  That is,
  within a sequence of draft versions, only the most recent revision
  need be recorded in the module.  However, whenever a new (i.e.
  changed) version is made available (e.g., via a new version of an
  Internet-Draft), the revision date of that new version MUST be
  updated to a date later than that of the previous version.

* Section 4.14.1.  Non-Presence Container

So what is the guideline here? That there is no guideline?

* Section 4.20

What does "cannot" imply here? MUST NOT? SHOULD NOT?

"The YANG "deviation" statement cannot appear in IETF YANG modules"

[Ballot comment]
Thank you for a great document. Some minor comments:

3.8.  IANA Considerations Section

  In order to comply with IESG policy as set forth in
  http://www.ietf.org/id-info/checklist.html, every Internet-Draft that
  is submitted to the IESG for publication MUST contain an IANA
  Considerations section.  The requirements for this section vary
  depending on what actions are required of the IANA.  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.

IANA's and RFC Editor opinion about empty IANA Considerations section has changed over time (and might change again), so I would not make this statement. I don't think this is necessarily the current policy. RFC Editor asks, but doesn't enforce this. So I suggest changing "is removed" to "might be removed".


[I-D.ietf-netmod-revised-datastores] - I am pretty sure that some uses of this document are normative, so you should move it to Normative References.

[Ballot comment]
Thanks for your work on this draft and in particular Section 3.7 with the updated Security Considerations Section template and pointer to one that can change over time.

It looks like the authors may not have seen Stephen's questions from his SecDir review, please respond:
https://mailarchive.ietf.org/arch/msg/secdir/jnAnJVymlTlKmLrqNBIfntWdJ4c

[Ballot comment]
Thanks for your work on this draft and the updated Security Considerations Section template!

Please respond to Stephen's questions from his SecDir review:
https://mailarchive.ietf.org/arch/msg/secdir/jnAnJVymlTlKmLrqNBIfntWdJ4c

(Via drafts-lastcall@iana.org): IESG/Authors/WG Chairs:

The IANA Services Operator has completed its review of draft-ietf-netmod-rfc6087bis-18. If any part of this review is inaccurate, please let us know.

The IANA Services Operator has a question about one of the actions requested in the IANA Considerations section of this document.

The IANA Services Operator understands that, upon approval of this document, there are two actions which we must complete.

First, in the ns registry on the IETF XML Registry page located at:

https://www.iana.org/assignments/xml-registry/

the existing registration for urn:ietf:params:xml:ns:yang:ietf-template

will have its reference changed from

RFC 6087.

IANA Question --> Should the new reference include both RFC 6087 and [ RFC-to-be ] or should it reference [ RFC-to-be ] only?

IANA understands that there are no other changes to be made to this registration.

Second, in the YANG Module Names registry on the YANG Parameters registry page located at:

https://www.iana.org/assignments/yang-parameters/

the existing registration for the YANG Module Name:

ietf-template

will have its reference changed from

RFC 6087

IANA Question --> Should the new reference include both RFC 6087 and [ RFC-to-be ] or should it reference [ RFC-to-be ] only?

We understand that there are no other changes to be made to this registration.

IANA Question --> Are there any other instances in YANG related registrations where the Reference to RFC 6087 should be changed?

The IANA Services Operator understands that these are the only actions required to be completed upon approval of this document.

Note:  The actions requested in this document will not be completed until the document has been approved for publication as an RFC. This message is meant only to confirm the list of actions that will be performed.


Thank you,

Sabrina Tanamal
Senior IANA Services Specialist

The following Last Call announcement was sent out (ends 2018-03-07):

From: The IESG
To: IETF-Announce
CC: bclaise@cisco.com, netmod-chairs@ietf.org, kwatsen@juniper.net, netmod@ietf.org, draft-ietf-netmod-rfc6087bis@ietf.org
Reply-To: ietf@ietf.org
Sender:
Subject: Last Call:  (Guidelines for Authors and Reviewers of YANG Data Model Documents) to Best Current Practice


The IESG has received a request from the Network Modeling WG (netmod) to
consider the following document: - 'Guidelines for Authors and Reviewers of
YANG Data Model Documents'
  as Best Current Practice

The IESG plans to make a decision in the next few weeks, and solicits final
comments on this action. Please send substantive comments to the
ietf@ietf.org mailing lists by 2018-03-07. Exceptionally, comments may be
sent to iesg@ietf.org instead. In either case, please retain the beginning of
the Subject line to allow automated sorting.

Abstract


  This memo provides guidelines for authors and reviewers of Standards
  Track specifications containing YANG data model modules.  Applicable
  portions may be used as a basis for reviews of other YANG data model
  documents.  Recommendations and procedures are defined, which are
  intended to increase interoperability and usability of Network
  Configuration Protocol (NETCONF) and RESTCONF protocol
  implementations that utilize YANG data model modules.  This document
  obsoletes RFC 6087.




The file can be obtained via
https://datatracker.ietf.org/doc/draft-ietf-netmod-rfc6087bis/

IESG discussion can be tracked via
https://datatracker.ietf.org/doc/draft-ietf-netmod-rfc6087bis/ballot/


No IPR declarations have been submitted directly on this I-D.


The document contains these normative downward references.
See RFC 3967 for additional information:
    rfc6021: Common YANG Data Types (Proposed Standard - IETF stream)
    rfc7950: The YANG 1.1 Data Modeling Language (Proposed Standard - IETF stream)
    rfc4741: NETCONF Configuration Protocol (Proposed Standard - IETF stream)
    rfc4742: Using the NETCONF Configuration Protocol over Secure SHell (SSH) (Proposed Standard - IETF stream)

As required by RFC 4858, this is the current template for the Document
Shepherd Write-Up.

Changes are expected over time. This version is dated 24 February 2012.

(1) What type of RFC is being requested (BCP, Proposed Standard, Internet Standard, Informational, Experimental, or Historic)? Why is this the proper type of RFC? Is this type of RFC indicated in the title page header?

BCP

(2) The IESG approval announcement includes a Document Announcement Write-Up. Please provide such a Document Announcement Write-Up. Recent examples can be found in the "Action" announcements for approved documents. The approval announcement contains the following sections:

Technical Summary:

Relevant content can frequently be found in the abstract and/or introduction of the document. If not, this may be an indication that there are deficiencies in the abstract or introduction.


  This memo provides guidelines for authors and reviewers of Standards
  Track specifications containing YANG data model modules.  Applicable
  portions may be used as a basis for reviews of other YANG data model
  documents.  Recommendations and procedures are defined, which are
  intended to increase interoperability and usability of Network
  Configuration Protocol (NETCONF) and RESTCONF protocol
  implementations that utilize YANG data model modules.  This document
  obsoletes RFC 6087.

Working Group Summary:

Was there anything in WG process that is worth noting? For example, was there controversy about particular points or were there decisions where the consensus was particularly rough?

  Consensus was reached among all interested parties before
  requesting the publication of this document.


Document Quality:

Are there existing implementations of the protocol? Have a significant number of vendors indicated their plan to implement the specification? Are there any reviewers that merit special mention as having done a thorough review, e.g., one that resulted in important changes or a conclusion that the document had no substantive issues? If there was a MIB Doctor, Media Type or other expert review, what was its course (briefly)? In the case of a Media Type review, on what date was the request posted?

  Multiple implementers of YANG and those who write
  models using YANG have reviewed the document.


Personnel:

Who is the Document Shepherd? Who is the Responsible Area Director?

  Kent Watsen is the Document Shepherd for this document? 
  Benoit Claise is the Responsible Area Director.


(3) Briefly describe the review of this document that was performed by the Document Shepherd. If this version of the document is not ready for publication, please explain why the document is being forwarded to the IESG.

The Document Shepherd went through the checklist listed here: http://trac.tools.ietf.org/group/iesg/trac/wiki/DraftShepherdWriteupWgAlternate


(4) Does the document Shepherd have any concerns about the depth or breadth of the reviews that have been performed?

No concerns


(5) Do portions of the document need review from a particular or from broader perspective, e.g., security, operational complexity, AAA, DNS, DHCP, XML, or internationalization? If so, describe the review that took place.

No portions of the document have been flagged as needing to be reviewed
from a particular or broader perspective.


(6) Describe any specific concerns or issues that the Document Shepherd has with this document that the Responsible Area Director and/or the IESG should be aware of? For example, perhaps he or she is uncomfortable with certain parts of the document, or has concerns whether there really is a need for it. In any event, if the WG has discussed those issues and has indicated that it still wishes to advance the document, detail those concerns here.

The Document Shepherd has no specific concerns or issues with this document.


(7) Has each author confirmed that any and all appropriate IPR disclosures required for full conformance with the provisions of BCP 78 and BCP 79 have already been filed. If not, explain why?

The author has confirmed that there is no IPR to be filed for this draft.


(8) Has an IPR disclosure been filed that references this document? If so, summarize any WG discussion and conclusion regarding the IPR disclosures.

No IPR disclosure have been filed.


(9) How solid is the WG consensus behind this document? Does it represent the strong concurrence of a few individuals, with others being silent, or does the WG as a whole understand and agree with it?

Strong support by many individuals.


(10) Has anyone threatened an appeal or otherwise indicated extreme discontent? If so, please summarise the areas of conflict in separate email messages to the Responsible Area Director. (It should be in a separate email because this questionnaire is publicly available.)

No one has threatened an appeal otherwise indicated extreme discontent.


(11) Identify any ID nits the Document Shepherd has found in this document. (See http://www.ietf.org/tools/idnits/ and the Internet-Drafts Checklist). Boilerplate checks are not enough; this check needs to be thorough.

Following are non-issues found by idnits:

  == The document seems to lack the recommended RFC 2119 boilerplate, even if
    it appears to use RFC 2119 keywords -- however, there's a paragraph with
    a matching beginning. Boilerplate error?

    NO ONE COULD FIND AN ERROR BEFORE, BUT NOT I THINK I SEE THAT THE ISSUE
    IS THAT IT"S MISSING "NOT RECOMMENDED" IN THE LIST.  I DON'T BELIEVE
    THAT IT'S WORTH ASKING FOR AN UPDATE TO FIX IT PRIOR TO BEING SUBMITTED,
    AS IT CAN BE FIXED IN THE NEXT UPDATE, OR DURING AUTH48.

  -- Found something which looks like a code comment -- if you have code
    sections in the document, please surround them with '' and
    '' lines.

    THERE ARE 156 "--" IN THE DRAFT, NONE OF WHICH SHOULD BE WRAPPED BY
    '' and '' lines.

  == Unused Reference: 'RFC5378' is defined on line 2502, but no explicit
    reference was found in the text

    THIS APPEARS TO BE AN IDNITS BUG.  THE REFERENCE IS CLEARLY VISIBLE
    IN THE APPENDIX, AND EVEN HYPERLINKS TO THE RIGHT SPOT IN THE
    REFERENCES SECTION.


(12) Describe how the document meets any required formal review criteria, such as the MIB Doctor, media type, and URI type reviews.

This document does not define any artifacts needing formal reviews.


(13) Have all references within this document been identified as either normative or informative?

Yes, all references have been partitioned into these two groupings. 


(14) Are there normative references to documents that are not ready for advancement or are otherwise in an unclear state? If such normative references exist, what is the plan for their completion?

There are no normative references to documents that are not ready for advancement or are otherwise in an unclear state.


(15) Are there downward normative references (see RFC 3967)? If so, list these downward references to support the Area Director in the Last Call procedure.

There are no downward references.


(16) Will publication of this document change the status of any existing RFCs? Are those RFCs listed on the title page header, listed in the abstract, and discussed in the introduction? If the RFCs are not listed in the Abstract and Introduction, explain why, and point to the part of the document where the relationship of this document to the other RFCs is discussed. If this information is not in the document, explain why the WG considers it unnecessary.

Publication of this document will obsolete RFC 6087.
There is a "Changes Since RFC 6087" section in the Introduction.


(17) Describe the Document Shepherd's review of the IANA considerations section, especially with regard to its consistency with the body of the document. Confirm that all protocol extensions that the document makes are associated with the appropriate reservations in IANA registries. Confirm that any referenced IANA registries have been clearly identified. Confirm that newly created IANA registries include a detailed specification of the initial contents for the registry, that allocations procedures for future registrations are defined, and a reasonable name for the new registry has been suggested (see RFC 5226).

The draft does not define any new registries.  This draft doesn't does move an RFC 6087 registration to this draft.


(18) List any new IANA registries that require Expert Review for future allocations. Provide any public guidance that the IESG would find useful in selecting the IANA Experts for these new registries.

This document does not define any new IANA registries.



(19) Describe reviews and automated checks performed by the Document Shepherd to validate sections of the document written in a formal language, such as XML code, BNF rules, MIB definitions, etc.

The shepherd validated both YANG examples (ietf-foo.yang and ietf-template.yang) using the `pyang` tool with the "--ietf" flag set.





As required by RFC 4858, this is the current template for the Document
Shepherd Write-Up.

Changes are expected over time. This version is dated 24 February 2012.

(1) What type of RFC is being requested (BCP, Proposed Standard, Internet Standard, Informational, Experimental, or Historic)? Why is this the proper type of RFC? Is this type of RFC indicated in the title page header?

BCP

(2) The IESG approval announcement includes a Document Announcement Write-Up. Please provide such a Document Announcement Write-Up. Recent examples can be found in the "Action" announcements for approved documents. The approval announcement contains the following sections:

Technical Summary:

Relevant content can frequently be found in the abstract and/or introduction of the document. If not, this may be an indication that there are deficiencies in the abstract or introduction.


  This memo provides guidelines for authors and reviewers of Standards
  Track specifications containing YANG data model modules.  Applicable
  portions may be used as a basis for reviews of other YANG data model
  documents.  Recommendations and procedures are defined, which are
  intended to increase interoperability and usability of Network
  Configuration Protocol (NETCONF) and RESTCONF protocol
  implementations that utilize YANG data model modules.  This document
  obsoletes RFC 6087.

Working Group Summary:

Was there anything in WG process that is worth noting? For example, was there controversy about particular points or were there decisions where the consensus was particularly rough?

  Consensus was reached among all interested parties before
  requesting the publication of this document.


Document Quality:

Are there existing implementations of the protocol? Have a significant number of vendors indicated their plan to implement the specification? Are there any reviewers that merit special mention as having done a thorough review, e.g., one that resulted in important changes or a conclusion that the document had no substantive issues? If there was a MIB Doctor, Media Type or other expert review, what was its course (briefly)? In the case of a Media Type review, on what date was the request posted?

  Multiple implementers of YANG and those who write
  models using YANG have reviewed the document.


Personnel:

Who is the Document Shepherd? Who is the Responsible Area Director?

  Kent Watsen is the Document Shepherd for this document? 
  Benoit Claise is the Responsible Area Director.


(3) Briefly describe the review of this document that was performed by the Document Shepherd. If this version of the document is not ready for publication, please explain why the document is being forwarded to the IESG.

The Document Shepherd went through the checklist listed here: http://trac.tools.ietf.org/group/iesg/trac/wiki/DraftShepherdWriteupWgAlternate


(4) Does the document Shepherd have any concerns about the depth or breadth of the reviews that have been performed?

No concerns


(5) Do portions of the document need review from a particular or from broader perspective, e.g., security, operational complexity, AAA, DNS, DHCP, XML, or internationalization? If so, describe the review that took place.

No portions of the document have been flagged as needing to be reviewed
from a particular or broader perspective.


(6) Describe any specific concerns or issues that the Document Shepherd has with this document that the Responsible Area Director and/or the IESG should be aware of? For example, perhaps he or she is uncomfortable with certain parts of the document, or has concerns whether there really is a need for it. In any event, if the WG has discussed those issues and has indicated that it still wishes to advance the document, detail those concerns here.

The Document Shepherd has no specific concerns or issues with this document.


(7) Has each author confirmed that any and all appropriate IPR disclosures required for full conformance with the provisions of BCP 78 and BCP 79 have already been filed. If not, explain why?

The author has confirmed that there is no IPR to be filed for this draft.


(8) Has an IPR disclosure been filed that references this document? If so, summarize any WG discussion and conclusion regarding the IPR disclosures.

No IPR disclosure have been filed.


(9) How solid is the WG consensus behind this document? Does it represent the strong concurrence of a few individuals, with others being silent, or does the WG as a whole understand and agree with it?

Strong support by many individuals.


(10) Has anyone threatened an appeal or otherwise indicated extreme discontent? If so, please summarise the areas of conflict in separate email messages to the Responsible Area Director. (It should be in a separate email because this questionnaire is publicly available.)

No one has threatened an appeal otherwise indicated extreme discontent.


(11) Identify any ID nits the Document Shepherd has found in this document. (See http://www.ietf.org/tools/idnits/ and the Internet-Drafts Checklist). Boilerplate checks are not enough; this check needs to be thorough.

Following are non-issues found by idnits:

  == The document seems to lack the recommended RFC 2119 boilerplate, even if
    it appears to use RFC 2119 keywords -- however, there's a paragraph with
    a matching beginning. Boilerplate error?

    NO ONE COULD FIND AN ERROR BEFORE, BUT NOT I THINK I SEE THAT THE ISSUE
    IS THAT IT"S MISSING "NOT RECOMMENDED" IN THE LIST.  I DON'T BELIEVE
    THAT IT'S WORTH ASKING FOR AN UPDATE TO FIX IT PRIOR TO BEING SUBMITTED,
    AS IT CAN BE FIXED IN THE NEXT UPDATE, OR DURING AUTH48.

  -- Found something which looks like a code comment -- if you have code
    sections in the document, please surround them with '' and
    '' lines.

    THERE ARE 156 "--" IN THE DRAFT, NONE OF WHICH SHOULD BE WRAPPED BY
    '' and '' lines.

  == Unused Reference: 'RFC5378' is defined on line 2502, but no explicit
    reference was found in the text

    THIS APPEARS TO BE AN IDNITS BUG.  THE REFERENCE IS CLEARLY VISIBLE
    IN THE APPENDIX, AND EVEN HYPERLINKS TO THE RIGHT SPOT IN THE
    REFERENCES SECTION.


(12) Describe how the document meets any required formal review criteria, such as the MIB Doctor, media type, and URI type reviews.

This document does not define any artifacts needing formal reviews.


(13) Have all references within this document been identified as either normative or informative?

Yes, all references have been partitioned into these two groupings. 


(14) Are there normative references to documents that are not ready for advancement or are otherwise in an unclear state? If such normative references exist, what is the plan for their completion?

There are no normative references to documents that are not ready for advancement or are otherwise in an unclear state.


(15) Are there downward normative references (see RFC 3967)? If so, list these downward references to support the Area Director in the Last Call procedure.

There are no downward references.


(16) Will publication of this document change the status of any existing RFCs? Are those RFCs listed on the title page header, listed in the abstract, and discussed in the introduction? If the RFCs are not listed in the Abstract and Introduction, explain why, and point to the part of the document where the relationship of this document to the other RFCs is discussed. If this information is not in the document, explain why the WG considers it unnecessary.

Publication of this document will obsolete RFC 6087.
There is a "Changes Since RFC 6087" section in the Introduction.


(17) Describe the Document Shepherd's review of the IANA considerations section, especially with regard to its consistency with the body of the document. Confirm that all protocol extensions that the document makes are associated with the appropriate reservations in IANA registries. Confirm that any referenced IANA registries have been clearly identified. Confirm that newly created IANA registries include a detailed specification of the initial contents for the registry, that allocations procedures for future registrations are defined, and a reasonable name for the new registry has been suggested (see RFC 5226).

The draft does not define any new registries.  This draft doesn't does move an RFC 6087 registration to this draft.


(18) List any new IANA registries that require Expert Review for future allocations. Provide any public guidance that the IESG would find useful in selecting the IANA Experts for these new registries.

This document does not define any new IANA registries.



(19) Describe reviews and automated checks performed by the Document Shepherd to validate sections of the document written in a formal language, such as XML code, BNF rules, MIB definitions, etc.

The shepherd validated both YANG examples (ietf-foo.yang and ietf-template.yang) using the `pyang` tool with the "--ietf" flag set.





Let's introduce in this document the YANG module design guidelines with the revised datastore solution in mind:
For new YANG modules, but also a transition path for existing YANG modules.

> As required by RFC 4858, this is the current template for the Document
> Shepherd Write-Up.
>
> Changes are expected over time. This version is dated 24 February 2012.
>
> (1) What type of RFC is being requested (BCP, Proposed Standard,
> Internet Standard, Informational, Experimental, or Historic)?

Informational


> Why is this the proper type of RFC? 

RFC 6087 is also Informational


> Is this type of RFC indicated in the title page header?

Yes


> (2) The IESG approval announcement includes a Document Announcement
> Write-Up. Please provide such a Document Announcement Write-Up. Recent
> examples can be found in the "Action" announcements for approved
> documents. The approval announcement contains the following sections:
>
> Technical Summary
>
>  Relevant content can frequently be found in the abstract
>  and/or introduction of the document. If not, this may be
>  an indication that there are deficiencies in the abstract
>  or introduction.

  This memo provides guidelines for authors and reviewers of Standards
  Track specifications containing YANG data model modules.  Applicable
  portions may be used as a basis for reviews of other YANG data model
  documents.  Recommendations and procedures are defined, which are
  intended to increase interoperability and usability of Network
  Configuration Protocol (NETCONF) and RESTCONF protocol
  implementations that utilize YANG data model modules.


> Working Group Summary
>
>  Was there anything in WG process that is worth noting? For
>  example, was there controversy about particular points or
>  were there decisions where the consensus was particularly
>  rough?

This document has been discussed for a long time within the
WG.  At this point it has received extensive reviews and has
solid consensus behind it.


> Document Quality
>
>  Are there existing implementations of the protocol? Have a
>  significant number of vendors indicated their plan to
>  implement the specification? Are there any reviewers that
>  merit special mention as having done a thorough review,
>  e.g., one that resulted in important changes or a
>  conclusion that the document had no substantive issues? If
>  there was a MIB Doctor, Media Type or other expert review,
>  what was its course (briefly)? In the case of a Media Type
>  review, on what date was the request posted?

This document defined best practices for YANG.  As such, it will
be used to guide the designs of YANG models.  It will also be used
as the basis for YANG Doctor reviews of YANG modules.


> Personnel
>
>  Who is the Document Shepherd?

Kent Watsen


> Who is the Responsible Area Director?

Benoit Claise


> (3) Briefly describe the review of this document that was performed by
> the Document Shepherd.  If this version of the document is not ready
> for publication, please explain why the document is being forwarded to
> the IESG.

The Document Shepherd has reviewed the document as part of the WG last
call.  The Shepherd posted a review (see link below) to the list which
resulted in the current -09 version.

https://www.ietf.org/mail-archive/web/netmod/current/msg16881.html


> (4) Does the document Shepherd have any concerns about the depth or
> breadth of the reviews that have been performed? 

No.


> (5) Do portions of the document need review from a particular or from
> broader perspective, e.g., security, operational complexity, AAA, DNS,
> DHCP, XML, or internationalization?

No.


> If so, describe the review that took place.

N/A.


> (6) Describe any specific concerns or issues that the Document Shepherd
> has with this document that the Responsible Area Director and/or the
> IESG should be aware of? For example, perhaps he or she is uncomfortable
> with certain parts of the document, or has concerns whether there really
> is a need for it. In any event, if the WG has discussed those issues and
> has indicated that it still wishes to advance the document, detail those
> concerns here.

This publication request was delayed a bit due to the Shepherd
considering the impact on Section 5.23 of the OpState discussion
and the potential impact of the results expected from the Revised
Datastore Design Team.  Specifically, consideration included
if there should be a recommendation that might facilitate future
deprecations, as YANG modules move to a potentially new datastore
solution (e.g., see link below).  In the end, it was decided that
the safest action is to not introduce any new modeling conventions
at this time.  This decision is aligned with the convention found
in both RFC7223 and draft-ietf-netmod-routing-cfg, which is going
through IESG review at the time of this writing.  At this point,
the Shepherd has no remaining concerns with this document.

https://tools.ietf.org/html/draft-nmdsdt-netmod-revised-datastores-00


> (7) Has each author confirmed that any and all appropriate IPR
> disclosures required for full conformance with the provisions of BCP 78
> and BCP 79 have already been filed. If not, explain why.

Yes, see thread at
https://www.ietf.org/mail-archive/web/netmod/current/msg16807.html


> (8) Has an IPR disclosure been filed that references this document?
> If so, summarize any WG discussion and conclusion regarding the IPR
> disclosures.

No IPR disclosed.


> (9) How solid is the WG consensus behind this document? Does it
> represent the strong concurrence of a few individuals, with others
> being silent, or does the WG as a whole understand and agree with it? 

Good consensus after significant review.


> (10) Has anyone threatened an appeal or otherwise indicated extreme
> discontent? If so, please summarize the areas of conflict in separate
> email messages to the Responsible Area Director. (It should be in a
> separate email because this questionnaire is publicly available.)

None


> (11) Identify any ID nits the Document Shepherd has found in this
> document. (See http://www.ietf.org/tools/idnits/ and the Internet-Drafts
> Checklist). Boilerplate checks are not enough; this check needs to be
> thorough.

ID nits noticed a number of issues, but most are intentional and fine, but
the following has been raise on list for correction:

  -- The draft header indicates that this document obsoletes RFC6087,
    but the abstract doesn't seem to mention this, which it should.

  == Missing Reference: 'RFCXXXX' is mentioned on line 378, but not defined

  == Outdated reference: A later version (-18) exists of
    draft-ietf-netconf-restconf-17



> (12) Describe how the document meets any required formal review
> criteria, such as the MIB Doctor, media type, and URI type reviews.

N/A.


> (13) Have all references within this document been identified as
> either normative or informative?

Yes.


> (14) Are there normative references to documents that are not ready for
> advancement or are otherwise in an unclear state? If such normative
> references exist, what is the plan for their completion?

No.


> (15) Are there downward normative references references (see RFC 3967)?
> If so, list these downward references to support the Area Director in
> the Last Call procedure.

This is an Informational RFC.  All normative references are
Informational or higher.



> (16) Will publication of this document change the status of any
> existing RFCs? Are those RFCs listed on the title page header, listed
> in the abstract, and discussed in the introduction? If the RFCs are not
> listed in the Abstract and Introduction, explain why, and point to the
> part of the document where the relationship of this document to the
> other RFCs is discussed. If this information is not in the document,
> explain why the WG considers it unnecessary.

Yes, this document obsoletes RFC 6087.  Per (11) above, and my email
to the author, both the abstract and introduction will be updated to
say this.


> (17) Describe the Document Shepherd's review of the IANA considerations
> section, especially with regard to its consistency with the body of the
> document. Confirm that all protocol extensions that the document makes
> are associated with the appropriate reservations in IANA registries.
> Confirm that any referenced IANA registries have been clearly
> identified. Confirm that newly created IANA registries include a
> detailed specification of the initial contents for the registry, that
> allocations procedures for future registrations are defined, and a
> reasonable name for the new registry has been suggested (see RFC 5226).

The IANA Considerations section was reviewed by the document shepherd
and was considered appropriate, except for the RFC Ed. note being
confusing.  This concern has been been raised on list.



> (18) List any new IANA registries that require Expert Review for future
> allocations. Provide any public guidance that the IESG would find
> useful in selecting the IANA Experts for these new registries.

None.


> (19) Describe reviews and automated checks performed by the Document
> Shepherd to validate sections of the document written in a formal
> language, such as XML code, BNF rules, MIB definitions, etc.

The shepherd validated the document without model issues via
http://www.yangvalidator.com.