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

From: IETF Chair <[email-masked]>
Date: Tue, 8 Jul 2008 11:44:27 -0700 (PDT)

>From the discussion just prior to the recent appeal by John Klensin, it
was clear that the guidance regarding example domain names in IETF
documents provided in the ID-Checklist needed to be updated.  This point
was emphasized further during the discussion of the Klensin appeal. 
Proposed text is now available.  Many thanks to Bert Wijnen for continuing
to edit the document.

The IESG solicits comments on this proposed update.  The IESG plans to
make a decision on this proposed text on 2008-07-17.  Please send
substantive comments to the [email-masked] mailing lists by 2008-07-16.
Exceptionally, comments may be sent to [email-masked] instead.  In either
case, please retain the beginning of the Subject line to allow automated
sorting.

The proposed text can be obtained via
http://www.ietf.org/Draft-ID-Checklist.html 
_______________________________________________
Ietf mailing list
[email-masked]
https://www.ietf.org/mailman/listinfo/ietf

---

From: Dave Crocker <[email-masked]>
Date: Tue, 08 Jul 2008 12:08:12 -0700

> Proposed text is now available.  Many thanks to Bert Wijnen for continuing

1. Document scope and force

    This isn't a 'nits' or 'checklist' document.  It is a formal specification 
of requirements for RFC format and style, per "All Internet Drafts which are 
offered for publication as RFCs must conform to the following requirements or 
they will be returned to the author(s)/editor(s) for revision."

    That's fine, but that reality should be cast clearly, directly and from the 
start, including the Abstract.

    It also suggests that the document needs to receive a full IETF consensus 
approval.

    Small point of confusion: I thought the RFC document series was managed with 
some independence of the IETF.  As such, I'm not clear how the IETF (nevermind 
the IESG) can set the rules for RFC format and style.

    Please note that this is not meant to challenge the benefit of having clear 
and precise formal statement of RFC format and style.  It's just that it would 
be helpful to be clear about who is in charge, what the scope is, and whether 
the formal rules for decision-making are being followed.

2. Normative language

    The document uses normative language, some is in upper case and some is not. 
The document needs a careful pass for its use of normative language, to make it 
consistent and unambiguous.  An interesting current example is 3.1.A: "most 
abbreviations must be expanded on first use."  Semantically, I believe this 
means "abbreviations SHOULD be expanded on first use."  Simpler, clearer...

3.  Confusion of goals

    The document includes advice that might be quite a good idea, but it has 
nothing to do with RFC format or 'style' in the sense that a nits program can 
check.  For example "Avoid IPv4 specificity." sounds reasonable but is a 
massively generic suggestion.  Does it really belong in something supposedly 
getting at formatting issues?

d/

-- 

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

---

From: Pete Resnick <[email-masked]>
Date: Tue, 8 Jul 2008 14:17:52 -0500

On 7/8/08 at 11:44 AM -0700, IETF Chair wrote:

>The IESG solicits comments on this proposed update.  The IESG plans 
>to make a decision on this proposed text on 2008-07-17.  Please send 
>substantive comments to the [email-masked] mailing lists by 
>2008-07-16. Exceptionally, comments may be sent to [email-masked] 
>instead.  In either case, please retain the beginning of the Subject 
>line to allow automated sorting.

Insert in the Introduction, before or at the beginning of "Notes:"

-----
This memo uses the terms "MUST", "REQUIRED", "SHOULD", and 
"RECOMMENDED",  similarly to the use of these terms in RFC 2119. In 
particular, when they appear in ALL CAPS in this memo:

   -"MUST" or "REQUIRED" means that if you do not do this in your I-D, 
the IESG will not accept the I-D for any review until the item is 
complete.

   - "SHOULD" or "RECOMMENDED" means that there may be valid reasons 
to ignore the item, but an explanation must be given, either in the 
text of the document or as part of the submission to the IESG, as to 
why the item is being ignored. Otherwise, the IESG may not accept the 
I-D for review.
-----

This text both (a) puts draft authors on notice as to what the hard 
requirements are in order to avoid late surprises, and (b) puts 
reviewers of this memo on notice so that consensus can be reached on 
what are or are not real showstoppers for IESG review.

