Subject: new text for ID_Checklist sect 3, item 6

From: "Bert Wijnen \(IETF\)" <[email-masked]>
Date: Wed, 13 Aug 2008 12:21:41 +0200

The revision 1.8 of the ID-Checklist is at
  
    http://www.ietf.org/ID-Checklist.html

Sect 3, item 6 in that revision states:

     6. Addresses used in examples SHOULD use fully qualified
        domain names instead of literal IP addresses, and SHOULD
        use example fqdn's such as foo.example.com instead of
        real-world fqdn's. See [RFC2606] for example domain names
        that can be used. 

John Klensin has proposed new text, whcih was amended by
Ted Hardie and the resulting text (if I understood it correctly) is:

       "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.  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).  It is generally 
        desirable for domain names used in other I-D discussion 
        contexts to be drawn from BCP32 as well, if only as an 
        act of politeness toward those who might be using the 
        domains for other purposes at the time of publication or 
        subsequently.   Working groups or editors who are 
        convinced that different names are required MUST be 
        prepared to explain and justify their choices and SHOULD 
        do so with explicit inline comments such as those 
        described above." 

>From the discussion on the list (that I have seen), people seem to
be OK with that text. It is quite a bit longer, but so be it.

Does anyone have objections to the above text as replacement for
the current text?

Bert 
Editor for ID_Checklist

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

---

From: [email-masked] (Scott O. Bradner)
Date: Wed, 13 Aug 2008 08:51:44 -0400 (EDT)

good stuff

---
>From [email-masked]  Wed Aug 13 06:54:56 2008
From: "Bert Wijnen \(IETF\)" <[email-masked]>
To: "IETF Discussion" <[email-masked]>
Subject: new text for ID_Checklist sect 3, item 6
Date: Wed, 13 Aug 2008 12:21:41 +0200
Organization: Consultant
Sender: [email-masked]

Bert 
Editor for ID_Checklist

---

From: "Eric Gray" <[email-masked]>
Date: Wed, 13 Aug 2008 08:13:00 -0500

Isn't it a little too redundant to include the parenthetical 
"RFC 2606 or its successors" along with BCP 32?

--
Eric Gray
Principal Engineer
Ericsson  

> -----Original Message-----
> From: [email-masked] [mailto:[email-masked]] On 
> Behalf Of Bert Wijnen (IETF)
> Sent: Wednesday, August 13, 2008 6:22 AM
> To: IETF Discussion

---

From: Lars Eggert <[email-masked]>
Date: Wed, 13 Aug 2008 15:27:40 +0200

Looks good. My only comment is about where the justification is to be  
provided - the PROTO writeup is at least an alternative to putting  
this into the document itself, and IMO it's a better alternative.

Lars

On 2008-8-13, at 12:21, ext Bert Wijnen (IETF) wrote:

> 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.  Example
> 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).  It is  
> generally        desirable for domain names used in other I-D  
> discussion        contexts to be drawn from BCP32 as well, if only  
> as an        act of politeness toward those who might be using  
> the        domains for other purposes at the time of publication  
> or        subsequently.   Working groups or editors who are         
> convinced that different names are required MUST be        prepared  
> to explain and justify their choices and SHOULD        do so with  
> explicit inline comments such as those        described above."
> Bert Editor for ID_Checklist
>

---

From: "Eric Gray" <[email-masked]>
Date: Wed, 13 Aug 2008 08:49:31 -0500

Not having it actually in the RFC itself means that it effectively
disappears on publication.  This is both a feature and a flaw.

If the justification is included in the published RFC, the precedent
is very much clearer (and - thus - much less likely to be the cause
of confusion and discussion in the future).

--
Eric Gray
Principal Engineer
Ericsson  

> Behalf Of Lars Eggert
> Sent: Wednesday, August 13, 2008 9:28 AM
> To: ext Bert Wijnen (IETF)
> Cc: IETF Discussion
> Subject: Re: new text for ID_Checklist sect 3, item 6
> 
>  Working  
> prepared

---

From: John C Klensin <[email-masked]>
Date: Wed, 13 Aug 2008 12:38:44 -0400

--On Wednesday, August 13, 2008 3:27 PM +0200 Lars Eggert 
<[email-masked]> wrote:

> Looks good. My only comment is about where the justification
> is to be provided - the PROTO writeup is at least an
> alternative to putting this into the document itself, and IMO
> it's a better alternative.

Lars,

