Re: #271: SHOULD review in p4

On 2012-06-22 03:44, Mark Nottingham wrote:
>
> As per <http://trac.tools.ietf.org/wg/httpbis/trac/ticket/271>, I'm reviewing our use of SHOULD in the documents; here I also pick on a few MAYs. Where I find issues, I've flagged with EDITORIAL or DESIGN as seems appropriate (I won't open issues for the design ones until we discuss; the editorial ones are considered attached to #271).
>
> 2.1
>
> "However, if a resource has distinct representations that differ only in their metadata, such as might occur with content negotiation over media types that happen to share the same data format, then a server SHOULD incorporate additional information in the validator to distinguish those representations and avoid confusing cache behavior."
>
> Seems OK, but not really testable.
> EDITORIAL - change "a server" to "the origin server"

OK.

> "A weak entity-tag SHOULD change whenever the origin server considers prior representations to be unacceptable as a substitute for the current representation. In other words, a weak entity-tag SHOULD change whenever the origin server wants caches to invalidate old responses."
>
> First one is OK, but not testable.
>
> EDITORIAL - change first one to "An origin server SHOULD change a weak entity-tag whenever it considers..."
> EDITORIAL - the second one should probably change to an "ought to", otherwise we're repeating ourselves.

OK.

> ...
> "HTTP/1.0 clients and caches might ignore entity-tags. Generally, last-modified values received or used by these systems will support transparent and efficient caching, and so HTTP/1.1 origin servers SHOULD provide Last-Modified values. In those rare cases where the use of a Last-Modified value as a validator by an HTTP/1.0 system could result in a serious problem, then HTTP/1.1 origin servers SHOULD NOT provide one."
>
> EDITORIAL - change SHOULD to "still ought to". (we're repeating ourselves)

Ack (note this was a lowercase should).

> DESIGN - What are the "rare cases" being talked about here, and how are servers supposed to detect them?

Good question. We may want to drop this.

> 3.1
>
> "The "If-Match" header field MAY be used to make a request method conditional on the current existence or value of an entity-tag for one or more representations of the target resource."
>
> EDITORIAL - change MAY to "can"

Absolutely.

> 3.2
>
> "The "If-None-Match" header field MAY be used to make a request method conditional on not matching any of the current entity-tag values for representations of the target resource."
>
> EDITORIAL - change MAY to "can"

Absolutely.

> "If-None-Match MAY also be used with a value of "*" to prevent an unsafe request method (e.g., PUT) from inadvertently modifying an existing representation of the target resource when the client believes that the resource does not have a current representation."
>
> EDITORIAL - change MAY to "can"

Absolutely.

> ...
> 3.3
>
> "The "If-Modified-Since" header field MAY be used to make a request method conditional by modification date: if the selected representation has not been modified since the time specified in this field, then do not perform the request method; instead, respond as detailed below."
>
> EDITORIAL - change MAY to "can"

Absolutely.

> ...
> 3.4
>
> "The "If-Unmodified-Since" header field MAY be used to make a request method conditional by modification date: if the selected representation has been modified since the time specified in this field, then the server must not perform the requested operation and must instead respond with the 412 (Precondition Failed) status code."
>
> EDITORIAL - change MAY to "can"

Absolutely.

> "If the selected representation has not been modified since the time specified in this field, the server SHOULD perform the request method as if the If-Unmodified-Since header field were not present."
>
> OK (but why not MUST here?)

Dunno, it's a lowercase "should" in RFC 2068. 
(<http://tools.ietf.org/html/rfc2068#section-14.28>)

> "If the request normally (i.e., without the If-Unmodified-Since header field) would result in anything other than a 2xx or 412 status code, the If-Unmodified-Since header field SHOULD be ignored."
>
> OK (but why not MUST here?)

Good question.

> EDITORIAL: "If the request.." -> "If a request..."
> EDITORIAL: the language around ignoring headers / "were not present" here is needlessly divergent.

I changed the second instance to:

    If a request normally (i.e., in absence of the If-Unmodified-Since
    header field) would result in anything other than a 2xx or 412 status
    code, the If-Unmodified-Since header field SHOULD be ignored.

> ...

Applied with <http://trac.tools.ietf.org/wg/httpbis/trac/changeset/1691> 
(except for the open issues).

Best regards, Julian

Received on Saturday, 23 June 2012 11:29:11 UTC