Subject: RFC2119 keywords in registration requirements

From: Julian Reschke <[email-masked]>
Date: Tue, 29 Oct 2013 21:22:21 +0100

So,

while getting IETF LC comment for httpbis, one reviewer complains about 
the use of RFC2119 in registration procedures, while another one 
complains about the lack of them in a different place.

Can we please clarify what's the right approach?

Best regards, Julian

/me thinks RFC2119 do not belong there.

---

From: "Bradner, Scott" <[email-masked]>
Date: Tue, 29 Oct 2013 20:29:12 +0000

seems to me to be completely reasonable to say MUST include the number of the RFC that describes 
the protocol being registered (for example)

Scott

On Oct 29, 2013, at 4:22 PM, Julian Reschke <[email-masked]> wrote:

> So,
> 
> while getting IETF LC comment for httpbis, one reviewer complains about the use of RFC2119 in registration procedures, while another one complains about the lack of them in a different place.
> 

Scott Bradner

Harvard University Information Technology
Innovation & Architecture
+1 617 495 3864
1350 Mass Ave., Room 760
Cambridge, MA 02138
www.harvard.edu/huit

---

From: Julian Reschke <[email-masked]>
Date: Tue, 29 Oct 2013 21:39:57 +0100

But then:

> 6. Guidance in the use of these Imperatives
>
>    Imperatives of the type defined in this memo must be used with care
>    and sparingly.  In particular, they MUST only be used where it is
>    actually required for interoperation or to limit behavior which has
>    potential for causing harm (e.g., limiting retransmisssions)  For
>    example, they must not be used to try to impose a particular method
>    on implementors where the method is not required for
>    interoperability.

To me this indicates that we should keep them out of registrations 
procedures.

(I also note that the "MUST" in the text I quoted shouldn't been used if 
the text followed its own advice :-).

Best regards, Julian

---

From: "Bradner, Scott" <[email-masked]>
Date: Tue, 29 Oct 2013 20:46:24 +0000

see rfc 2418 page 3 as well as RFC 2434 page 3 for an example of non-protocol uses of 2119 terms

fwiw - I have seen 2119 terms used in registration type RFCs for rather many years 
I think it is too late to unwind that clock

Scott

Scott Bradner

On Oct 29, 2013, at 4:39 PM, Julian Reschke <[email-masked]> wrote:

> To me this indicates that we should keep them out of registrations procedures.
> 
> (I also note that the "MUST" in the text I quoted shouldn't been used if the text followed its own advice :-).
> 
> Best regards, Julian

---

From: Julian Reschke <[email-masked]>
Date: Tue, 29 Oct 2013 21:48:56 +0100

> I think it is too late to unwind that clock

Well yes, I've seen that too.

But there *is* confusion about whether it's the right approach, and it 
would be really cool if there was some consistency with respect to this.

Best regards, Julian

---

From: "Bradner, Scott" <[email-masked]>
Date: Tue, 29 Oct 2013 20:50:01 +0000

yup

Scott 

On Oct 29, 2013, at 4:48 PM, Julian Reschke <[email-masked]> wrote:

> But there *is* confusion about whether it's the right approach, and it would be really cool if there was some consistency with respect to this.
> 
> Best regards, Julian
>

---

From: Paul Hoffman <[email-masked]>
Date: Tue, 29 Oct 2013 13:57:16 -0700

> the protocol being registered (for example)

It is also completely reasonable to say "needs to include" as well.

--Paul Hoffman

---

From: Barry Leiba <[email-masked]>
Date: Tue, 29 Oct 2013 17:06:46 -0400

First, I think we have to take the question of whether and when to use 2119
key words into the context of the document we're writing.  BCPs and
Informational documents can and do use them, but they use them in somewhat
different ways than Standards Track documents do, while still maintaining
the spirit of that text you quote from RFC 2119.

Second, I bristle when I see instructions to IANA in the form of "IANA MUST
[do this]."  We should not use 2119 key words in registration information
in that way.

Third, as instructions to registrants, I think it's absolutely fine to say
"you MUST [include this information," and "you SHOULD [include that
information]," and so on.  I think that respects the spirit of 2119, in
that things are more likely to interoperate if the documentation of
registered values is up to snuff.