There is a tricky balance about going into too much detail here. 
In general, I prefer to see phrases like "in a way specified by 
the IESG" to language about where things go (much less debates 
about that language).   On the other hand, this sort of document 
is exactly the sort of place where the IESG specifies what it 
wants to see and where it wants to see it, so being more 
specific here doesn't disturb me too much.

The PROTO writeup is a fine place iff the IESG either includes 
that writeup in the Last Call or, better, includes an explicit 
note that the authors have asked for an exception to some 
particular guideline and pointing to the PROTO writeup for their 
explanation.

If the PROTO writeup is, in practice, only examined by the IESG, 
then it is the IESG, and the IESG alone, reviewing the argument 
for an exception and making the decision.  The IESG should be 
evaluating and reflecting community consensus if the community 
cares.   If the community doesn't, then I'm happy leaving thing 
up to the IESG.  But having something the community might want 
to consider hidden in an obscure place, with no notice to the 
community, should not, ever, be the basis for a conclusion that 
the community doesn't care.

--On Wednesday, August 13, 2008 8:49 AM -0500 Eric Gray 
<[email-masked]> wrote:

> Not having it actually in the RFC itself means that it
> effectively disappears on publication.  This is both a feature
> and a flaw.
>
> If the justification is included in the published RFC, the
> precedent is very much clearer (and - thus - much less likely
> to be the cause of confusion and discussion in the future).

Eric, while it is clearly a judgment call about what is 
important, your suggestion above could easily be extended to 
suggest that it was necessary to have all WG discussions about 
alternatives included in every WG-produced, Standards-track RFC 
that is published.  Sometimes that might not be a bad idea but, 
as a rule I think it leads to absurdity.

Ultimately, an argument that an exception should be made in a 
particular case is an argument that the choice is technically 
and substantively harmless and hence essentially an editorial 
matter.   If that is true, then we certainly don't preserve 
long-term documentation of editorial decisions (doing so would 
lead, not merely to absurdity, but to madness).    If the matter 
is judged by the community to be substantive and not editorial, 
then I would expect the exception request to be rejected, so 
there would be nothing much to document.

      john

---

From: John C Klensin <[email-masked]>
Date: Wed, 13 Aug 2008 12:54:49 -0400

> "RFC 2606 or its successors" along with BCP 32?

This is really a separate topic and one that it would be nice 
if, after all these years, the IESG, RFC Editor, and, if they 
care, the IAB would make a decision about and then start 
reflecting that decision in style guidelines (including the 
Checklist) and in tools.

While I'm going to use "BCP" in the examples below, the question 
applies equally well to "STD" numbers.

* Is a citation of BCP NN a reference to whatever the current 
version of the BCP, and all of the documents that make it up? 
If so, we need citation and referencing formats for such things 
that are not tied to an RFC number (or, worse, several RFC 
numbers).  We have no such referencing model and some tools, 
such as xml2rfc and its bibliographic libraries, make faking one 
really painful.

* Is a citation of "BCP NN (RFC MMMM)" or "BCP NN [RFCMMMM]" a 
reference to the BCP or a reference to the RFC with a note that 
it is a BCP?   If the latter, should the form be "RFC MMMM (BCP 
NN)" or perhaps "RFC MMMM (BCP NN) [RFCMMMM]"?  Or should this 
form be prohibited?

* If RFC MMMM is a BCP, does referencing it without the BCP 
number mean that future revisions or updates don't count?

* If a particular specification is known much more widely by its 
RFC number than by its BCP one (which is certainly the case for 
RFC 2026), what is the approved form of citation if one wants to 
be clear that the BCP and not the RFC is what counts?  Choices 
include:

    -- Use the BCP number and make people try to find out what
    is being talked about by consulting the bibliography or some
    index outside the document.

    -- Use the RFC number with some text like "or its
    successors", perhaps even "or its successors as BCP NN".

    -- Use the BCP number with the RFC number and hope that
    people figure out the BCP is intended and the RFC is
    specific.

    -- Use the BCP number with the RFC number and a note to make
    the intent clear.

I've clearly got some opinions on this, and they favor clarity 
over ambiguity, even if the clarity involves some possible 
redundancy, but YMMD.    And some editorial guidance in the 
Checklist, in 2223bis or some other style manual, would, IMO, 
really be appreciated.

    john

---

From: Ted Hardie <[email-masked]>
Date: Wed, 13 Aug 2008 10:33:07 -0700

>        Working Groups or authors seeing exemptions from that

Is this "seeking exemptions from that"?

>        community along with the rest of the document. 

