Subject: draft-ietf-httpbis-http2-16: use of "optional"

From: Julian Reschke <[email-masked]>
Date: Tue, 13 Jan 2015 17:30:38 +0100

Hi there,

(now getting to the nitpicking...)

in several cases, the spec says "optional".

Some people in the IETF believe it's equivalent to "OPTIONAL", while 
others disagree. I recommend to uppercase "optional" where it's supposed 
to express a requirement, and to choose a different where it's not.

Best regards, Julian

---

From: Martin Thomson <[email-masked]>
Date: Tue, 13 Jan 2015 10:10:38 -0800

On 13 January 2015 at 08:30, Julian Reschke <[email-masked]> wrote:
> Some people in the IETF believe it's equivalent to "OPTIONAL", while others
> disagree. I recommend to uppercase "optional" where it's supposed to express
> a requirement, and to choose a different where it's not.

Or do this:

          The key words "MUST", "MUST NOT", "REQUIRED", "SHALL",
"SHALL NOT", "SHOULD", "SHOULD
-          NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document
are to be interpreted as
+          NOT", "RECOMMENDED", and "MAY" in this document are to be
interpreted as
         described in <xref target="RFC2119">RFC 2119</xref>.

Or better yet:

-          The key words "MUST", "MUST NOT", "REQUIRED", "SHALL",
"SHALL NOT", "SHOULD", "SHOULD
-          NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document
are to be interpreted as
+          The key words "MUST", "MUST NOT", "SHOULD", and "MAY" in
this document are to be interpreted as
         described in <xref target="RFC2119">RFC 2119</xref>.

We don't use the full 2119 repertoire, and we shouldn't need to.

---

From: Julian Reschke <[email-masked]>
Date: Tue, 13 Jan 2015 19:20:09 +0100

> We don't use the full 2119 repertoire, and we shouldn't need to.

That'll make IDNITS unhappy :-(

Best regards, Julian

---

From: Martin Thomson <[email-masked]>
Date: Tue, 13 Jan 2015 10:21:43 -0800

> That'll make IDNITS unhappy :-(

I'm sure that if that is the only drawback, I can live with that.

---

From: Bjoern Hoehrmann <[email-masked]>
Date: Tue, 13 Jan 2015 22:20:44 +0100

>         described in <xref target="RFC2119">RFC 2119</xref>.

I think omitting some keywords from the boilerplate is a bad and risky
practise that does not really remove the problem that using "optional"
invites confusion.
-- 
Björn Höhrmann · mailto:[email-masked] · http://bjoern.hoehrmann.de
D-10243 Berlin · PGP Pub. KeyID: 0xA4357E78 · http://www.bjoernsworld.de
 Available for hire in Berlin (early 2015)  · http://www.websitedev.de/

---

From: Tony Hansen <[email-masked]>
Date: Tue, 13 Jan 2015 17:22:30 -0500

On 1/13/15 1:10 PM, Martin Thomson wrote:
> ...

-100

I think that would cause MORE confusion and congnitive dissonance than 
the alternatives.

     Tony Hansen

---

From: Martin Thomson <[email-masked]>
Date: Sun, 18 Jan 2015 13:11:13 -0800

> in several cases, the spec says "optional".

Tracking as https://github.com/http2/http2-spec/issues/681