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

From: "Bert Wijnen \(IETF\)" <[email-masked]>
Date: Sat, 9 Aug 2008 21:43:50 +0200

As you all can see, the ID-Checklist in fact DOES refer to
the rfc2223bis at many places. It has now been updated (in my copy)
to point to the RFC-Editor-Style Manual. Specifically section 2
discusses this, and sect 2.1 starts out by stating:

   In principle, the RFC-Editor can take care of a few small formatting 
errors.
   And if there are only a few, then they will do so. However, if many 
errors
   exist, the document will be returned to the author(s)/editor(s)/WG for 
fixes.
   In any event, please realize that not following the formatting rules will 
most
   probably delay publication and does consume time that can be spend on
   other work.

It could be made clearer that the ID-Checklist is specifically intended for
final I-Ds that are submitted to an AD, i.e. a request for publication
to the AD/IESG.

The first Note in the Introduction section does say so.
But to be more clear, I have changed the fuirst sentence of sect 1.
from

    All Internet Drafts which are offered for publication as RFCs

into

    All Internet Drafts which are offered to an AD or the IESG with a 
request
    for publication as RFC

I hope that clarifies.

Bert
Editor for ID_checklist

----- Original Message ----- 
From: "Brian E Carpenter" <[email-masked]>
To: <[email-masked]>
Cc: <[email-masked]>; <[email-masked]>
Sent: Wednesday, July 09, 2008 2:13 AM
Subject: Re: Call for review of proposed update to ID-Checklist

Re: Call for review of proposed update to ID-ChecklistOn 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
_______________________________________________
Ietf mailing list
[email-masked]
https://www.ietf.org/mailman/listinfo/ietf

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

---

From: Dave Crocker <[email-masked]>
Date: Sun, 10 Aug 2008 09:14:42 -0700

Bert,

Bert Wijnen (IETF) wrote:
> As you all can see, the ID-Checklist in fact DOES refer to the rfc2223bis at
>  many places.

Yes, but...

1. draft-rfc-editor-rfc2223bis is expired.

2. While the citations that are included mostly do include the specific section
to look in, some do not.  (See the first example, below.) Hence, some of the
citations are too broad.

3. Much of the document's direction is offered without citation.

 From the July 4 <http://www.ietf.org/ID-Checklist.html>...

> 2.2.  Required sections - all I-Ds
...
> List of authors/editors
> 
> There should not be more than 5 authors/editors (see 
> http://www.rfc-editor.org/policy.html)

The Policy document is about 10 pages long.  I thought the specific information
would be in "Authors vs. Contributors" but it wasn't.   One has to search awhile
to find Item #1 under an interestingly named section "Author Overload", to find
the basis for the "should" in the checklist.

And note that the normative "should" language in the Checklist, here, might be
considered stronger than what is actually said in the RFC Editor's policy
document.  (One can debate this, but then, that debate is exactly what we ought
to have, based on hard data like this. My own opinion is that the "should" is
appropriate here, in terms of actual practice, and it's long been what I advise
folk writing drafts.)

> 1.  Introduction
...
> As a suggestion for productivity improvement, it is strongly RECOMMENDED to 
> use XML2RFC

The capitalization appears intended to offer essentially normative guidance but,
of course, that's probably not what is meant.

> 2.2.  Required sections - all I-Ds
> 
> The following are REQUIRED sections in all Internet-Drafts:

What is the basis for asserting that this list is *required* (and, by the way,
is "required" meant as a normative term; the caps suggest yes)?  Again, please 
note that I'm not claiming the list is wrong, but that its provenance is absent. 
So your view that "Our processes are described in formally approved BCP 
documents" might be at risk.

> 3.  Content issues
...
> B. no citations

While I happen to think this is quite good advice, I have no idea a) where it
comes from, or b) whether it is guidance or requirement.

The one before it, "Should be meaningful to someone not versed in the
technology" also lacks basis.  Further, as guidance, it's reasonable, but
entirely lacking in substance to help an author know how to satisfy it.