I think the "Addresses used in I-Ds SHOULD use FQDNs instead
of literal IP addresses" should add "where either would be
appropriate in the protocol described."  It would be silly
to require that a document describing the IPv6 architecture
include an "Editor's note:" of this type.  I personally think
that it is also silly to require at MUST strength the inclusion
of such a note where there is a long history of IP rather
DNS in a slot (as is the case for SDP).  I would prefer
"Authors should be aware that that the use of IP addresses
where FQDNs or other identifiers would be appropriate
may engender questions and delay.  They may wish to include
explanatory text in an "Editor's Note" or "Note in Draft" to
avoid these issues."  It just seems more like
we're peers discussing the issue that way, rather than the
community being told how the IESG will wield its power.
But I digress.

Authors also need to use a lot of caution in using things
ORCHIDS, which use the same bit patterns as IPv6 addresses but
are not IP-layer, and ULAs, which have routing policy built in to the
address ranges.  Whether we want to include general advice
to that effect here (Caution!  Dangerous ORCHIDS present!)
or not is largely a matter of how exhaustive you want this
to be. It's well past exhaustive enough, in my opinion, but
tastes differ.
			regards,
				Ted
_______________________________________________
Ietf mailing list
[email-masked]
https://www.ietf.org/mailman/listinfo/ietf

---

From: SM <[email-masked]>
Date: Wed, 13 Aug 2008 12:13:27 -0700

At 03:21 13-08-2008, Bert Wijnen \(IETF\) wrote:
>       "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.  Example
>        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
> or        subsequently.   Working groups or editors who 
> are        convinced that different names are required MUST 
> be        prepared to explain and justify their choices and 
> SHOULD        do so with explicit inline comments such as 
> those        described above."

The proposed text is about a specific exception.  It might be better 
to have a more general exemption than one that covers Item 6 only.

I suggest using the following:

   6. Addresses used in I-Ds SHOULD use fully qualified domain names 
