Skip to contentSkip to conversation

introduction: Clarify RFC 2119 key words usage

PATCH In review Parav Pandit 4 participants 5 messages Jun 27, 2025

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 introduction: Clarify RFC 2119 key words usage

RFC 2119 key words should be used in Requirements and Conformance sections; these key words to be avoided in rest of the sections.

The motivations for such clarity are:

1. To clarify the intent:
These key words carry precise semantic weight. When a spec says MUST, it means compliance is not optional. Using such terms in general or explanatory text risks misinterpreting guidance as a requirement.

2. Avoiding Ambiguity:
If normative language is used in non-normative (informative) sections, it becomes unclear whether the reader is required to follow it or if it's just background or suggestion.

3. Informative sections explain context, rationale, or examples. Normative sections define rules. Mixing the two muddies the structure and weakens the authority of the normative part.

---
 introduction.tex | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)
introduction.tex +4 -1
index 80aa67a..4e7ab59 100644
@@ -196,7 +196,10 @@ \section{Terminology}\label{Terminology}
 ``SHOULD'', ``SHOULD NOT'', ``RECOMMENDED'', ``NOT RECOMMENDED'', ``MAY'', and
 ``OPTIONAL'' in this document are to be interpreted as described in
 \hyperref[intro:rfc2119]{[RFC2119]} and \hyperref[intro:rfc8174]{[RFC8174]} when,
-and only when, they appear in all capitals, as shown here.
+and only when, they appear in all capitals, as shown here. The use of these
+key words is recommended in the Requirements and Conformance sections and should
+be avoided in other sections.
+
 \subsection{Legacy Interface: Terminology}\label{intro:Legacy
 Interface: Terminology}
 
Signature · 1 line
2.34.1
Reviewed-by on v1 1/1
#1 lore raw
Quoted 19 lines · Parav Pandit

RFC 2119 key words should be used in Requirements and Conformance sections; these key words to be avoided in rest of the sections.

The motivations for such clarity are:

1. To clarify the intent:
These key words carry precise semantic weight. When a spec says MUST, it means compliance is not optional. Using such terms in general or explanatory text risks misinterpreting guidance as a requirement.

2. Avoiding Ambiguity:
If normative language is used in non-normative (informative) sections, it becomes unclear whether the reader is required to follow it or if it's just background or suggestion.

3. Informative sections explain context, rationale, or examples. Normative sections define rules. Mixing the two muddies the structure and weakens the authority of the normative part.

Quoted 5 lines
---
 introduction.tex | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)
Reviewed-by on v1 1/1
#2 lore raw
In reply to Parav Pandit
Quoted 19 lines · Parav Pandit

RFC 2119 key words should be used in Requirements and Conformance sections; these key words to be avoided in rest of the sections.

The motivations for such clarity are:

1. To clarify the intent:
These key words carry precise semantic weight. When a spec says MUST, it means compliance is not optional. Using such terms in general or explanatory text risks misinterpreting guidance as a requirement.

2. Avoiding Ambiguity:
If normative language is used in non-normative (informative) sections, it becomes unclear whether the reader is required to follow it or if it's just background or suggestion.

3. Informative sections explain context, rationale, or examples. Normative sections define rules. Mixing the two muddies the structure and weakens the authority of the normative part.

Quoted 5 lines
---
 introduction.tex | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)
#3 lore raw
In reply to Parav Pandit
Quoted 30 lines · Parav Pandit

RFC 2119 key words should be used in Requirements and Conformance sections; these key words to be avoided in rest of the sections.

The motivations for such clarity are:

1. To clarify the intent:
These key words carry precise semantic weight. When a spec says MUST, it means compliance is not optional. Using such terms in general or explanatory text risks misinterpreting guidance as a requirement.

2. Avoiding Ambiguity:
If normative language is used in non-normative (informative) sections, it becomes unclear whether the reader is required to follow it or if it's just background or suggestion.

3. Informative sections explain context, rationale, or examples. Normative sections define rules. Mixing the two muddies the structure and weakens the authority of the normative part.

---
 introduction.tex | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)
introduction.tex +0 -0
index 80aa67a..4e7ab59 100644

introduction.tex \section{Terminology}\label{Terminology} · line 204

Quoted 10 lines
introduction.tex +4 -1
@@ -196,7 +196,10 @@ \section{Terminology}\label{Terminology}
 ``SHOULD'', ``SHOULD NOT'', ``RECOMMENDED'', ``NOT RECOMMENDED'', ``MAY'', and
 ``OPTIONAL'' in this document are to be interpreted as described in
 \hyperref[intro:rfc2119]{[RFC2119]} and \hyperref[intro:rfc8174]{[RFC8174]} when,
-and only when, they appear in all capitals, as shown here.
+and only when, they appear in all capitals, as shown here. The use of these
+key words is recommended in the Requirements and Conformance sections and should
+be avoided in other sections.
+
 \subsection{Legacy Interface: Terminology}\label{intro:Legacy
 Interface: Terminology}

The spec is for the reader, who has nothing to gain from this and will just be confused. If you want to start a document with suggestions for contributors, that might be a great idea, and this might belong there.

Quoted 2 lines
Signature · 1 line
2.34.1
#4 lore raw
Quoted 40 lines

From: Michael S. Tsirkin <[email protected]>
Sent: 27 June 2025 05:23 PM

Quoted 31 lines · Parav Pandit

RFC 2119 key words should be used in Requirements and Conformance sections; these key words to be avoided in rest of the sections.

The motivations for such clarity are:

1. To clarify the intent:
These key words carry precise semantic weight. When a spec says MUST, it means compliance is not optional. Using such terms in general or explanatory text risks misinterpreting guidance as a requirement.

2. Avoiding Ambiguity:
If normative language is used in non-normative (informative) sections, it becomes unclear whether the reader is required to follow it or if it's just background or suggestion.

3. Informative sections explain context, rationale, or examples. Normative sections define rules. Mixing the two muddies the structure and weakens the authority of the normative part.

---
 introduction.tex | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)
introduction.tex index renamed from introduction.tex +0 -0

80aa67a..4e7ab59 100644

introduction.tex +0 -0
@@ -196,7 +196,10 @@ \section{Terminology}\label{Terminology}
 ``SHOULD'', ``SHOULD NOT'', ``RECOMMENDED'', ``NOT RECOMMENDED'',
Quoted 3 lines

``MAY'', and ``OPTIONAL'' in this document are to be interpreted as described in \hyperref[intro:rfc2119]{[RFC2119]} and \hyperref[intro:rfc8174]{[RFC8174]} when, -and only when, they appear in

all capitals, as shown here.

Quoted 14 lines

introduction.tex \section{Terminology}\label{Terminology} · line 204

Quoted 6 lines
introduction.tex +4 -0
+and only when, they appear in all capitals, as shown here. The use of
+these key words is recommended in the Requirements and Conformance
+sections and should be avoided in other sections.
+
 \subsection{Legacy Interface: Terminology}\label{intro:Legacy
 Interface: Terminology}

The spec is for the reader, who has nothing to gain from this and will just be confused. If you want to start a document with suggestions for contributors, that might be a great idea, and this might belong there.

Quoted 2 lines

--
2.34.1

Yeah, that contributor's doc is a good idea.
We already have one.
I will just extend https://github.com/oasis-tcs/virtio-spec/blob/master/CONTRIBUTING.md