Being clearer about use of RFC 2119
Nessuno ha ancora preso questa issue.
Valutazione
- Difficoltà
- 5/5
- Tempo stimato
- Più di una settimana
- Idoneità per principianti
- 28/100
- Tipo di issue
- Documentazione
- Chiarezza
- Da chiarire
- Stato di attività
- Ferma
- Ambito
- documentation
Direzione di ricerca
Inizia con purpose_and_scope.html e RFC 2119, quindi esamina gli usi dei termini normativi nello standard, come «should», «must», «may» e «optional». Identifica i punti in cui la formulazione o la presentazione causa ambiguità e definisci il completamento come una spiegazione concordata di RFC 2119 e una terminologia o formattazione coerente in tutto lo standard.
Scritto dal modello di indicizzazione a partire dal testo della issue.
Descrizione
We use RFC 2119 for words like "should" and "must" in the standard. But many people are confused by this and think that "should" restrictions are actually "must" restrictions. This is most common for dtype restrictions, but it appears in other places in the standard as well.
We need to be clearer about this somehow. Some suggestions
-
Capitalize (as is the common convention) or bold these words (https://github.com/data-apis/array-api/issues/397)
-
Add a section somewhere making it clear that we are following the RFC. There is a link to the RFC at the bottom of https://data-apis.org/array-api/latest/purpose_and_scope.html but that's it. The RFC itself says:
Authors who follow these guidelines
should incorporate this phrase near the beginning of their document: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. -
The RFC also lists "required", "shall", "recommended", "may", and "optional". We should review our use of those terms to make sure they match the RFC.
-
We might be using "should" in places where we should be using "may" or "optional". From the RFC: SHOULD "means 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", but MAY "means that an item is truly optional". Things like data type restrictions are probably correct in using SHOULD, but things like indexing restrictions, like out-of-bounds slices" perhaps ought to use MAY, since the only reason they are limited is so the the standard can support libraries that can't implement them.
-
We should consider if there are other ways things could be made clearer, for instance, explicitly stating "other behavior is unspecified".
- Lingua principale
- Python
- Stelle
- 281
- Fork
- 52
- Metriche di merge delle PR
- Nessuna PR unita negli ultimi 30g
Guida per i contributori
Apri la guida per i contributori
Come iniziare
- Leggi tutta la issue e poi la guida ai contributi del progetto.
- Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
- Fai un fork del repository e lavora su un branch.
- Apri una pull request che faccia riferimento al numero della issue.
Altre issue di data-apis/array-api
-
Difficoltà 1/5 1-3 ore Idoneità per principianti 88/100
-
Difficoltà 2/5 1-3 ore Idoneità per principianti 70/100
-
Difficoltà 5/5 Più di una settimana Idoneità per principianti 35/100
-
Maintenance
-
Difficoltà 5/5 Più di una settimana Idoneità per principianti 25/100
Tutte le issue di data-apis/array-api
Issue simili
-
bug
Difficoltà 2/5 1-3 ore Idoneità per principianti 82/100
-
Difficoltà 2/5 1-3 ore Idoneità per principianti 88/100
use-agent-os/agent-os#3314 ·
-
Difficoltà 2/5 1-3 ore Idoneità per principianti 75/100
BasedHardware/omi#15662 · 1 commento ·
-
documentation help wanted
Difficoltà 2/5 1-3 ore Idoneità per principianti 90/100
-
Difficoltà 2/5 1-3 ore Idoneità per principianti 62/100
AiursoftWeb/AnduinOS-2#19 ·