and also from that section:

> Specific IPR (e.g., patent claims & terms) must not be in an RFC

The "must" is interesting.  What BCP documents this (entirely reasonable, IMO)
requirement?

And so on.

d/

-- 

   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: Sun, 10 Aug 2008 17:32:31 -0400

> appropriate here, in terms of actual practice, and it's long
> been what I advise folk writing drafts.)

And this is precisely one of the examples to which I was 
referring, because, in exceptional circumstances, the RFC Editor 
has been willing to negotiate that limit.  However, if my memory 
is correct, the "nits" checker, which draws its authority from 
the Checklist, gets sufficiently annoyed about more than five 
authors to prevent posting of I-Ds.

>> 1.  Introduction
> ...
>> As a suggestion for productivity improvement, it is strongly
>> RECOMMENDED to  use XML2RFC
>

And, the last I checked, there were MSWord tools that are 
considered as productive as xml2rfc (even if they are not to the 
personal taste of some of us).

   john

---

From: Henrik Levkowetz <[email-masked]>
Date: Mon, 11 Aug 2008 00:54:41 +0200

Hi John,

...
> authors to prevent posting of I-Ds.

Umm???

If you're referring to idnits, it does no test the number of authors
in any way or form.  I haven't checked whether the current, soon-to
be replaced submission tool tries to check this, but idnits does
most emphatically not.

	Henrik

---

From: John C Klensin <[email-masked]>
Date: Sun, 10 Aug 2008 19:46:02 -0400

--On Monday, August 11, 2008 12:54 AM +0200 Henrik Levkowetz 
<[email-masked]> wrote:

>> referring, because, in exceptional circumstances, the RFC
>> Editor  has been willing to negotiate that limit.  However,
>> if my memory  is correct, the "nits" checker, which draws its
>> authority from  the Checklist, gets sufficiently annoyed
>> about more than five  authors to prevent posting of I-Ds.
>
> Umm???
>
> be replaced submission tool tries to check this, but idnits
> does most emphatically not.

I apologize to idnits.   I have seen documents rejected by some 
process because they had more than five authors, but I don't 
remember whether it was the submission tool or someone 
overzealous at the (present or past) Secretariat.

    john

---

From: Henrik Levkowetz <[email-masked]>
Date: Mon, 11 Aug 2008 10:21:55 +0200

Hi John,

...
> overzealous at the (present or past) Secretariat.

Ok.  Which leaves establishing the desired behaviour of the draft
submission mechanisms.  

My personal viewpoint is that it would be inappropriate to strictly
enforce a limit of 5 authors.  The use of 'should' in section 2.2,
item 2 of the current document ('There should not be more than 5
authors/editors') seems appropriate given the current RFC Editor
policy, and tools-wise this would then be implemented as a note or
warning at the most, but should never cause a refusal to accept a draft
submission.

	Henrik

---

From: Julian Reschke <[email-masked]>
Date: Mon, 11 Aug 2008 10:28:17 +0200

> warning at the most, but should never cause a refusal to accept a draft

+1

BR, Julian

---

From: "Bert Wijnen \(IETF\)" <[email-masked]>
Date: Mon, 11 Aug 2008 10:51:41 +0200

inline
----- Original Message ----- 
From: "Dave Crocker" <[email-masked]>
To: "Bert Wijnen (IETF)" <[email-masked]>
Cc: "Brian E Carpenter" <[email-masked]>; <[email-masked]>; 
<[email-masked]>
Sent: Sunday, August 10, 2008 6:14 PM
Subject: Re: Call for review of proposed update to ID-Checklist

> 1. draft-rfc-editor-rfc2223bis is expired.

I know. and the RFC-Editor has givem me a pointer to
    http://www.rfc-editor.org/rfc-style-guide/rfc-style-manual-08.txt
which replaces rfc2223bis and this will be in the next revision (1.9)
as I had already stated in an earlier posting.

> appropriate here, in terms of actual practice, and it's long been what I 

I can change the pointer to
    http://www.rfc-editor.org/policy.html#policy.authlist

if that helps.

Again, a lower case "should" is certainly not nromative in the sense you 
seem to
interpret it. Let me also say that this point became part of the 
ID_Checklist after
the RFC-Editor was exposed to I-Ds that had 15 or so people on the front 
page
and then when the AUTH48 phase was entered it was enourmously time-comsuming
and nearly impossible to reach (and get a response) from all the umpteen
people on the front-page.

>
>
>> 1.  Introduction
> ...
>> As a suggestion for productivity improvement, it is strongly RECOMMENDED 
>> to use XML2RFC
>

wow... some of you seem to jump to RED-Alert when you see a capitalized
term. It is there as strong advise. I personally have no problem changing
that to lower case. I am checking with IESG on that.

> is "required" meant as a normative term; the caps suggest yes)?  Again, 
> please note that I'm not claiming the list is wrong, but that its 
> provenance is absent. So your view that "Our processes are described in 
> formally approved BCP documents" might be at risk.
>
I can live with making it lowercase (I am checking with IESG).
The first MUST in point 1 in sect 2.2 is certainly based on a real thing.
But even if we make all the capitalized MUST/SHOULD/RECOMMENDED
lower case, even then the ID_Checklist is very usefull.

