Use RFC 2119 keywords consistently

[turt2live]

https://tools.ietf.org/html/rfc2119

See #701
See #682

[clokep]

I'm in favor of standardizing this. It offloads any terminology discussion to the IETF and matches what people generally expect when reading specifications.

[turt2live]

ftr, as this affects the "presentation layer" of the spec, I don't believe this requires an MSC. It's something we can do without actually changing the meaning of the specification.

[Johennes]

Shall MSCs attempt to use the RFC2119 language as well or should that be reserved to the spec itself?

[clokep]

Shall MSCs attempt to use the RFC2119 language as well or should that be reserved to the spec itself?

Personally I think it would be clearer, but I suspect we don't want to enforce it to keep the barrier of entry to writing MSCs fairly low.

[turt2live]

As the MSC gets closer to FCP I think it would be a fair requirement, though as clokep says: the barrier needs to be kept low.

[richvdh]

You've all said the same thing as me, but for posterity here's the GH comment I started writing 6 hours ago:

---

I think we've said that use of RFC2119 language is to be encouraged in MSCs, especially as an MSC gets closer to FCP.

In the past we've tended to be more relaxed about wording in MSCs "as long as the intention is clear" but that has had some unfortunate consequences.

A well-written MSC often has a bunch of informative sections around a normative proposal. Obviously, only the normative section needs formal RFC2119 keywords.

In other words: MSCs SHOULD express the proposal using RFC2119 keywords.

[Johennes]

For reference: In #1858 (comment) we discussed that the RFC keywords probably shouldn't be used in info or warning boxes because these usually should be descriptive rather than normative.

For what it's worth, this also matches the rules currently being used in gematik's extension of the spec. Below is an example of a normative requirement (delimited by A_... and <=) that uses keyword capitalization and an adjacent explanatory note ("Hinweis") that doesn't.

[HarHarLinks]

ftr, as this affects the "presentation layer" of the spec, I don't believe this requires an MSC. It's something we can do without actually changing the meaning of the specification.

While I agree with the comments made, I can not find that the spec defines its use of RFC 2119 language at all so far? If this is correct, I think that we would also need to do that, and I wonder if that change could affect the meaning of the spec somewhere.

as noted by richvdh

capitalised MUST/SHOULD/MAY have always meant to just use the RFC2119 meaning: if that's never been written down, that's just an omission

[turt2live]

to clarify: the spec uses RFC 2119, but doesn't document that. PRs are very much welcome for adding that block of text.

This issue is to ensure the keywords are used where they're supposed to already be used. The history is a bit unclear on this front, but that's the state of affairs :D