(FQDNs) instead
   of literal IP addresses.  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 BCP 32.

   9. Exemptions

   It is recommended that Working Groups or authors seeking exemptions from the
   ID-Checklist explain the rationale with inline comments.  (e.g., 
"Editor's note:"
   or "Note in Draft:" that can be evaluated by the IESG and the IETF 
community along
   with the rest of the document.

Regards,
-sm

---

From: Tony Hansen <[email-masked]>
Date: Wed, 13 Aug 2008 15:36:39 -0400

I think it would be better to use phrasing like this:

	BCP 32 (currently RFC 2606)

Tony Hansen
[email-masked]

John C Klensin wrote:
> This is really a separate topic and one that it would be nice if, after 
> all these years, the IESG, RFC Editor, and, if they care, the IAB would 
> make a decision about and then start reflecting that decision in style 
> guidelines (including the Checklist) and in tools.
> 
> While I'm going to use "BCP" in the examples below, the question applies 
> equally well to "STD" numbers.
> 
> * Is a citation of BCP NN a reference to whatever the current version of 
> the BCP, and all of the documents that make it up? If so, we need 
> citation and referencing formats for such things that are not tied to an 
> RFC number (or, worse, several RFC numbers).  We have no such 
> referencing model and some tools, such as xml2rfc and its bibliographic 
> libraries, make faking one really painful.
> 
> * Is a citation of "BCP NN (RFC MMMM)" or "BCP NN [RFCMMMM]" a reference 
> to the BCP or a reference to the RFC with a note that it is a BCP?   If 
> the latter, should the form be "RFC MMMM (BCP NN)" or perhaps "RFC MMMM 
> (BCP NN) [RFCMMMM]"?  Or should this form be prohibited?
> 
> * If RFC MMMM is a BCP, does referencing it without the BCP number mean 
> that future revisions or updates don't count?
> 
> * If a particular specification is known much more widely by its RFC 
> number than by its BCP one (which is certainly the case for RFC 2026), 
> what is the approved form of citation if one wants to be clear that the 
> BCP and not the RFC is what counts?  Choices include:
> 
> I've clearly got some opinions on this, and they favor clarity over 
> ambiguity, even if the clarity involves some possible redundancy, but 
> YMMD.    And some editorial guidance in the Checklist, in 2223bis or 
> some other style manual, would, IMO, really be appreciated.
> 
>    john
>

---

From: John C Klensin <[email-masked]>
Date: Wed, 13 Aug 2008 19:17:01 -0400

> 	BCP 32 (currently RFC 2606)

And that, of course, has yet a different meaning, although 
probably nearly the same one as the "2606 and successors" 
version does.

    john

---

From: "Eric Gray" <[email-masked]>
Date: Thu, 14 Aug 2008 10:41:27 -0500

John/Tony,

	The issue I have with either formulation is that BCP 32
currently means "RFC 2606 or its successors" - hence either
formulation is redundant.

--
Eric Gray
Principal Engineer
Ericsson  

> Behalf Of John C Klensin
> Sent: Wednesday, August 13, 2008 7:17 PM
> To: Tony Hansen; IETF Discussion
> Subject: Re: BCP or RFC references
> 
> 
>

---

From: Fred Baker <[email-masked]>
Date: Thu, 14 Aug 2008 21:16:26 +0800

I seem to be in the minority, but I object.

This results, if I understand correctly, from the dispute that JCK had  
with the IESG a little while ago. Basically, someone on the IESG felt  
that rules of this sort should apply, an update to an existing  
specification didn't conform, and they objected to an update to an  
existing RFC on the basis of personal opinion. This attempts to  
enshrine that opinion in legislation.

And you know what? I think there are two cases here.

In one case, you have an entirely new document. On that case, no  
argument. If this is the rule we want, let it be, and I am willing to  
see the rule.

In the case the discussion was over, that seems like a big change from  
the document being updated, and the editor would have to be pretty  
about how s/he did it to make sure s/he didn't change anything  
unintentionally. The usage in the past documents hasn't been confusing  
to engineers in the past, and a change to it might introduce confusion.

In the latter case - the case under dispute - I disagree with the  
sense of this rule. I think the important thing is clarity, and  
clarity is enhanced by not changing text whose sense isn't actually  
being changed.

And oh yes, I agree with Eric's comment that including this in an  
erratum stored separate from the document isn't very helpful. I think  
it will come as a surprise to most people when it is enforced, and  
this kind of thing doesn't want surprises.

---

From: Dave Crocker <[email-masked]>
Date: Fri, 15 Aug 2008 09:40:37 -0700

> I seem to be in the minority, but I object.
...
> In the latter case - the case under dispute - I disagree with the sense 
> of this rule. I think the important thing is clarity, and clarity is 
> enhanced by not changing text whose sense isn't actually being changed.

+1

d/

ps. I guess this all settles the question about whether the Checklist mandates 
its own set of formal requirements on RFC content.  This entire discussion is 
about something that is not mandated anywhere else. No other BCP, RFC, or RFC 
Editor document.

-- 

   Dave Crocker
   Brandenburg InternetWorking
   bbiw.net
_______________________________________________
Ietf mailing list
[email-masked]
https://www.ietf.org/mailman/listinfo/ietf

---

From: John C Klensin <[email-masked]>
Date: Fri, 15 Aug 2008 13:05:25 -0400

--On Thursday, August 14, 2008 9:16 PM +0800 Fred Baker 
<[email-masked]> wrote:

> This results, if I understand correctly, from the dispute that
> JCK had with the IESG a little while ago. Basically, someone
> on the IESG felt that rules of this sort should apply, an
> update to an existing specification didn't conform, and they
> objected to an update to an existing RFC on the basis of
> personal opinion. This attempts to enshrine that opinion in
> legislation.
>

yes

> In one case, you have an entirely new document. On that case,
> no argument. If this is the rule we want, let it be, and I am
> willing to see the rule.

Me too, although I've been persuaded by others that there are 
still some reasonable exception cases and that those who think 
they have them should be able to make that case to the community.

> In the case the discussion was over, that seems like a big
> change from the document being updated, and the editor would
> have to be pretty about how s/he did it to make sure s/he
> didn't change anything unintentionally. The usage in the past
> documents hasn't been confusing to engineers in the past, and
> a change to it might introduce confusion.
>
> In the latter case - the case under dispute - I disagree with
> the sense of this rule. I think the important thing is
> clarity, and clarity is enhanced by not changing text whose
> sense isn't actually being changed.

What I anticipated when I wrote the text that Bert picked up was 
that the document editor in this case would simply write a short 
note that said more or less exactly what you say above.  In a 
reasonable world filled with reasonable people, the community 
would accept that argument, the IESG would respond by saying 
"yep, hasn't done any demonstrable harm in years and the 
community seems ok with it", and that would be the end of the 
story (other than the RFC Editor removing the note before 
publication).   If an IESG said, instead, something equivalent 
to "nah, nah, we have this rule and we don't care about 
explanations", then we would have a problem that I-D checklists 
aren't going to fix and, especially since I hope that outcome is 
unlikely, is not worth further consideration in this context.

> And oh yes, I agree with Eric's comment that including this in
> an erratum stored separate from the document isn't very
> helpful. I think it will come as a surprise to most people
> when it is enforced, and this kind of thing doesn't want
> surprises.

Yep.   The use of non-2606 names also should _never_ be an 
error.  It should be an explicit decision made by authors and 
agreed to by the community, just like everything else in an 
IETF-track RFC.

    john

p.s. this whole discussion moves us back toward "checklist as a 
source of definitive rules" rather than "checklist as a general 
guide and source of suggestions".   If it is the former (which I 
believe neither Bert nor I (nor at least some others) want), 
then I think that any reasonable interpretation of our 
procedures require an I-D, Last Call, community consensus, and, 
since the IESG decided that IONs were not needed, publication of 
a BCP.