> comes from, or b) whether it is guidance or requirement.

comes from RFC-Editor. See last para in
   http://www.rfc-editor.org/policy.html#policy.abstract
I can add the pointer if that helps.

> entirely lacking in substance to help an author know how to satisfy it.

It came from rfc2223bis or at least how I (and the IESG at the time of first
ID_Checklist revision) interpreted:

      The Abstract section should provide a concise and comprehensive
      overview of the purpose and contents of the entire document, to
      give a technically knowledgeable reader a general overview of the
      function of the document.  In addition to its function in the RFC
      itself, the Abstract section text will appear in publication
      announcements and in the online index of RFCs.

I think the intent is that the reader of an abstract of course should be
somewhat technically knowledgebale, but that he/she should not have
to be an expert in the technology described in the document. I.e.
the abstract is intended for technically knowledgeable people that
have not participated in the production of the RFC (or the
technology described in the RFC).
If you have better wording to suggest, pls do so.

> The "must" is interesting.  What BCP documents this (entirely reasonable, 

Does not point 4
    4.  Specific IPR (e.g., patent claims & terms) must not be in an RFC (or 
Internet-Draft).
         Any claims must go to the IETF IPR web page and notice that there 
is some IPR
         claim. The mandatory IPR Notice from [RFC3979] (Bradner, S., 
"Intellectual
         Property Rights in IETF Technology," March 2005.) section 5 points 
readers
         to the IETF IPR web page.
clealry point you to the basis (RFC3979) ???
The point was/is that some people put one specific IPR claim in the RFC.
And such is useless, after the RFC is published, new claims may come in,
So the IPR Notice from RFC3979 makes it clear that there *may* (my emphasis)
be IPR claims, but that you must go to the IETF IPR disclosure web pages to
see which ones (if any) there are.

> And so on.

Pls point out all the issues/concerns you have (if you want a personal email
is fine). As you probably know, things that seem obvious for the editor of
a document may not be obvious to readers of the document.

Bert

---

From: Dave Crocker <[email-masked]>
Date: Mon, 11 Aug 2008 07:35:16 -0700

> warning at the most, but should never cause a refusal to accept a draft

1. "enforce a limit"  moves a should to a must.

2. The RFC Editor's policy document does not use language that is as strong as a 
should.

Hence, the ID Checklist is making a normative statement stronger than the RFC 
Editor and the proposal for the checker to 'enforce' is even stronger than that.

By contrast, last sentence suggesting simply printing a notice that there are 
more authors than preferred captures the RFC Editor policy's statement.

d/
-- 

   Dave Crocker

---

From: Dave Crocker <[email-masked]>
Date: Mon, 11 Aug 2008 09:01:50 -0700

> http://www.rfc-editor.org/policy.html#policy.authlist

It gets the reader to the right sections, so yes, it helps quite a bit.

> Again, a lower case "should" is certainly not nromative in the sense you

This semantic distinction between upper and lower case that folks keep making is
not supported by RFC 2119.  The RFC's "these words are often capitalized" does 
not mean "these words must always be capitalized in order to mean that they are 
normative."

Case distinction for semantics also goes against normal rules for English.

> seem to interpret it. Let me also say that this point became part of the 
> ID_Checklist after the RFC-Editor was exposed to I-Ds that had 15 or so
> people on the front page and then when the AUTH48 phase was entered it was
> enourmously time-comsuming and nearly impossible to reach (and get a
> response) from all the umpteen people on the front-page.

And yet the RFC Editor has not yet stated that this is a hard limit, nor has the
IETF consensus process imposed it.  So it makes no sense to have the Checklist 
mechanism enforce such a limit.

What we also have here is the usual debate problem with citing an extreme 
outlier (15 authors) as demonstrating a pervasive problem, while ignoring 
reasonable exceptions (6 authors) that can and do occur.

We really need to get out of the habit of attempting to stop (or impose) change 
by citing only one side of the issue -- and and extreme version of that side. 
There are problems with change and with no change. The choice between them 
should consider the *balance* of cost and benefit of the change and the cost and 
benefit of no change.

>> The capitalization appears intended to offer essentially normative guidance
>> but, of course, that's probably not what is meant.
> 
> wow... some of you seem to jump to RED-Alert when you see a capitalized term.

Bert, now I am completely confused.  Above you stated "lower case 'should' is 
certainly not normative" and yet here you take exception to the interpretation 
of a capitalized term as implying that it is normative.

> It is there as strong advise. I personally have no problem changing that to
> lower case. I am checking with IESG on that.

How is the reader to know what is required and what is merely "advise"?  We are 
in the specification business.  Where is the distinction specified?

> I can live with making it lowercase (I am checking with IESG). The first MUST
> in point 1 in sect 2.2 is certainly based on a real thing. But even if we
> make all the capitalized MUST/SHOULD/RECOMMENDED lower case, even then the
> ID_Checklist is very usefull.

I don't recall anyone suggesting that the checklist or the checker weren't 
useful.  I thought that the discussion was how to make the *more* useful.

>>> 3.  Content issues
>> ...
>>> B. no citations
>> 
>> While I happen to think this is quite good advice, I have no idea a) where
>> it comes from, or b) whether it is guidance or requirement.
> 
> http://www.rfc-editor.org/policy.html#policy.abstract I can add the pointer
> if that helps.