pr
-- 
Pete Resnick <http://www.qualcomm.com/~presnick/>
Qualcomm Incorporated - Direct phone: (858)651-4478, Fax: (858)651-1102
_______________________________________________
Ietf mailing list
[email-masked]
https://www.ietf.org/mailman/listinfo/ietf

---

From: Pete Resnick <[email-masked]>
Date: Tue, 8 Jul 2008 14:27:41 -0500

The document says:

"If ABNF is used, you MUST include a normative reference to RFC 4234."

To quote two fine radio personalities here in the states, this one 
seems "boooooooooogus". Yes, any I-D that uses ABNF must include a 
normative reference to RFC 4234, but for the IESG to not engage in 
review until it is in there is silly beyond belief. Make a note to 
the author that they need the reference and continue consideration.

pr

---

From: Dave Crocker <[email-masked]>
Date: Tue, 08 Jul 2008 12:37:23 -0700

Pete Resnick wrote:
>      Yes, any I-D that uses ABNF must include a normative
> reference to RFC 4234, but for the IESG to not engage in review until it 
> is in there is silly beyond belief. Make a note to the author that they 
> need the reference and continue consideration.

Hmmm.  Mayhaps the doc should make its own clear and pragmatic distinction 
between MUST and SHOULD, in terms of what is acceptable for immediate 
processing, with MUST restricted to immediate showstoppers?

d/

-- 

   Dave Crocker

---

From: "Bert Wijnen - IETF" <[email-masked]>
Date: Tue, 8 Jul 2008 21:43:01 +0200

Mmm... as editor of the document, maybe I should explain how this document
came into existence several years ago. It was back then that the IESG got
many many documents that had a lot of these simple (and easy to fix) 
issues. Some look like showstoppers, others are not so much showstoppers, 
but they do take extra time (of many people) if they need to be fixed 
once the document goes into IETF Last Call. So in order to try and make
doument authors/editors and also WG chairs aware of what the many 
little errors were that we as IESG often saw, we composed this document.

Hope this helps,

Bert Wijnen 

> -----Oorspronkelijk bericht-----
> Van: [email-masked] [mailto:[email-masked]]Namens Pete
> Resnick
> Verzonden: dinsdag 8 juli 2008 21:28
> Aan: [email-masked]
> CC: IETF Chair; [email-masked]
> Onderwerp: Re: Call for review of proposed update to ID-Checklist
> 
> 
> The document says:
>

---

From: John C Klensin <[email-masked]>
Date: Tue, 08 Jul 2008 16:04:33 -0400

Hi.

I'm likely to have some other comments on this once I get
through studying it, but the recent notes from Pete and Dave
make a start on some of them.  Rather than trying to put
together a single long note...

--On Tuesday, 08 July, 2008 14:17 -0500 Pete Resnick
<[email-masked]> wrote:

>...
> "RECOMMENDED",  similarly to the use of these terms in RFC
> 2119. In particular, when they appear in ALL CAPS in this memo:
> 
>    -"MUST" or "REQUIRED" means that if you do not do this in
> your I-D, the IESG will not accept the I-D for any review
> until the item is complete.
> 
>    - "SHOULD" or "RECOMMENDED" means that there may be valid
> reasons to ignore the item, but an explanation must be given,
> either in the text of the document or as part of the
> submission to the IESG, as to why the item is being ignored.
> Otherwise, the IESG may not accept the I-D for review.
> -----
> 
> This text both (a) puts draft authors on notice as to what the
> hard requirements are in order to avoid late surprises, and
> (b) puts reviewers of this memo on notice so that consensus
> can be reached on what are or are not real showstoppers for
> IESG review.

While I agree, I believe that it would be of great help if the
IESG  gave indications of the situations in which an exception
to a "SHOULD" would be appropriate.  The last thing the
community needs, as a consequence of this document or otherwise,
is to expand the basis on which the IESG can block a document
for reasons that are essentially non-technical and that come as
a surprise to authors.

