Loading ...
Sorry, an error occurred while loading the content.

Re: MUST-MAY-SHOULD (MMS) audit...

Expand Messages
  • Koen Holtman
    ... I managed to go through Jeff s audit and get halfway through Scott s audit so far. Here are some comments. - Jim: I looked at your corrections to their
    Message 1 of 5 , Jul 29, 1998
    • 0 Attachment
      Jim Gettys:
      >
      >
      >There has been no comments on Jeff and Scott's massive audit. I suspect
      >everyone who has looked at them has had their eyes glaze over; I know
      >I have.

      I managed to go through Jeff's audit and get halfway through Scott's
      audit so far. Here are some comments.

      - Jim: I looked at your corrections to their corrections and they seem
      correct to me.

      - Generic editorial warning: I seem to remember (though I don't know
      where I learnt it) that notes in an RFC are always non-normative by
      convention, so there should be no MMS terminology in them. Jeff's
      corrections seem to take the opposite view, whereas Scott makes
      judgment calls on a note by note basis. I don't have a direct
      connection to any RFC repository now so I can't check whether there
      are generic conventions with respect to notes, but somebody should
      check this.

      - MMS 025: I am not sure if Jeff is right in his assumption as to what
      the term "common form" is supposed to mean. Maybe "common form"
      means `not extended over multiple lines' here.

      - MMS 117: The musts in the two items define conditions to be met for
      a MAY to apply, so they should be lowercase (or preferably
      rephrased), not uppercase.

      - MMS 125: in the definition of "invalidate an entity", the two
      shoulds are defining a term, they are are not keywords specifying a
      requirement, so they should be rephrased, e.g. from `should' to
      `will'. [This is a bit of a judgment call: I believe a phrase like

      "MUST cause a cache to invalidate the entity"

      (which is used in the paragraph following the definition) was meant
      to expand to

      "MUST cause a cache to either remove all instances or mark them
      as invalid"

      and not to

      "MUST cause a cache to apply the rule that it SHOULD either
      remove all instances or mark them as invalid"

      which is only a SHOULD level requirement at the core.]

      Koen.
    • Jeffrey Mogul
      Koen Holtman writes: Generic editorial warning: I seem to remember (though I don t know where I learnt it) that notes in an RFC are always non-normative by
      Message 2 of 5 , Aug 6, 1998
      • 0 Attachment
        Koen Holtman writes:

        Generic editorial warning: I seem to remember (though I don't know
        where I learnt it) that notes in an RFC are always non-normative by
        convention, so there should be no MMS terminology in them. Jeff's
        corrections seem to take the opposite view, whereas Scott makes
        judgment calls on a note by note basis. I don't have a direct
        connection to any RFC repository now so I can't check whether there
        are generic conventions with respect to notes, but somebody should
        check this.

        It has indeed been our policy to avoid normative statements in
        "Notes". I basically followed this policy, although there are
        a few places where it seemed like a secondary priority. Also,
        there are place where it's not clear whether a paragraph is
        really a "Note" or not. In almost every case, I did point out
        that the Note in question contained apparently normative
        language. I didn't want to delete requirements simply because
        they appeared in Notes, but I also didn't want to spend the
        time to rewrite large chunks of text.

        MMS_AUDIT_ITEM_008:
        The paragraph starts with the word "Note", but it's not
        indented like the other "Notes". The content is clearly
        normative, but it might just be restating other normative
        language.

        MMS_AUDIT_ITEM_010:
        An actual "Note"; I changed a "should" (ambiguous) to
        an "ought" (non-normative).

        issue MMS_AUDIT_ITEM_013
        I pointed out that this is a case where normative
        language appears in a Note, and it's not clear whether
        it was meant to be normative or not. Someone with
        an interest should comment on the substance, not just
        the form.

        issue MMS_AUDIT_ITEM_018:
        Definitely in a Note, but also possibly an
        interoperability requirement. Again, review by
        a qualified person would be helpful.

        issue MMS_AUDIT_ITEM_024:
        A Note that restates a normative requirement.

        issue MMS_AUDIT_ITEM_062:
        I removed a "should not" from a Note.

        issue MMS_AUDIT_ITEM_065:
        issue MMS_AUDIT_ITEM_066:
        Notes that contain what appear to be normative
        requirements (aids to interoperability)

        issue MMS_AUDIT_ITEM_075:
        issue MMS_AUDIT_ITEM_104:
        I removed two "mays" from each of these Notes.

        In other words, I'm not sure why Koen thinks that I "took an
        opposite view" rather than making "judgement calls on a note
        by note basis." Nevertheless, if we really want to be consistent
        on this formality, then someone should spend some effort
        splitting some of these Notes into normative and true-Note parts.

        MMS 025: I am not sure if Jeff is right in his assumption as to
        what the term "common form" is supposed to mean. Maybe "common
        form" means `not extended over multiple lines' here.

        As I wrote, we don't have a definition for "common form" in general, so
        we can argue until the end of the millenium about what this paragraph
        actually means. The right solution is to either define a general
        "common form", or make it clear which specific "common forms" are
        intended. I tried to do the latter.

        MMS 117: The musts in the two items define conditions to be met for
        a MAY to apply, so they should be lowercase (or preferably
        rephrased), not uppercase.

        I think your logic is faulty. An analogy: in this sentence,

        You MAY pilot an airliner, but in order to do so, you
        MUST have a pilot's license.

        it is pretty clear that the phrase "you MUST have a pilot's
        license" does not apply to everyone; it only applies to pilots,
        but then it is an "absolute requirement of the specification"
        (to quote from RFC2119). I think you are arguing that one should
        instead say

        You MAY pilot an airliner, but in order to do so, you
        ought to have a pilot's license.

        which has a very different meaning (and one that would convince
        me to travel by train).

        MMS 125: in the definition of "invalidate an entity", the two
        shoulds are defining a term, they are are not keywords specifying a
        requirement, so they should be rephrased, e.g. from `should' to
        `will'.

        I believe that this language basically defines a "subroutine"
        rather than simply a "term". It's giving a specific meaning to a
        verb-phrase when that phrase is used in this specification.

        Using a word like "will" sidesteps the issue of whether this
        is a conditional or unconditional requirement. Which points
        out that since I didn't look at the following text as carefully
        as you have, where it says

        Some HTTP methods MUST cause a cache to invalidate an entity.

        it seems (by my argument re: MMS 117) that these SHOULDS really
        need to be MUSTs (or that the latter MUST has to be a SHOULD).

        Otherwise, we're in the position of saying that doing something
        is an absolute requirement of the specification, but doing it
        according to our definition is only a conditional requirement.
        I.e., the implementor has to do something, but is allowed (for
        good cause) to ignore our specification of what that something is.
        So this is probably a bug in the language, and needs to be resolved.

        -Jeff
      • Koen Holtman
        ... [....] ... Usually this apparently normative language merely explains or restates actual normative language in the main text. I recall that at least one
        Message 3 of 5 , Aug 10, 1998
        • 0 Attachment
          Jeffrey Mogul:
          >
          [....]
          > In almost every case, I did point out
          >that the Note in question contained apparently normative
          >language.

          Usually this apparently normative language merely explains or restates
          actual normative language in the main text. I recall that at least
          one editor (Roy?) had the policy of stating all normative requirements
          exactly once, in order to reduce the risks of
          self-contradictions. This policy leads to the editorial device of
          using a note whenever you want to explain or restate requirements
          already stated once.

          > I didn't want to delete requirements simply because
          >they appeared in Notes, but I also didn't want to spend the
          >time to rewrite large chunks of text.

          Whenever reviewing a note in the past I have always kept in mind that
          it could not contain a normative requirement, so I am pretty sure that
          the set of the requirements in the draft won't change if we leave all
          notes non-normative.

          [...]
          >In other words, I'm not sure why Koen thinks that I "took an
          >opposite view" rather than making "judgement calls on a note
          >by note basis."

          Just an overall impression I got. I may have missed some exceptions.

          >Nevertheless, if we really want to be consistent
          >on this formality, then someone should spend some effort
          >splitting some of these Notes into normative and true-Note parts.

          I believe being consistent on this is very necessary, so I would like
          one of the editors to take the effort.

          > MMS 025: I am not sure if Jeff is right in his assumption as to
          > what the term "common form" is supposed to mean. Maybe "common
          > form" means `not extended over multiple lines' here.
          >
          >As I wrote, we don't have a definition for "common form" in general, so
          >we can argue until the end of the millenium about what this paragraph
          >actually means.

          Hmm, I was hoping that the original author of that sentence, or maybe
          someone knowledgeable of email/news header terminology, would come
          forward and clarify.

          [...]
          > MMS 117: The musts in the two items define conditions to be met for
          > a MAY to apply, so they should be lowercase (or preferably
          > rephrased), not uppercase.
          >
          >I think your logic is faulty. An analogy: in this sentence,
          >
          > You MAY pilot an airliner, but in order to do so, you
          > MUST have a pilot's license.
          >
          >it is pretty clear that the phrase "you MUST have a pilot's
          >license" does not apply to everyone; it only applies to pilots,
          >but then it is an "absolute requirement of the specification"
          >(to quote from RFC2119). I think you are arguing that one should
          >instead say
          >
          > You MAY pilot an airliner, but in order to do so, you
          > ought to have a pilot's license.
          >
          >which has a very different meaning (and one that would convince
          >me to travel by train).

          No, I am arguing that you should say

          If you have a pilot's license you MAY pilot an airliner.

          which avoids the whole problem. Compare this to the following piece
          of text from the spec:

          If the response includes the "must-revalidate" Cache-Control
          directive, the cache MAY use that response in replying to a
          subsequent request.

          The logical structure of such things is

          if 'condition' then ( 'subject' MAY 'action' )

          My sense of grammar tells me that the 'condition' part, if it includes
          the verbs must, may, or should, should never have these capitialised
          as keywords, because in the condition parts these verbs do not signal
          an actual requirement on a subject in the sense of rfc2219. I got
          most of my grammatical intuition from reading Latin and writing C, so
          I may be wrong, but I don't think so.

          > MMS 125: in the definition of "invalidate an entity", the two
          > shoulds are defining a term, they are are not keywords specifying a
          > requirement, so they should be rephrased, e.g. from `should' to
          > `will'.
          >
          >I believe that this language basically defines a "subroutine"
          >rather than simply a "term". It's giving a specific meaning to a
          >verb-phrase when that phrase is used in this specification.

          Well, I agree that this could be a "subroutine" too, but as you also
          note, this does not solve the problem in the spec, so we should fix
          this one way or the other.

          >-Jeff

          Koen.
        • Roy T. Fielding
          ... The editorial policy of using a note to explain non-normative design decisions comes from the MIME specs (or at least that s where I got it from).
          Message 4 of 5 , Aug 11, 1998
          • 0 Attachment
            >Usually this apparently normative language merely explains or restates
            >actual normative language in the main text. I recall that at least
            >one editor (Roy?) had the policy of stating all normative requirements
            >exactly once, in order to reduce the risks of
            >self-contradictions. This policy leads to the editorial device of
            >using a note whenever you want to explain or restate requirements
            >already stated once.

            The editorial policy of using a note to explain non-normative design
            decisions comes from the MIME specs (or at least that's where I got
            it from). Anything that is normative should just be changed to a
            non-note.

            >> MMS 025: I am not sure if Jeff is right in his assumption as to
            >> what the term "common form" is supposed to mean. Maybe "common
            >> form" means `not extended over multiple lines' here.
            >>
            >>As I wrote, we don't have a definition for "common form" in general, so
            >>we can argue until the end of the millenium about what this paragraph
            >>actually means.

            When I originally wrote "common form" it wasn't associated with a
            requirement -- it was implementation advice. "common form" means
            just that -- whatever is commonly used by other applications at the
            time of implementation, which might have changed over time.

            If you want to spell it out, I'd say the current common form is

            fieldname: fieldvalue

            with no extra space or line continuation folding.

            ....Roy
          Your message has been successfully submitted and would be delivered to recipients shortly.