Yup. Tnx.

>> technology" also lacks basis.  
> 

The important point is that by having a citation, then we get to compare the 
authoritative statement with the synthesis that made it into the checklist.

For the moment, it is really secondary as to whether that synthesis retained or 
lost the useful information.

(FWIW, in terms of offering anything useful for the user of the Checklist, I 
think it lost it.  Note the massive difference in detailed guidance, such as for 
2.1 Formatting, versus this entirely generic "Should be meaningful to someone 
not versed in the technology."  While "not versed in the technology" is a 
somewhat useful tidbit, the Checklist text provides none of the affirmative, 
semantic content guidance in the RFC Editor document.)

>> The "must" is interesting.  What BCP documents this (entirely reasonable,
>> IMO) requirement?
>> 
> 
> Does not point 4 4.  Specific IPR (e.g., patent claims & terms) must not be
> in an RFC (or Internet-Draft). Any claims must go to the IETF IPR web page
> and notice that there is some IPR claim. The mandatory IPR Notice from
> [RFC3979] (Bradner, S., "Intellectual Property Rights in IETF Technology,"
> March 2005.) section 5 points readers to the IETF IPR web page. clealry point
> you to the basis (RFC3979) ??? The point was/is that some people put one
> specific IPR claim in the RFC. And such is useless, after the RFC is

