Subject: Re: Call for review of proposed update to ID-Checklist

From: John C Klensin <[email-masked]>
Date: Wed, 09 Jul 2008 20:59:21 -0400

--On Wednesday, 09 July, 2008 14:25 -0700 Ted Hardie
<[email-masked]> wrote:

> At 2:03 PM -0700 7/9/08, John C Klensin wrote:
> 
>> I propose
>> the following as alternative text:
> 
> A nit with this:
> 
> 
>>        "6.  Addresses used in I-Ds SHOULD use fully qualified
>>        domain names (FQDNs) instead of literal IP addresses.
>>        Working Groups or authors seeing exemptions from that
>>        rule MUST supply the rationale for IP address use with
>>        inline comments (e.g., "Editor's note:" or "Note in
>>        Draft:" that can be evaluated by the IESG and the
>>        community along with the rest of the document.  Domain
>>        names  in pseudo-code, actual code segments, sample
>>        data structures and templates, specifically including
>>        MIB definitions and examples that could reasonably be
>>        expected to be partially or entirely copied into code,
>>        MUST be drawn from the list reserved for documentary
>>        use in BCP32 (RFC 2606 or its successors).
> 
> I believe that this must say "Example domains in pseudo-code,
> actual code segments, sample data structures and templates,
> specifically including MIB definitions and examples that could
> reasonably be expected to be partially or entirely copied into
> code, MUST be drawn from the list reserved for documentary use
> in BCP32 (RFC 2606 or its successors). "  Without that, it
> might be read to force things like the domains in XML
> namespaces to fit this rule.  Those are, after all, things
> that might be partially or entirely copied into code.

Amendment gratefully accepted.

I meant to say explicitly that I hadn't spent nearly enough time
on that text to have any confidence that it was either exactly
correct or not in need or wordsmithing and then sent it too
soon. I am certain it could be improved by wordsmithing and am
not surprised that there were cases I failed to consider.  

The main point I was trying to make is that it really is
possible to parse this issue in a way that separates the read
problems/ risk/ harm from matters of taste and that replaces a
vague "SHOULD" (and "now you get to guess what will be
accepted") into a requirement for explanations and opportunity
for community review. 

A bit more below.

>> It is generally
>>        desirable for domain names used in other I-D discussion
>...
>> Now, that is somewhat longer and more complicated, but it
>> would seem to satisfy the criteria that have been discussed
>> on the IETF list, not just since the ID-Checklist update
>> draft was posted, but over the last six weeks or so.  In
>> particular:
>> 
>>        (i) I believe that there actually is consensus that use
>>        of non-2606 names in places where they are likely to be
>>        copied into production code (even if only by the lazy
>>        or careless) is likely to be harmful as well as a
>>        terrible idea.
> 
> See above.  There are places where it will be required. 

Yes.  I think your correction fixes the problem.

>... 
>>        (iii) The IETF has indicated enough times that domain
>>        names, not literal addresses, should be used in both
>>        protocols and documents that doing anything else should
>>        reasonably require clear and strong justification.
> 
> I'm not sure that this is a reasonable statement of the
> consensus, even of the weak consensus.  I think we normally
> like to have examples cover common cases; if literals are
> common in the actual protocol use, forcing the examples to use
> FQDNs is unhelpful.  We could use FQDNs in SDP examples, to
> take one common case, but the reality is that these usually
> use IP addresses.  The relevant ABNF is:
> 
>  unicast-address =     IP4-address / IP6-address / FQDN /
> extn-addr
> 
> from RFC 4566, so FQDNs could clearly be used in SDP examples.
> But doing so is no favor to the actual implementors that might
> read the docs.

You are right of course.  Better text is welcome if we can agree
on the principle.  It may also be that, if we are going to
permit addresses, some words in the Checklist about preferences
for IPv4, IPv6, or parallel examples would be in order.

>...
>> I think that is supposed to be what we all want around here,
>> isn't it?
> 
> I certainly share your goals: avoiding elaborate procedures
> and private negotiations between the IESG and the authors.  I
> remain concerned, though, that this formulation still looks
> like "justify yourself to the IESG" rather than "satisfy the
> relevant community you know what you're doing, and the IESG
> will approve unless the larger community objects".  But that
> is a much larger issue.

I had hoped it would be at least "justify yourself to the
community and then let the IESG make judgments about community
consensus" rather than any of the variations on "let the IESG
reach a decision independent of the community".  The question of
what the IESG should do (or might be expected or required to do)
in the absence of any community consensus is, as you say, a much
larger issue.

regards,
    john

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

---

From: "Frank Ellermann" <[email-masked]>
Date: Thu, 10 Jul 2008 15:36:45 +0200

John C Klensin wrote:
 
> Better text is welcome if we can agree on the principle.  It
> may also be that, if we are going to permit addresses, some
> words in the Checklist about preferences for IPv4, IPv6, or
> parallel examples would be in order.

The principle should be "stay away from IP literals when you
can in practice".  The hypothetical specification could quote
the scream in RFC 822:

| Note:  THE USE OF DOMAIN-LITERALS IS STRONGLY DISCOURAGED.

After that's clear some examples with domain literals are no
problem, they are actually desperately needed, because the
syntax differs depending on the context:

Sometimes square brackets are required, sometimes they are
not allowed, sometimes this depends on IPv4 vs. IPv6.  When
square brackets are required they are typically used as is,
but in URIs + IRIs outside of <host> and <ihost> they have
to be percent-encoded.

A mailto: specification without example for domain literals
would be irresponsible, no matter what an ID-checklist says.

IMO the SHOULD about using FQDNs instead of IPs in examples
is nonsense.  The ID-Checklist is the wrong place to tell
authors that FQDNs are better than IPs; they are supposed
to know this.  

>>> I think that is supposed to be what we all want around 
>>> here, isn't it?

Yes, your new MUSTard is fine.  The old SHOULD about FQDNs
vs. domain literals in examples is utter dubious.

 Frank