Document the RFC 2119 keyword rule (attribution lost in docs rebuild) and its clarification update RFC 8174

Aperta Adatta ai principianti
  • Qualcosa non va?
#2,200 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 2 giorni

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
1/5
Tempo stimato
1-3 ore
Idoneità per principianti
88/100
Tipo di issue
Documentazione
Chiarezza
Specificata chiaramente
Stato di attività
Attiva
Ambito
documentation

Direzione di ricerca

Leggi docs-lab/README.md e i due file citati: docs-lab/reference/schemas/spec-driven/index.md vicino alla riga 218 e docs-lab/reference/glossary.md vicino alla riga 28. Confronta le loro indicazioni con i riferimenti agli RFC in openspec/specs/cli-validate/spec.md e le vecchie citazioni in docs/. Aggiungi l’attribuzione a RFC 2119 e RFC 8174 e spiega che i significati definiti si applicano alle parole chiave scritte interamente in maiuscolo; il lavoro è concluso quando questo è chiaro in entrambe le pagine di documentazione attuali.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

documentation needs-triage
Where

https://openspec.dev/docs/schemas/spec-driven, https://openspec.dev/docs/glossary

What is wrong or missing

The Issue is that the live docs pages teach keyword usage but cite no source for the keywords. Verified at current main (2026-11-02, 2bd5bc3):

Both RFC 2119 and Updated RFC 8174 Should be Documented

To align to cli-validate spec.md, as well as defining a stronger specification matching IETF documents, which openspec/specs already follows.

The abstract of RFC 2119 originally said its key words "are often capitalized" — which RFC 8174 §1 notes "has caused confusion about how to interpret non-capitalized words such as 'must' and 'should'". RFC 8174 §2 (BCP 14, Updates: 2119) replaced that clause — in its === NEW === block:

In many IETF documents, several words, when they are in all capitals as shown below, are used to signify the requirements in the specification. These capitalized words can bring significant clarity and consistency to documents because their meanings are well defined.

In short: RFC 8174 clarifies that words have the meanings specified in RFC 2119 only when they are in all capitals, thus - should not retry is descriptive text; - SHOULD NOT retry makes it a specification.

What it should say instead
  1. docs-lab/reference/schemas/spec-driven/index.md#L218 (line 218): change the guidance line to cite the standard — e.g. "Use the RFC 2119 keywords (as updated by RFC 8174, BCP 14) for normative requirements; they carry their defined meaning only in ALL CAPS — lowercase should/may are ordinary prose."
  2. docs-lab/reference/glossary.md#L28 (line 28): add an "RFC 2119 keywords" entry (mirroring what the old docs/ glossary had) with the ALL-CAPS condition made explicit.
Lingua principale
TypeScript
Stelle
73.6k
Fork
5k
Merge medio
3g 20h
PR unite (30g)
56

Preparare l'ambiente

Apri in Codespaces

Avvia il container di sviluppo del progetto nel browser, con il tuo account GitHub.

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di Fission-AI/OpenSpec

Tutte le issue di Fission-AI/OpenSpec

Issue simili

Altre issue su TypeScript

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.