[PATCH] introduction: Clarify RFC 2119 key words usage

[PATCH] introduction: Clarify RFC 2119 key words usage

[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.

Fixes: https://github.com/oasis-tcs/virtio-spec/issues/230
Signed-off-by: Parav Pandit <parav@nvidia.com>
---
 introduction.tex | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/introduction.tex b/introduction.tex
index 80aa67a..4e7ab59 100644
--- a/introduction.tex
+++ b/introduction.tex
@@ -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}
 
-- 
2.34.1

Re: [PATCH] introduction: Clarify RFC 2119 key words usage

[Matias Ezequiel Vara Larsen]

On Fri, Jun 27, 2025 at 07:19:54AM +0300, Parav Pandit wrote:
> 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.
> 
> Fixes: https://github.com/oasis-tcs/virtio-spec/issues/230
> Signed-off-by: Parav Pandit <parav@nvidia.com>
> ---
>  introduction.tex | 5 ++++-
>  1 file changed, 4 insertions(+), 1 deletion(-)


Reviewed-by: Matias Ezequiel Vara Larsen <mvaralar@redhat.com>

Re: [PATCH] introduction: Clarify RFC 2119 key words usage

[Cornelia Huck]

On Fri, Jun 27 2025, Parav Pandit <parav@nvidia.com> wrote:

> 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.
>
> Fixes: https://github.com/oasis-tcs/virtio-spec/issues/230
> Signed-off-by: Parav Pandit <parav@nvidia.com>
> ---
>  introduction.tex | 5 ++++-
>  1 file changed, 4 insertions(+), 1 deletion(-)

Reviewed-by: Cornelia Huck <cohuck@redhat.com>

Re: [PATCH] introduction: Clarify RFC 2119 key words usage

[Michael S. Tsirkin]

On Fri, Jun 27, 2025 at 07:19:54AM +0300, Parav Pandit wrote:
> 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.
> 
> Fixes: https://github.com/oasis-tcs/virtio-spec/issues/230
> Signed-off-by: Parav Pandit <parav@nvidia.com>
> ---
>  introduction.tex | 5 ++++-
>  1 file changed, 4 insertions(+), 1 deletion(-)
> 
> diff --git a/introduction.tex b/introduction.tex
> index 80aa67a..4e7ab59 100644
> --- a/introduction.tex
> +++ b/introduction.tex
> @@ -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.

> -- 
> 2.34.1

RE: [PATCH] introduction: Clarify RFC 2119 key words usage

[Parav Pandit]

> From: Michael S. Tsirkin <mst@redhat.com>
> Sent: 27 June 2025 05:23 PM
> 
> On Fri, Jun 27, 2025 at 07:19:54AM +0300, Parav Pandit wrote:
> > 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.
> >
> > Fixes: https://github.com/oasis-tcs/virtio-spec/issues/230
> > Signed-off-by: Parav Pandit <parav@nvidia.com>
> > ---
> >  introduction.tex | 5 ++++-
> >  1 file changed, 4 insertions(+), 1 deletion(-)
> >
> > diff --git a/introduction.tex b/introduction.tex index
> > 80aa67a..4e7ab59 100644
> > --- a/introduction.tex
> > +++ b/introduction.tex
> > @@ -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.
> 
> > --
> > 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