Bert, once again, I'm not suggesting the guidance is "wrong", but that it is 
without substantiation.  It asserts a *requirement* that it seems to have invented.

RFC 3979 says what is to be in an RFC, not what isn't. The Checklist says what 
isn't.

> Pls point out all the issues/concerns you have (if you want a personal email 

I did that:  Each and every assertion that says or implies anything more than 
"it can be helpful to do this" needs to provide a narrow citation for its basis.

d/
-- 

   Dave Crocker

---

From: Henrik Levkowetz <[email-masked]>
Date: Mon, 11 Aug 2008 18:54:22 +0200

Hi Dave,

> 1. "enforce a limit"  moves a should to a must.

Yes, but nobody is arguing that this should be done...

> Editor and the proposal for the checker to 'enforce' is even stronger than that.

Repeating myself in a new context:  Umm??

I didn't propose that the checker enforce such a limit, and I'm not aware of
anyone else proposing it, thus I don't understand why you seem to argue against
a proposal nobody seems to have made.  Have I misunderstood what you seem to
be saying immediately above, or have you misunderstood my position?

> more authors than preferred captures the RFC Editor policy's statement.

I think you are saying that this makes sense?  If so, I think we're in agreement.

	Henrik

---

From: "Bert Wijnen \(IETF\)" <[email-masked]>
Date: Mon, 11 Aug 2008 22:00:45 +0200

W.r.t.

----- Original Message ----- 
From: "Dave Crocker" <[email-masked]>
To: "Bert Wijnen (IETF)" <[email-masked]>
Cc: <[email-masked]>; <[email-masked]>
Sent: Monday, August 11, 2008 6:01 PM
Subject: Re: Call for review of proposed update to ID-Checklist

... snip a lot ..

> Bert, once again, I'm not suggesting the guidance is "wrong", but that it 
> is without substantiation.  It asserts a *requirement* that it seems to 
> have invented.
>
> RFC 3979 says what is to be in an RFC, not what isn't. The Checklist says 
> what isn't.
>

The proble we saw in the IESG (when we started ID_Checklist) was that we saw
A LOT OF I-Ds that requested publication and that DID HAVE SPECIFIC IPR
claims. So we wanted to make it clear to people that such is NOT TO BE DONE.

Just saying that RFC3979 text was to be used seemed not to get through!

> I did that:  Each and every assertion that says or implies anything more 
> than "it can be helpful to do this" needs to provide a narrow citation for 
> its basis.
>

I means "and so on". If there are more, pls point them out.

Bert

---

From: "Frank Ellermann" <[email-masked]>
Date: Mon, 11 Aug 2008 22:24:15 +0200

Dave Crocker wrote:
 
> This semantic distinction between upper and lower case that
> folks keep making is not supported by RFC 2119.

As far as I'm concerned it is perfectly supported by RFC 2119:

The capitalized forms of the keywords have the defined meaning.
Other forms can have a different meaning.  And where they have
the same meaning they should be capitalized to avoid confusion.

RFC 2119 itself uses lower case "may", "must", "must not", and
"should" in several places where the precise meaning of the
capitalized words, i.e. the keywords, would not match. 

It is of course allowed to avoid mixed uses, but not required.

> Case distinction for semantics also goes against normal rules

THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS OR IS 
SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND
THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, 
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY
THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY
RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS
FOR A PARTICULAR PURPOSE.

 Frank

---

From: Dave Crocker <[email-masked]>
Date: Wed, 13 Aug 2008 10:54:37 -0700

Bert Wijnen (IETF) wrote:
> ----- Original Message ----- From: "Dave Crocker" <[email-masked]>

Bert,

One of the likely reasons it didn't get through is that the IESG was inventing a
new rule.  A good rule, in my opinion, but a new one, since I think that
redundancy of specifications invites disparity.

To say that something must be in one place is very different from saying that it
may not (also) be in another.

So the IESG a) invented a more strict, formal rule than had existed before, and
b) only documented it in the Checklist.

