[Gen-art] Gen-ART review of draft-ietf-dime-app-design-guide-19

[Martin Thomson <[e-mail]>]

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-dime-app-design-guide-19
Reviewer: Martin Thomson
Review Date: 2013-09-13
IETF LC End Date: unknown, early review
IESG Telechat date: (if known)

Summary: This document is ready, with some minor issues and nits.

Minor issues:
I would find it a lot easier to read this document if it did as the
goals state (the first objective from the introduction) and clarify
what the extensibility rules in Diameter say with respect to each of
the described extensions.  It's not easy to glean this information
from RFC 6733, which makes reviewing this a little tricky.

For instance, Section 4.1 doesn't really say what the expectations are
with respect to implementations that receive unknown or unsupported
commands.  I think that I could guess, but I'd rather not.  (I just
read the relevant parts of 6733, and it turns out that my guess was
wrong.)

The same applies to Section 4.2, presumably through applying the same
principles.  The question here is: what would be the expected behavior
if a node was operating on the new application definition and that
node received a deleted command?  (The old implementation presumably
has no problem with the absence of the command if it's being removed.)

The same applies to Section 5.

Sections 4.4.2 and particularly 5.6 lead me to infer that the
extensibility for enumerated types is fundamentally broken, so maybe
those properties need to be expanded upon a little here too.

The placement of the guidance in Section 5.6 seems fairly important
for Section 4, lest that important information be lost to someone just
looking to tweak a command.

Section 4.3.1, perhaps add to the M-bit criteria: Would the presence
or value of the AVP alter the interpretation of the command (or any
other AVP) in any way?  (nit: s/AVPs/AVP on second bullet here.)

I didn't find the list in  Section 6 particularly compelling.  It
seemed a little like motherhood statements.  The description of what
it was this was talking about: good; the description of how these
"often" (always?) manifest is also useful.  I wonder though whether
it's safe to generalize when you only see generic protocols extensions
as optional AVPs.  Perhaps you need to refocus on exactly that, and
leave the other forms of extension to speculation.

Nits/editorial comments:
The last paragraph of Section 3 is confusing to me.  Firstly, the
subject of the reminder is missing from the first sentence.  I think
that the intent of that sentence is to say that extending by adding
applications or commands is to be avoided, but then subsequent
sentences make it clear that doing so is easy.  The last sentence
seems to be talking about something else entirely, which is the value
that IANA registries provide.  I am going to have to suggest that this
be reworded entirely.

In Section 4.1, I'd like to see the note turned into real text.  The
size and complexity of an application seems to be a fairly significant
factor in determining whether a new application imports commands, or
whether separate applications are defined.

I read the first bullet in Section 4.3.2 as a sentence, several times,
before realizing that it's a title.  Please reconsider the formatting
of this list.  At a very minimum, remove the period.

--Martin

p.s., I'm on vacation starting approximately ...now, since I'm out of
time for this review... so apologies for any slow responses to the
review.