Guidelines for Authors and Reviewers of YANG Data Model Documents
draft-ietf-netmod-yang-usage-11

[Ballot discuss]
The Gen-ART Review by Enrico Marocco on 9-Jul-2010 leads me to ask a
  question about Section 3.4.

  Section 3.4 says:
  >
  > Each specification that defines one or more modules MUST contain a
  > section that discusses security considerations relevant to those
  > modules.  This section MUST be patterned after the latest approved
  > template (available at
  > http://www.ops.ietf.org/netconf/yang-security-considerations.txt).
  >
  This seems like an odd place for a normative reference to point.
  I'd be much happier with a place that required some form of review
  and consensus call to be updated.

[Ballot discuss]
>    The 'position' and 'last' functions MAY be used with caution.

  DISCUSS: I don't know what "MAY be used with caution" means. Does it mean
  "SHOULD NOT, but if you do consider "? Or does it mean "MUST be
  used in "? (The "with caution" phrasing appears elsewhere,
  and I have the same question about all occurrences.)

[Ballot comment]
Section 3., paragraph 3:
>    The following sections MUST be present in an Internet-Draft
>    containing a module:
>    o  Narrative sections
>    o  Definitions section
>    o  Security Considerations section
>    o  IANA Considerations section
>    o  References section

  I think it makes sense here to separate this into sections that this
  memo requires for YANG modules (the first two), and into sections that
  the general ID template requires (the final three), because the latter
  can change and obviously YANG IDs need new sections if they become
  required to submit an ID. For the latter, you should rephrase the
  sections that describe their content in a way that makes it clear that
  they are currently required, but that new ones may be added and just
  maybe some of the listed ones will dissappear.


Section 3.1., paragraph 3:
>    Each YANG module or submodule contained within an Internet-Draft or
>    RFC is considered to be a code component.  The strings '    BEGINS>' and '' MUST be used to identify each code
>    component.

  I note that YANG is listed in
  http://trustee.ietf.org/license-info/archive/Code-Components-List-4-23-09.txt,
  so you actually do not need to require the use of and
  .


Section 4., paragraph 1:
>    In general, modules in IETF standards-track specifications MUST
>    comply with all syntactic and semantic requirements of YANG.
>    [I-D.ietf-netmod-yang].  The guidelines in this section are intended
>    to supplement the YANG specification, which is intended to define a
>    minimum set of conformance requirements.

  You may want to recommend that authors verify the syntax of their YANG
  module with an automated checker every time before submitting a new
  revision. (I see that Section 4.8 talks about that - maybe add a
  forward reference?)


Section 4.5., paragraph 2:
>    The 'attribute' and 'namespace' axes are not supported in YANG, and
>    MAY be empty in a NETCONF server implementation.

  s/MAY/may/ (I don't think the idea is to make requirements on NETCONF
  servers here)


Section 6.1., paragraph 1:
>    transport is SSH [RFC4742].

  Reference missing: RFC4742

[Ballot discuss]
Section 4., paragraph 0:
> 3.7.  Intellectual Property Section

  DISCUSS: The current ID format does not have an Intellectual Property
  Section anymore.

>    The 'position' and 'last' functions MAY be used with caution.

  DISCUSS: I don't know what "MAY be used with caution" means. Does it mean
  "SHOULD NOT, but if you do consider "? Or does it mean "MUST be
  used in "? (The "with caution" phrasing appears elsewhere,
  and I have the same question about all occurrences.)

[Ballot comment]
Thanks for this document. I think it will be useful.

---

Support Enrico's point in Russ's Discuss.
It is not appropriate to keep the boilerplate outside the IETF domain.

http://trac.tools.ietf.org/wg/netconf/trac/wiki may be an appropriate
location.

---

I wonder if there is scope for some common framework text like that
held at http://www.ops.ietf.org/mib-boilerplate.html

---

I am a bit worried that this document covers advice that is more general than just the Yang-related work in an I-D. This risks setting up contradictory advice in a number of places. (For example, discussing how the References should be split is generic advice for authors of I-Ds that could be changed at any time.)

[Ballot discuss]
#1 - IANA Section

Section 3.5 says:

  In order to comply with IESG policy as set forth in
  http://www.ietf.org/ID-Checklist.html, every Internet-Draft that is
  submitted to the IESG for publication which has action items for IANA
  MUST contain an IANA Considerations section.

But the checklist indicates that ALL I-Ds MUST contain an IANA Considerations section and if there's no IANA actions to follow bullet D:

  If there is no action for IANA, the section should say that, e.g., including
  something like "This document has no actions for IANA."

