Introduce RFC 2119 keywords MUST, SHOULD, MAY etc. in the documentation, where appropriate

I would really appreciate it if we can clearly differentiate between hard requirements (e.g. “You must do it this way or it will not work or seriously break”) and recommendations (“It is recommended to do it that way but will still work if you not”).

I suggest to use the keywords MUST, MUST NOT, SHOULD, SHOULD NOT etc. as specified in https://www.ietf.org/rfc/rfc2119.txt:

  1. MUST This word, or the terms “REQUIRED” or “SHALL”, mean that the
    definition is an absolute requirement of the specification.
  1. MUST NOT This phrase, or the phrase “SHALL NOT”, mean that the
    definition is an absolute prohibition of the specification.
  1. SHOULD This word, or the adjective “RECOMMENDED”, mean that there
    may exist valid reasons in particular circumstances to ignore a
    particular item, but the full implications must be understood and
    carefully weighed before choosing a different course.
  1. SHOULD NOT This phrase, or the phrase “NOT RECOMMENDED” mean that
    there may exist valid reasons in particular circumstances when the
    particular behavior is acceptable or even useful, but the full
    implications should be understood and the case carefully weighed
    before implementing any behavior described with this label.
  1. etc. see https://www.ietf.org/rfc/rfc2119.txt

A short note could be added to the documentation to explain this and link to the RFC.

Texts that adhere to these conventions often use these keywords in captital letters to make it clear the words are not used as normally, but they have a special meaning as specified in the RFC, e.g.

“The extension key MUST be unique worldwide if you publish your extension (on extensions.typo3.org).”

“The extension key MAY contain underscores.”

Language can be inherently vague and ambigous. Things like these make it much clearer. We do not need to do this excessively but I would like to suggest it in places that are currently vague and ambiguous. Especially where things will break if you do not follow the rules (which are sometimes specified as “conventions”, which does not really help to make it clear).

Examples, that might be improved by using these keywords:

4 Likes

As you probably know, the PSRs use this as well, e.g.

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 described in RFC 2119.

Loving it! Please go ahead.

1 Like

Making clear statements is a very god idea!

1 Like