Barry

---

From: [email-masked]
Date: Tue, 29 Oct 2013 16:27:55 -0700 (PDT)

> registered values is up to snuff.

FWIW, my experience with "running code" in this area is that this is a case
where the use of such directive does seem to help. (Assuming, of course, that
the registrant even bothers to read the procedure. Plain text capitalization is
not big enough to catch the attention of those who don't.)

				Ned

---

From: Ted Lemon <[email-masked]>
Date: Wed, 30 Oct 2013 03:04:10 +0000

> I think it is too late to unwind that clock

The fact that a mistake has been made many times is no excuse to keep making it.

---

From: Ted Lemon <[email-masked]>
Date: Wed, 30 Oct 2013 03:09:46 +0000

> It is also completely reasonable to say "needs to include" as well.

Blargh.   The word you want to use there is "must."   You're saying "needs to" because you mean "must" but are trying to say it a different way.   "Needs to" does not mean the same thing as "must."

There has been some discussion of this topic recently in the IESG, which (AFAIK) has not reached consensus on the following:

http://trac.tools.ietf.org/group/iesg/trac/wiki/Draft2119BoilerplateSuggestions

I'd be curious to hear reactions, bearing in mind that this is _not_ an IESG statement, at least at the moment.

---

From: "John Levine" <[email-masked]>
Date: 30 Oct 2013 03:42:48 -0000

>I'd be curious to hear reactions, bearing in mind that this is _not_ an IESG statement, at least at the moment.

Ugh.  Please say that in documents that reference 2119, the words have
the magic meaning when capitalized, and authors should* refrain from
using them uncapitalized anywhere else, to avoid confusion.  I've done
this for a while, and it's not very hard.

With respect to the original question, understanding that the horse is
now three or four counties away, I'd find it useful to use 2119 words
to describe things that readers implement, so that they will
interoperate with things that other readers have implemented.

For situations where you have to provide X, Y, and Z to register a
foo, that's different, since it won't fail by not interoperating,
it'll fail by the registry sending it back and asking for the missing
pieces.

R's,
John

* - this message does not reference 2119

---

From: Bjoern Hoehrmann <[email-masked]>
Date: Wed, 30 Oct 2013 12:11:46 +0100

>the text followed its own advice :-).

You think there is no potential for causing harm in inappropriately
using these imperatives? I rather think there is. And having proper
information in registries is quite often necessary to achieve inter-
operation.
-- 
Björn Höhrmann · mailto:[email-masked] · http://bjoern.hoehrmann.de
Am Badedeich 7 · Telefon: +49(0)160/4415681 · http://www.bjoernsworld.de
25899 Dagebüll · PGP Pub. KeyID: 0xA4357E78 · http://www.websitedev.de/

---

From: Julian Reschke <[email-masked]>
Date: Wed, 30 Oct 2013 13:18:09 +0100

> information in registries is quite often necessary to achieve inter-

Yes, but does using RFC2119 keywords here actually improve the 
registrations?

Anyway, I'll leave this to the IESG / our AD to make a choice.

Best regards, Julian

---

From: [email-masked]
Date: Wed, 30 Oct 2013 07:13:34 -0700 (PDT)

> Yes, but does using RFC2119 keywords here actually improve the

Of course it's impossible to be sure, but I can say that overall media type
registration quality has ticked up when we've released revised registration
procedures that make increased used of the RFC 2119 vocabulary.

> Anyway, I'll leave this to the IESG / our AD to make a choice.

Um, actually, this is not really up to the IESG. The most the IESG could
realistically say is that use of RFC 2119 language specifically is
inappropriate in current and future registration documents. That would leave
the door open to such documents specifying their own compliance vocabulary, and
I can assure you that is exactly what would happen for any document I'm
involved with. There's nothing magical about RFC 2119.

I suppose the IESG could then go so far as to say that such documents
should never use such vocabularies, but that seems rather unlikely.

				Ned