Section 3.5 should be modified to indicate align with the checklist.

[Ballot discuss]
The Gen-ART Review by Enrico Marocco on 9-Jul-2010 leads me to ask a
  question about Section 3.4.

  Section 3.4 says:
  >
  > Each specification that defines one or more modules MUST contain a
  > section that discusses security considerations relevant to those
  > modules.  This section MUST be patterned after the latest approved
  > template (available at
  > http://www.ops.ietf.org/netconf/yang-security-considerations.txt).
  >
  This seems like an odd place for a normative reference to point.
  I'd be much happier with a place that required some form of review
  and consensus call to be updated.

[Ballot comment]
Section 3., paragraph 3:
>    The following sections MUST be present in an Internet-Draft
>    containing a module:
>    o  Narrative sections
>    o  Definitions section
>    o  Security Considerations section
>    o  IANA Considerations section
>    o  References section

  I think it makes sense here to separate this into sections that this
  memo requires for YANG modules (the first two), and into sections that
  the general ID template requires (the final three), because the latter
  can change and obviously YANG IDs need new sections if they become
  required to submit an ID. For the latter, you should rephrase the
  sections that describe their content in a way that makes it clear that
  they are currently required, but that new ones may be added and just
  maybe some of the listed ones will dissappear.


Section 3.1., paragraph 3:
>    Each YANG module or submodule contained within an Internet-Draft or
>    RFC is considered to be a code component.  The strings '    BEGINS>' and '' MUST be used to identify each code
>    component.

  I note that YANG is listed in
  http://trustee.ietf.org/license-info/archive/Code-Components-List-4-23-09.txt,
  so you actually do not need to require the use of and
  .


Section 4., paragraph 1:
>    In general, modules in IETF standards-track specifications MUST
>    comply with all syntactic and semantic requirements of YANG.
>    [I-D.ietf-netmod-yang].  The guidelines in this section are intended
>    to supplement the YANG specification, which is intended to define a
>    minimum set of conformance requirements.

  You may want to recommend that authors verify the syntax of their YANG
  module with an automated checker every time before submitting a new
  revision. (I see that Section 4.8 talks about that - maybe add a
  forward reference?)


Section 4.5., paragraph 2:
>    The 'attribute' and 'namespace' axes are not supported in YANG, and
>    MAY be empty in a NETCONF server implementation.

  s/MAY/may/ (I don't think the idea is to make requirements on NETCONF
  servers here)

>    The 'position' and 'last' functions MAY be used with caution.

  I don't know what "MAY be used with caution" means. Does it mean
  "SHOULD NOT, but if you do consider "? Or does it mean "MUST be
  used in "? (The "with caution" phrasing appears elsewhere,
  and I have the same question about all occurrences.)


Section 6.1., paragraph 1:
>    transport is SSH [RFC4742].

  Reference missing: RFC4742

[Ballot discuss]
Section 4., paragraph 0:
> 3.7.  Intellectual Property Section

  DISCUSS: The current ID format does not have an Intellectual Property
  Section anymore.

[Ballot comment]
I am generally glad that this document is written. Some comments/questions below:

3.6.  Reference Sections

  For every normative reference statement which appears in a module
  contained in the specification, which identifies a separate document,
  a corresponding normative reference to that document SHOULD appear in
  the Normative References section.

Why only a SHOULD (and not a MUST)?

4.1.  Module Naming Conventions

  Modules contained in standards track documents SHOULD be named
  according to the guidelines in the IANA considerations section of
  [I-D.ietf-netmod-yang].

Why only a SHOULD?

  A distinctive word or acronym (e.g., protocol name or working group
  acronym) SHOULD be used in the module name.  If new definitions are
  being defined to extend one or more existing modules, then the same
  word or acronym should be reused, instead of creating a new one.

s/should/SHOULD ?

4.7.  Module Header, Meta, and Revision Statements

  It is acceptable to reuse the same revision statement within
  unpublished versions (i.e., Internet-Drafts), but the revision date
  MUST be updated to a higher value each time the Internet-Draft is re-
  published.

I tend to think that this MUST will be ignored in practice. I think making authors update a revision date with every uncompatible change would be more sensible.

IANA comments:

Upon approval of this document, IANA will make the following assignment
in the "ns" registry located at
http://www.iana.org/assignments/xml-registry/ns.html

ID URI Registration template Reference
-- --- -------------------- ---------
yang:ietf-template urn:ietf:params:xml:ns:yang:ietf-template
yang:ietf-template
[RFC-netmod-yang-usage-07]