For at least the MUST list, if we are going down this path, it
would be good to improve efficiency and reduce AD workload by
getting the IESG out of the loop entirely.   As an alternative,
as Pete suggested about one specific case in a different note,
treat a "MUST" as "note and move on, with final approval
contingent on getting the issue fixed".   In other words, if
something is a MUST condition, then either the document
shepherd, the secretariat, or both should be able to verify that
condition and block or flag the document if it is not met.  We
should not be wasting AD time that way unless the ADs really
have nothing better to do with their time.
 
IMO, the IESG should be spending energy evaluating only those
conditions that require judgment as to appropriateness, i.e.,
the SHOULDs.

    john

---

From: "Bert Wijnen - IETF" <[email-masked]>
Date: Tue, 8 Jul 2008 22:28:28 +0200

> conditions that require judgment as to appropriateness, i.e.,

The ID-Checklist was (and I believe still IS) intended to do just that.
When a document shepherd does answer the questions of RFC4848 in section
3.1,
then the shepherd (often WG chair) is asked to confirm that he did check
of the document to meet the ID-Checklist (see question 1.g on page 6).
So it happens BEFORE one or many ADs go spend a lot of time on the document.
And it was specifically intended to NOT cause surprised and to prepare the
document in a good shape before being submitted for review by many people
outside the WG.

Bert

---

From: John C Klensin <[email-masked]>
Date: Tue, 08 Jul 2008 16:34:43 -0400

Bert,

FWIW, that is always how I have taken the list and why I have
appreciated the effort, both when you led the initial version
and the IESG's effort to clarify things now.   I, at least, also
appreciated the "DISCUSS criteria" document in the same spirit
-- the more the community understands about what the IESG
expects or requires, and on what issues the IESG considers it
appropriate to block documents regardless of consensus in the
developing group or the community in general, the better off we
will all be... and the less work both editors and the IESG
should have to do. 

But, in the presence of something that seemed to express a
strong preference turning into a firm, and very broad, rule in a
way that some of us found surprising, it seems worth the effort
on this round to push a little bit further in the direction of
clarity.

    john

--On Tuesday, 08 July, 2008 22:28 +0200 Bert Wijnen - IETF
<[email-masked]> wrote:

> The ID-Checklist was (and I believe still IS) intended to do
> just that. When a document shepherd does answer the questions
> of RFC4848 in section 3.1,
> then the shepherd (often WG chair) is asked to confirm that he
> did check of the document to meet the ID-Checklist (see
> question 1.g on page 6). So it happens BEFORE one or many ADs
> go spend a lot of time on the document. And it was
> specifically intended to NOT cause surprised and to prepare the
> document in a good shape before being submitted for review by
> many people outside the WG.
> 
> Bert
>>     john
>

---

From: Theodore Tso <[email-masked]>
Date: Tue, 8 Jul 2008 17:35:02 -0400

On Tue, Jul 08, 2008 at 02:27:41PM -0500, Pete Resnick wrote:
> To quote two fine radio personalities here in the states, this one seems 
> "boooooooooogus". Yes, any I-D that uses ABNF must include a normative 

Stupid question ---- isn't this specific thing something we should
allow the secretariat to fix as part of the RFC publishing process,
and in fact give them instructions to add the reference if they find
it missing?  They do things like fix/update references IIRC, and this
is only a minor step beyond that, and should be well within their
capabilities, I would think.

Sure, we can ask document editors to add the reference to RFC 4234,
and maybe we can even do things like include a reference to RFC 4234
in an RFC template file with a note to remove if the standard ends up
not using ABNF, but there must be a class of things which could be
streamlined to save time on both the document editors, reviewers, and
AD's time.

Regards,

						- Ted

---

From: Brian E Carpenter <[email-masked]>
Date: Wed, 09 Jul 2008 12:13:54 +1200

On 2008-07-09 07:08, Dave Crocker wrote:
...
>    Small point of confusion: I thought the RFC document series was
> managed with some independence of the IETF.  As such, I'm not clear how
> the IETF (nevermind the IESG) can set the rules for RFC format and style.

I view the id-checklist as a gating factor for IESG review, not as
instructions to the RFC Editor. Of course it should be consistent
with the RFC Editor's practice, as a matter of common sense. The
introduction should make this clear, perhaps.

   Brian

---

From: "Frank Ellermann" <[email-masked]>
Date: Wed, 9 Jul 2008 05:21:13 +0200

