Subject: Re: [Netconf] Gen-ART LC review of draft-ietf-netconf-4741bis-07.txt

From: "Bert (IETF) Wijnen" <[email-masked]>
Date: Mon, 07 Feb 2011 12:44:43 +0100

Brian, thanks for your review and comments

All comments together are being considered by the editors and possibly will
result in a new revision.

We'll keep you updated.

Bert Wijnen
Document Shepherd

On 1/31/11 1:59 AM, Brian E Carpenter wrote:
> Please see attached review.

draft-ietf-netconf-4741bis-07-carpenter.txt

I am the assigned Gen-ART reviewer for this draft. For background on
Gen-ART, please see the FAQ at
<http://wiki.tools.ietf.org/area/gen/trac/wiki/GenArtfaq>.

Please resolve these comments along with any other Last Call comments
you may receive.

Document: draft-ietf-netconf-4741bis-07.txt
Reviewer: Brian Carpenter
Review Date: 2011-01-31
IETF LC End Date: 2011-02-07
IESG Telechat date:

Summary: Almost ready - review use of normative words
--------

Comment:
--------

This is a 121 page document with a very large amount of code included,
including code explicitly marked as being normative content. I have
not checked this code in any way.

Minor issues
------------

I'm a little confused by some of the non-normative uses of lower case "should".
For example:

"1.3.  Capabilities

    A NETCONF capability is a set of functionality that supplements the
    base NETCONF specification.  The capability is identified by a
    uniform resource identifier (URI).  These URIs should follow the
    guidelines as described in Section 8.
...
"8.  Capabilities

    This section defines a set of capabilities that a client or a server
    MAY implement."

So if the capabalities are a formal MAY, what is that apparently non-normative
"should" supposed to mean? I suggest that the sentence would be less confusing
if it said:

"Section 8 provides guidelines for these URIs."

Another example:

"Appendix D.  Capability Template

    This non-normative section defines a template that should be used to
    define protocol capabilities. "

If it's non-normative, how is the reader to interpret "should"? Doesn't
it mean "could" or "might"?

There are tens of instances of lower case "should" and I wonder how many
of them are confusing in this way.

Similarly:

"2.3.  Authentication

    NETCONF connections must be authenticated.  "

Surely that should be normative MUST? And there are lots of other lower
case "must" and "may". The latter is especially confusing because in
examples like this:
"6.4.4.  Select All<name>  Elements within the<users>  Subtree

    This filter contains two containment nodes (<users>,<user>) and one
    selection node (<name>).  All instances of the<name>  element in the
    same sibling set are selected in the filter output.  The client may
    need to know that<name>  is used as an instance identifier..."

s/may/might/ would be appropriate, but in

"The filter element may optionally contain a "type" attribute."

s/may optionally/MAY/ would be appropriate.

The current mix of RFC 2119 terms, apparently normative lower case terms, and
apparently non-normative use of "may" and "should" seems like it needs cleaning up compared to RFC4741.