Subject: [Gen-art] Gen-ART LC Review of draft-ietf-netmod-yang-usage-07

From: Enrico Marocco <[email-masked]>
Date: Fri, 9 Jul 2010 17:32:13 +0200

Document: draft-ietf-netmod-yang-usage-07
Reviewer: Enrico Marocco
Review Date: July 9, 2010
IETF LC End Date: July 8, 2010

Note: This review comes one day after the LC End Date, my bad. I'm
sending it anyways, hoping it may be useful in the reminder of the
publishing process. Feel free to ignore my late comments.

Summary: This draft is on the right track but has open issues, described
in the review.

Major Issues:

None.

Minor Issues:

Some guidelines in the document point to documents on the web that
cannot be assumed to stay stable for as long as the RFC. My advice is to
replace them with more stable references, or with new text in the
document itself. In particular:

S. 3. "General Documentation Guidelines:" replace the URL pointing to
rfc-editor.org with references to RFC 2223. The first paragraph could be
rewritten as:

OLD:
    YANG data model modules under review are likely to be contained in
    Internet-Drafts.  All guidelines for Internet-Draft authors MUST be
    followed.  These guidelines are available online at:

    http://www.rfc-editor.org/rfc-editor/instructions2authors.txt

NEW:
    YANG data model modules under review are likely to be contained in
    Internet-Drafts, formatted according to RFC 2223 [ref to the RFC]
    and its successors.

S. 3.4. "Security Considerations Section," first paragraph: is there
really a need to define such a template in an external document (that
most likely won't be reachable in a few years at the given URL)? Why not
simply putting the whole template (< 2pg) in this document? [Note that
the same document is also referenced in the draft's "Security
Considerations" section.]

Nits:

Abstract: expand NETCONF (as per
http://www.rfc-editor.org/rfc-style-guide/abbrev.expansion.txt) and
provide a few words about YANG for the casual reader.

S. 3.3. "Definitions Section," first para: define "YIN."

S. 3.4. "Security Considerations Section," third bullet point: s/'rpc'
statements/YANG 'rpc' statements/

S. 3.5.1. "Documents that Create a New Name Space," second para: here
citing I-D.ietf-netmod-yang after "The YANG specification" may help the
reader.

S. 4.1 "Module Naming Conventions," third para: as I understand, an IANA
registry is going to guarantee name uniqueness. Why not mentioning it
here (other than in S. 4.7)?

S. 4.4. "Conditional Statements," third para: s/indicate the/indicate
that the/

S. 4.5. "XPath Usage," fourth para: quote the node properties provided
as an example. Before that point names/variables are quoted.

S. 4.5. "XPath Usage," seventh para: quotes in the example again.

S. 4.7. "Module Header, Meta, and Revision Statements," second para:
s/documented/document/

S. 4.10. "Data Types:" quote "identityref," "int32," "enum" and "bit."

Questo messaggio e i suoi allegati sono indirizzati esclusivamente alle persone indicate. La diffusione, copia o qualsiasi altra azione derivante dalla conoscenza di queste informazioni sono rigorosamente vietate. Qualora abbiate ricevuto questo documento per errore siete cortesemente pregati di darne immediata comunicazione al mittente e di provvedere alla sua distruzione, Grazie.

This e-mail and any attachments is confidential and may contain privileged information intended for the addressee(s) only. Dissemination, copying, printing or use by anybody else is unauthorised. If you are not the intended recipient, please delete this message and any attachments and advise the sender by return e-mail, Thanks.

---

From: Andy Bierman <[email-masked]>
Date: Mon, 12 Jul 2010 09:16:11 -0700

> Summary: This draft is on the right track but has open issues, described

Sorry for the delay.  I was trying to get WG Chair feedback on one of your
comments, and this took awhile.  I will submit an I-D update today
addressing all the issues except 1 -- the URL to the YANG security
guidelines.  This WEB page is owned by the IETF, and is similar to the
on-line MIB security guidelines.   This text may change over time,
which has been the case with the MIB guidelines.   It is maintained
by a different author as well.

Andy

> Questo messaggio e i suoi allegati sono indirizzati esclusivamente
> alle persone indicate. La diffusione, copia o qualsiasi altra azione
> derivante dalla conoscenza di queste informazioni sono rigorosamente
> vietate. Qualora abbiate ricevuto questo documento per errore siete
> cortesemente pregati di darne immediata comunicazione al mittente e di
> provvedere alla sua distruzione, Grazie.
>
> This e-mail and any attachments is confidential and may contain
> privileged information intended for the addressee(s) only.
> Dissemination, copying, printing or use by anybody else is
> unauthorised. If you are not the intended recipient, please delete
> this message and any attachments and advise the sender by return
> e-mail, Thanks.
>

---

From: Enrico Marocco <[email-masked]>
Date: Wed, 14 Jul 2010 14:30:37 +0200

> by a different author as well.

What puzzles me is the fact that the text in section 3.4 ("This section
MUST be patterned after [..]") basically makes that URL a normative
reference. However, I understand that such kind of references are an
established practice in OPS, so I'll let more expert reviewers discuss
whether it is appropriate in this case.

-- 
Ciao,
Enrico