Consider both of these points, please, in terms of your earlier claim:

>> I think that both of you (and some others) arwe looking at the ID_Checklist
>> too much as if it is part of our (rigid) process. Our processes are 
>> described in formally approved BCP documents.

While it is vastly more convenient, for the IESG, to have it take initiative and
decide on its own to make a more strict rule and issue it in a document that
does not go through public vetting, it isn't the way things are supposed to be
done in the IETF.

If the IESG is now responsible for inventing IETF policy, that ought to be
acknowledged and documented explicitly.

d/
-- 

   Dave Crocker

---

From: Dave Crocker <[email-masked]>
Date: Wed, 13 Aug 2008 10:55:05 -0700

Bert,

d/
-- 

   Dave Crocker

---

From: "Spencer Dawkins" <[email-masked]>
Date: Wed, 13 Aug 2008 13:13:46 -0500

Hi, Dave,

> does not go through public vetting, it isn't the way things are supposed 

Just to ring one of the changes here...

I'm actually OK with the process that Dave is not OK with, because I'm 
assuming that "public vetting" can also be retroactive - as long as the IESG 
announces rules publicly, I trust the community to point out problematic 
rules with great enthusiasm, and trust that the IESG will not go into 
"because we said so" mode when someone does point out that a new rule is 
problematic.

If my trust is misplaced, we have bigger problems than process changes, I 
think.

> acknowledged and documented explicitly.

One of the many contortions we went through on process change was trying to 
distinguish between policy and procedure. Our "current"(?) process BCPs 
don't make this distinction well.

I'm totally good with the IESG inventing IETF *procedures*, and that's what 
I think most of the ID checklist is. I would not be good with the IESG 
inventing IETF *policy* without community involvement, but that's not what I 
think is on the block.

Unannounced rules ("double SECRET probation") would be a problem, but I 
don't see anyone arguing in favor of undocumented late-surprise barriers.

Thanks,

Spencer

---

From: Robert Elz <[email-masked]>
Date: Thu, 14 Aug 2008 12:45:12 +0700

Date:        Wed, 13 Aug 2008 13:13:46 -0500
    From:        "Spencer Dawkins" <[email-masked]>
    Message-ID:  <[email-masked]>

  | I'm actually OK with the process that Dave is not OK with, because I'm 
  | assuming that "public vetting" can also be retroactive - as long as the
  | IESG announces rules publicly,

I'm not.

The big difference is what consensus is needed to achieve what.

In the cases of even mildly controversial changes, and isn't
everything, the question is whether it requires (rough) consensus
to make the change, or requires (rough) consensus to overturn the
change.

Personally, I believe we need to achieve some form of agreement
before any changes, and not fall into the trap of: "it's done,
and some (enough) people believe it is OK, so there's no consensus
to not do it."

For what it's worth, on the issue that has been under discussion,
I see no harm at all in having documents list IPR claims they're
aware of, so long as they don't pretend to claim that those are
the only possible IPR claims.   For example, in the early 90's,
it would have been entirely reasonable for a doc proposing use of
RSA public key technology to note the patent status, in the doc.

Requiring that such information be only on the web page is just
plain absurd.

So, for example, in this case, I wouldn't like anything to be
pretending to say that IPR claims are not allowed in docs, unless
we first achieve a consensus doc that says that.   Similarly
no claims that only the domain names in 2606 can be (even just
"usually" used as example in docs, unless we have a consensus doc
that says that.)

I have no problem with pointing out things that are common (or even
just seen more than once) errors, that no-one would rationally ever
do deliberately (like using ABNF, or anything else, and failing to
reference its definition) - that is, helping people remember to
check for the things that are easy to overlook.

But no new rules, for everything that isn't just noise, you need to
be able to cite the precise text in some standards track RFC, or BCP
that justifies exactly what you're planning on requiring.  No matter
how rational you, or anyone, believes the proposed rule is.

If that doesn't exist, it needs to be made to happen, first.

kre