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

Abierto Apto para principiantes
  • ¿Algo no está bien?
#2,200 0 comentarios 0 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 2 días

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
1/5
Tiempo estimado
1-3 horas
Aptitud para principiantes
88/100
Tipo de issue
Documentación
Claridad
Bien especificado
Estado de actividad
Activo
Área
documentation

Línea de trabajo

Lee docs-lab/README.md y los dos archivos mencionados: docs-lab/reference/schemas/spec-driven/index.md cerca de la línea 218 y docs-lab/reference/glossary.md cerca de la línea 28. Compara sus indicaciones con las referencias a los RFC en openspec/specs/cli-validate/spec.md y las citas antiguas de docs/. Añade la atribución de RFC 2119 y RFC 8174 y explica que los significados definidos se aplican a las palabras clave escritas en mayúsculas; la tarea estará completa cuando esto quede claro en ambas páginas de documentación vigentes.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

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.
Lenguaje dominante
TypeScript
Estrellas
73.6k
Forks
5k
Merge medio
3 d 20 h
PR fusionados (30 d)
56

Preparar el entorno

Abrir en Codespaces

Inicia el contenedor de desarrollo del proyecto en tu navegador, con tu propia cuenta de GitHub.

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de Fission-AI/OpenSpec

Todos los issues de Fission-AI/OpenSpec

Issues similares

Más issues de TypeScript

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.