Subject: [pcp] -06 review: organization

From: Paul Selkirk <[email-masked]>
Date: Mon, 07 Mar 2011 21:55:31 +0000

I recently undertook a close reading of -06, as if I was approaching it
for the first time as an implementor.

What follows will be a number of "topic" posts, followed by a catch-all
nit post.  I'm still working through some of the smaller topics, but I
wanted to start sending these out in some kind of time for tomorrow's
interim meeting (is that still happening?).

First up, general organization of the document.  A lot of information
that should be together is spread throughout the document, sometimes
repetitiously.  Also, there's a lack of consistency in some of the
terminology.

I would like to see all the Options together in one chapter, rather than
scattered across sections 6.7.1, 8.8, 9.6 (empty), and 10.  The Option
boilerplate includes a field for which OpCodes the Option applies to, so
they don't need to be co-located with the OpCode definitions.  (More on
options in the next post.)

Likewise, I would like to see all Result Codes consolidated into one
section, rather than scattered across sections 5.4, 8.2, 9.2, and 10.

This might not make it easier to spot problems like the fact that
IMPLICIT_MAPPING_EXISTS is used without ever being defined or given a
result code value, but it would give us one definitive place to look for
result codes.

Result code ordering seems a bit arbitrary, but I'm willing to let is pass.

The "generating request/processing request/processing reply"
organization that was introduced in -05 doesn't really work for me.
For one thing, 6.1 and 8.3, ostensibly about generating requests,
are actually about discovery and retransmission, and renewal,
respectively.  I think I'd rather see a return to the -04 organization
of client operation/server operation, with other topics (such as
discovery) moved to other sections.  (More on this in a subsequent
post).

On terminology, we should decide whether it's "response code" (used 14
times) or "result code" (used 27 times).

This is somewhat complicated by the tendency to talk about a "positive
response" (used 8 times in various forms), versus a "positive result"
(used once).  Only once do we refer to the actual result code of
SUCCESS ("SUCCESS response", in section 9.4).

In a final bit of terminology, I note that -05 changed from a mixture
of "CGN" and "LSN" references to use "CGN" exclusively.  However, we
reference draft-ietf-behave-lsn-requirements, which uses "LSN"
exclusively.  For consistency, we should probably also use "LSN".

				paul

---

From: "Dan Wing" <[email-masked]>
Date: Mon, 7 Mar 2011 18:27:38 -0800

> -----Original Message-----
> From: [email-masked] [mailto:[email-masked]] On Behalf Of
> Paul Selkirk
> Sent: Monday, March 07, 2011 1:56 PM
> To: [email-masked]
> Subject: [pcp] -06 review: organization
> 
> result code value, but it would give us one definitive place to look
> for result codes.

The reason for the current layout is to describe the base protocol
itself (PCP requsts, PCP responses) and then two options (MAP, PEER).
This clearly shows how new OpCodes can be defined above the base 
request/response protocol.

The current layout is as if there were three documents, combined
into one:

  * base protocol specification
  * MAP OpCodes
  * PEER OpCodes

of course, it isn't perfect.

> discovery) moved to other sections.  (More on this in a subsequent

I had several complaints about the previous organization.  Maybe
we can take votes or something tomorrow morning during the Interim
meeting.

> times) or "result code" (used 27 times).

Ok, it's now "result code" everywhere.

> SUCCESS ("SUCCESS response", in section 9.4).

s/positive response/SUCCESS response/

> exclusively.  For consistency, we should probably also use "LSN".

BEHAVE's consensus was to use "CGN", and draft-ietf-behave-lsn-requirements
will be modified to use CGN (although its filename will remain the same,
but the filename dies off when it becomes an RFC),
http://www.ietf.org/mail-archive/web/behave/current/msg09181.html

-d

> 
> 				paul
> _______________________________________________
> pcp mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/pcp

---

From: Paul Selkirk <[email-masked]>
Date: Tue, 08 Mar 2011 06:34:16 +0000

> we can take votes or something tomorrow morning during the Interim

My biggest beef with the the current organization is that it seems kind
of artificial, and it puts subjects that aren't really related under the
heading of "generating a request" (like server discovery).

It's largely a matter of taste; if I can find the information I need, I
can implement it (but I'd like to be able to find the information I need
in the table of contents).

> http://www.ietf.org/mail-archive/web/behave/current/msg09181.html

Thanks, I missed that (haven't been following BEHAVE very closely in a
while).

				paul

---

From: "Dan Wing" <[email-masked]>
Date: Mon, 7 Mar 2011 22:38:57 -0800

> From: Paul Selkirk [mailto:[email-masked]]
> Sent: Monday, March 07, 2011 10:34 PM
> To: Dan Wing
> Cc: [email-masked]
> Subject: Re: [pcp] -06 review: organization
> 
> of artificial,

Agreed.

> and it puts subjects that aren't really related under
> the heading of "generating a request" (like server discovery).

That particular paragraph, I agree, would be better moved somewhere
else.  

> can implement it (but I'd like to be able to find the information I
> need in the table of contents).

What is a better ToC?

> Thanks, I missed that (haven't been following BEHAVE very closely in a

In the scheme of things, the terminology is minor.

-d