Making RFC 2119 usage clearer

data-apis / array-api

RFC document, tooling and other content related to the array API standard

https://data-apis.github.io/array-api/latest/

MIT License

204 stars 42 forks source link

Making RFC 2119 usage clearer #801

Open asmeurer opened 2 months ago

asmeurer commented 2 months ago

I've

Added text to the end of the term definitions indicating that RFC 2119 is used.
Add a Sphinx extension that automatically bolds RFC 2119 words.

However, note that our usage of some of the RFC terms is not always consistent, especially for less used terms like "required", "may", "optional", and "recommended". So I would suggest that we either

Audit our use of these terms and fix them to align with RFC 2119 usage.
Add some text to clarify that certain terms are not used in accordance with RFC 2119.

For example, we use the term "optional" to refer to "optional parameters".

Fixes https://github.com/data-apis/array-api/issues/796

kgryte commented 2 months ago

Thanks, @asmeurer, for opening the draft PR. If we are going to try to auto-bold, this should only apply to the documents under "API Specification" and "Extensions". Much of the other content is narrative text and should not fall under RFC 2119.

kgryte commented 2 months ago

Also, swapping out the rst table for a list table seems unrelated to the changes described in the OP. That may be better left to a small separate PR to keep things clean.

kgryte commented 2 months ago

One last addendum: the only words we apply from RFC 2119 are must and should. I don't believe we have a written record of this, but those were the only two words which we sought to apply when originally considering RFC 2119 for use in the specification.

asmeurer commented 2 months ago

Also, swapping out the rst table for a list table seems unrelated to the changes described in the OP. That may be better left to a small separate PR to keep things clean.

There was a build error related to this table. I think adding the bold messed up the formatting of the table.

asmeurer commented 2 months ago

We should consider that if we say that we follow RFC 2119, then it would be better to follow it consistently, meaning in all documents, and also follow it completely, meaning the full set of words. If we don't do this, then we need to make it very clear that we aren't, but it would be clearer to people familiar with the RFC conventions if we did.

kgryte commented 2 months ago

We should consider that if we say that we follow RFC 2119, then it would be better to follow it consistently, meaning in all documents, and also follow it completely, meaning the full set of words. If we don't do this, then we need to make it very clear that we aren't, but it would be clearer to people familiar with the RFC conventions if we did.

We'll need to update quite a bit of copy then, as a fair amount of copy when discussing, e.g., the test suite or methodology or various design topics is not actually normative.

kgryte commented 2 months ago

I think, as a first pass, if we can limit to only the specification directories ("API Specification" and "Extensions"), that would be preferable. Otherwise, the non-normative content becomes confusing in its own right.