---

From: "Spencer Dawkins" <[email-masked]>
Date: Fri, 15 Aug 2008 12:19:05 -0500

>> enhanced by not changing text whose sense isn't actually being changed.

For what it's worth, I also agree with Fred's point. It was very significant 
to me that the document under discussion wasn't I-D->PS, it was PS->DS, and 
the distinction that applies in "the latter case" is being ignored here.

I will omit a much longer snotty comment about us not being very good at 
advancing beyond PS because it happens so rarely, but those familiar with 
the topic can fill in details for themselves.

> ps. I guess this all settles the question about whether the Checklist 
> mandates its own set of formal requirements on RFC content.  This entire 
> discussion is about something that is not mandated anywhere else. No other 
> BCP, RFC, or RFC Editor document.

I've been forcing myself not to reply to an earlier (but less forceful) 
point along these lines from Dave, and from Robert's follow-up that provided 
another part of the jigsaw puzzle, but with this clear statement of Dave's 
objection, I don't think silence is appropriate.

Flame on.

We have a sense that we should have community consensus for process 
requirements, and our track record on trying to achieve and declare 
consensus on process requirements is appallingly bad.

Brian wrote a lovely draft that included a number of statements that are in 
our process BCPs that we have NEVER enforced - "periodic review of all 
standards-track documents that haven't reached full standard status yet" 
being my personal favorite, but YMMV - but we don't know what to do with 
that draft, or any suggestions made in that draft, and in the absence of 
doing anything, there our process BCPs lie, describing rules in consensus 
documents we don't enforce.

Since the IESG can't obey the letter of our process BCPs, and we can't 
figure out how to change the letter of those BCPs, they enforce rules that 
aren't described in BCPs, because they are trying to do what the IESG does 
(manage the standards process). If we published the rules they enforce as 
BCPs, we'd know we have community consensus behind those rules, but we 
don't, because we can't figure out how to make that happen.

Russ sponsored the PUFI BOF at IETF 71 
(http://www.ietf.org/proceedings/08mar/pufi.html). I've heard Russ 
characterize that BOF's results several times as "people want to do things, 
but we don't have consensus to do anything". No one has contradicted him 
within my hearing.

Some of us Had Hoped that ISDs slapped around our process BCPs would have 
given the IESG a way to keep our precious-but-frozen BCPs up-to-date 
reflecting what the IESG actually does (among many other advantages of 
ISDs). ISDs didn't happen.

So ...

o Dave's absolutely right in pointing out that documents like the ID-nits 
checklist have no BCP standing,

o We're wedged on coming up with a way to publish process BCPs (even a 
process BCP that says "the IESG can publish documents like ID-nits 
checklist" would be more indication of community consensus than we've got 
behind the ID-nits checklist now), and

o This is a problem.

I said at the IETF 72 plenary mike that the IESG does not have time to solve 
this problem. The ADs I talked to afterwards said the acoustics weren't good 
for the IESG, but no one from the community got up and said that the IESG 
DOES have time to solve this problem.

Does the larger community have any suggestions on how to move beyond

o not enforcing the rules we describe in BCP documents, and

o not describing the rules we enforce in BCP documents?

Flame off. Have a lovely weekend.

Spencer

---

From: "Frank Ellermann" <[email-masked]>
Date: Fri, 15 Aug 2008 21:28:15 +0200

> formulation is redundant.

+1  The ID-checklist can reference RFC 2606, and updating
it to 2606bis later is no obstacle.   That is no general
recipe:  For an RFC 4646 vs. BCP 47 reference there are
some technical details to consider, especially if those
references are in a stable non-IETF document.

But IMO the "checklist" and "BCP 32" are both supposed to
be harmless documents, and not designed to help with the
in various ways special 2821bis case.

 Frank