> normative reference to RFC 4234

The ID-Checklist should pass a simple IDnits test, which would point
out that RFC 4234 was obsoleted by RFC 5234 six months ago (IIRC).

The ID-Checklist should exist in plain text format.  The output was
obviously created by xml2rfc, which can also create plain text, and
plain text can be processed by IDnits.  It can be also processed by
"rfcmarkup" to create the simple HTML working with older browsers.  

It can be also processed by various cute I-D diff tools, allowing
reviews of small changes.

 Frank

---

From: Thomas Narten <[email-masked]>
Date: Wed, 09 Jul 2008 10:19:04 -0400

John C Klensin <[email-masked]> writes:

> to a "SHOULD" would be appropriate.

Yes.

And on the particular question of example DNS names:

> 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] (Eastlake, D. and A. Panitz, "Reserved Top Level DNS
>     Names," June 1999.) for example domain names that can be used.

Why the SHOULD? Presumably, because you don't want naive folk to take
the examples in the RFC and use them in local config files and such,
causing problems or other undesirable effects when they (unexpectedly)
get used in the real world..

But in cases where this really is not a concern, there is also
presumably not a need to _require_ use of the example names.

Thomas

---

From: "Spencer Dawkins" <[email-masked]>
Date: Wed, 9 Jul 2008 10:49:46 -0500

Dear IESG,

> case, please retain the beginning of the Subject line to allow automated

I agree with moving the 2606 check to "SHOULD".

It is often helpful to provide guidance about when SHOULDs might not be 
appropriate, when we have at least some experience where this is the case.

Were I to propose text, I think we have some experience that's popped up 
during the appeal discussion, as follows:

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] (Eastlake, D. 
and A. Panitz, "Reserved Top Level DNS Names," June 1999.) for example 
domain names that can be used.

The use of reserved example FQDNs, IP addresses or network prefixes may not 
be appropriate in all cases, including these (which have come up in 
practice):

o If an example describes a complex network topology, it could be 
appropriate to use a variety of names, IP addresses or prefixes that are 
easily disambiguated, so that the reader might follow the example more 
easily.

o If a standards-track document that does not use example names is 
advancing, it could be appropriate to minimize text changes as the document 
advances (the names used in the document have already been published, so the 
question should be whether there is additional damage that would result from 
the second publication on the standards track).

Thanks,

Spencer

---

From: Bill McQuillan <[email-masked]>
Date: Wed, 9 Jul 2008 09:37:28 -0700

On Wed, 2008-07-09, Spencer Dawkins wrote:
> If an example describes a complex network topology, it could be 

I wonder if it would make it easier to use "example" DNS names if, in
addition to the verbose and clumsy: "*.example", IMHO, we reserved gTLDs
like "*.foo", "*.bar", "*.bat", "*.baz", as well as the one used quite
frequently on this list lately: "*.tld", for use as example DNS names.

Or do we assume that economic concerns would triumph here?

-- 
Bill McQuillan <[email-masked]>

---

From: Paul Hoffman <[email-masked]>
Date: Wed, 9 Jul 2008 10:03:26 -0700

>frequently on this list lately: "*.tld", for use as example DNS names.

"foo" and "bar" seem fine for nerdy IETF examples. "bat" would pose 
similar security issues as "com" :-). "baz" seems awfully close to 
the ever-so-popular "biz" TLD.

"tld" seems like an excellent suggestion. Not much like any current 
TLDs; it's well-known in the field of use; it is unlikely that there 
is much commercial value to it; it's nearly impossible to pronounce 
without spelling out the acronym.

--Paul Hoffman, Director
--VPN Consortium

---

From: "Spencer Dawkins" <[email-masked]>
Date: Wed, 9 Jul 2008 12:22:02 -0500

hi, bill,

> frequently on this list lately: "*.tld", for use as example DNS names.

in a 2606bis, right?

spencer

---

From: "Frank Ellermann" <[email-masked]>
Date: Wed, 9 Jul 2008 19:27:35 +0200

Bill McQuillan wrote:

> I wonder if it would make it easier to use "example" DNS
> names if, in addition to the verbose and clumsy: "*.example",
> IMHO, we reserved gTLDs like "*.foo", "*.bar", "*.bat", 
> "*.baz", as well as the one used quite frequently on this
> list lately: "*.tld", for use as example DNS names.
 