We understand the above to be the only IANA Action for this document.

(1.a)  Who is the Document Shepherd for this document?

        David Partain, NETMOD WG co-chair

        Has the Document Shepherd personally reviewed this version
        of the document and, in particular, does he or she believe
        this version is ready for forwarding to the IESG for
        publication?

        Yes, I have reviewed this document and consider it much
        ready for IESG review and publication as Informational.

(1.b)  Has the document had adequate review both from key WG members
        and from key non-WG members?

        Yes, the document has gone through the normal review
        processes within the Working Group.

        Does the Document Shepherd have any concerns about the
        depth or breadth of the reviews that have been performed?

        No, I do not.

(1.c)  Does the Document Shepherd have concerns that the document
        needs more review from a particular or broader perspective,
        e.g., security, operational complexity, someone familiar with
        AAA, internationalization, or XML?

        The document would be well-served by further review from
        members of the O&M community who are not deeply involved
        in the NETCONF area, particularly as the document
        provides guidelines for how YANG will be used for
        modeling management information.

(1.d)  Does the Document Shepherd have any specific concerns or
        issues with this document that the Responsible Area Director
        and/or the IESG should be aware of?

        No, this document has been stable and straightforward to
        reach consensus on.

        Has an IPR disclosure related to this document been filed?

        No IPR disclosures have been filed against this document.

(1.e)  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?

        I believe this document represents strong consensus of the
        working group.

(1.f)  Has anyone threatened an appeal or otherwise indicated extreme
        discontent?

        No.

(1.g)  Has the Document Shepherd personally verified that the
        document satisfies all ID nits?  (See
        http://www.ietf.org/ID-Checklist.html and
        http://tools.ietf.org/tools/idnits/.)  Boilerplate checks are
        not enough; this check needs to be thorough.

        The following nit is NOT an issue:
            -----------------------------------------
            Looks like a reference, but probably isn't: '42' on
            line 411 'caution. (e.g., //chapter[42]).  Note that
            a NETCONF server is on...'
            -----------------------------------------

        The following nit will need to be fixed:

            -----------------------------------------
            Using lowercase 'not' together with uppercase 'MUST',
            'SHALL', 'SHOULD', or 'RECOMMENDED' is not an
            accepted usage according to RFC 2119.  Please use
            uppercase 'NOT' together with RFC 2119 keywords (if
            that is what you mean).

            Found 'MUST not' in this paragraph:

            Once a module name is published, it MUST not be
            reused, even if the RFC containing the module is
            reclassified to 'Historic' status.
            -----------------------------------------
            Outdated reference: A later version (-13) exists of
            draft-ietf-netmod-yang-12
            -----------------------------------------

        Has the document met all formal review criteria it needs
        to, such as the MIB Doctor, media type, and URI type
        reviews?

        Yes.

(1.h)  Has the document split its references into normative and
        informative?
       
        Yes.

        Are there normative references to documents that are not
        ready for advancement or are otherwise in an unclear
        state?

        The companion NETMOD documents (draft-ietf-netmod-yang
        and draft-ietf-netmod-yang-types) are included but will
        be going to advancement in parallel.  Both have already
        been approved by the IESG.

        If such normative references exist, what is the strategy
        for their completion?

        They are being advanced in parallel.
       
        Are there normative references that are downward
        references, as described in [RFC3967]?

        No.

(1.i)  Has the Document Shepherd verified that the document's IANA
        Considerations section exists and is consistent with the body
        of the document?
       
        Yes.

        If the document specifies protocol
        extensions, are reservations requested in appropriate IANA
        registries?  Are the IANA registries clearly identified?
       
        No protocol extensions are specified.
       
        If the document creates a new registry, does it define
        the proposed initial contents of the registry and an
        allocation procedure for future registrations?

        No new registry is created.
       
        Does it suggest a reasonable name for the new registry?

        Not applicable.

(1.j)  Has the Document Shepherd verified that sections of the
        document that are written in a formal language, such as XML
        code, BNF rules, MIB definitions, etc., validate correctly in
        an automated checker?

        Yes, there is an example YANG module.

(1.k)  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

          YANG is a data modeling language used to model
          configuration and state data manipulated by the Network
          Configuration Protocol (NETCONF) protocol, NETCONF
          remote procedure calls, and NETCONF notifications.

          This document 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 NETCONF implementations which utilize YANG
          data model modules.

        Working Group Summary

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

        Document Quality

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