> Or do we assume that economic concerns would triumph here?

After about 100 articles with "2606" in the subject finally a
note which really is about 2606, even if not in the subject :-)

There is certainly a tradition to use *.tld in examples, and
we could say that we want this officially reserved.  While at
it we could also grab the 11 IDN example labels used together
with the 11 IDN test TLDs in the (running) IDN test.  That
would give us 13 example TLDs, plus three known *.example.cno.
IMO more than enough, otherwise we could add *.lit to the set.

But the keyword is "grab" as in "domain grabbing".  Without a
clear technical demand for this it could upset folks with an
interest and the money to buy TLD .tld for dubious purposes.

So far the support to grab those 11 IDN example labels as TLDs
was not overhelming, otherwise you would already see it in the 
2606bis draft (idnabis-test-tlds).

 Frank

---

From: Keith Moore <[email-masked]>
Date: Wed, 09 Jul 2008 16:06:23 -0400

> presumably not a need to _require_ use of the example names.

+1

Also, I'm convinced that in a document requiring numerous example 
domains, that restricting to 2606 domains can reduce readability.
(the DSN specifications come immediately to mind)

Keith

---

From: John C Klensin <[email-masked]>
Date: Wed, 09 Jul 2008 17:03:25 -0400

--On Wednesday, 09 July, 2008 10:19 -0400 Thomas Narten
<[email-masked]> wrote:

>> 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] (Eastlake, D. and A.
>>     Panitz, "Reserved Top Level DNS Names," June 1999.) for
>>     example domain names that can be used.
> 
> Why the SHOULD? Presumably, because you don't want naive folk
> to take the examples in the RFC and use them in local config
> files and such, causing problems or other undesirable effects
> when they (unexpectedly) get used in the real world..
> 

Well, I agree, but, based on the response to the 2821bis appeal
and the proposed RFC Editor note on that document, the IESG
apparently sees actual harm (rather than, e.g., impolite
behavior) where some of the rest of us do not.  In the interest
of being constructive, reducing ambiguity, surprises and
post-last-call quibbling, of focusing on the areas where I think
there is consensus about harm, and of being specific, I propose
the following as alternative text: 

	"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).  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."

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.

	(ii) There is, at best, much less consensus that use of
	non-2606 names in narrative or illustrative examples is
	likely to be harmful.  There may be consensus that it is
	impolite (or, to quote some recent IESG comments,
	"rude") but that is, IMO, a rather different matter.
	
	(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.
	
	(iv) If someone wants to use non-2606 names, it is
	entirely reasonable to expect them to explain why and to
	do so in public.  If that drives editors and WGs to take
	the path of least resistance and use the 2606 names, I
	think it should be fine with all of us.

FWIW, please note the philosophical similarity between the above
and RFC 4897.  In both cases, we move away from incentives for
elaborate procedures and private negotiations between the IESG
and authors (and the consequent late-stage guessing about what
is likely to happen).  Instead, we get the issues and
justifications up front as part of document processing or in the
document itself so that the community can address them as part
of Last Call.  The IESG can then make decisions based on
evidence of community consensus (or community indifference, as
the case may be).

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

    john

---

From: Ted Hardie <[email-masked]>
Date: Wed, 9 Jul 2008 14:25:49 -0700

At 2:03 PM -0700 7/9/08, John C Klensin wrote:

>I propose

A nit with this:

>        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.

> It is generally

See above.  There are places where it will be required. 

>        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.

>I think that is supposed to be what we all want around here,

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.

				regards,
					Ted

---

From: Keith Moore <[email-masked]>
Date: Wed, 09 Jul 2008 19:22:13 -0400

> 	reasonably require clear and strong justification.

I take issue with that as a general statement.  There are plenty of 
applications where the ability to use literal addresses on an occasional 
basis is quite useful - e.g. for diagnostic purposes (of various kinds) 
or in a pinch when DNS is broken or not set up correctly.  Furthermore 
addresses are precise where domain names are not.

To remove the capability to use address literals is to cripple our 
protocols.

(your other three points seemed fine to me)

Keith