Prepare FAPI 2.0 Implementation Advice for informational publication

Abierto
  • ¿Algo no está bien?
#886 0 comentarios 0 reacciones 0 asignados Ver en GitHub

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
5/5
Tiempo estimado
Más de una semana
Aptitud para principiantes
35/100
Tipo de issue
Documentación
Claridad
Bien especificado
Estado de actividad
Activo
Stack tecnológico
html
Área
documentation

Línea de trabajo

Start with the document’s front matter and publication build in build-all.py, then review the linked FAPI 2.0 Implementation Advice source and the OIDF naming and publication check references. Check how the document identifier and output filenames are set before removing seriesInfo, and review status language, normative recommendations, Notices, acknowledgements, security considerations, references, and history. Done means the informational OIDF document builds without inappropriate IETF metadata and passes the publication checks.

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

Descripción

Background

We would like to publish "FAPI 2.0 Implementation Advice" (https://github.com/openid/fapi/blob/master/FAPI_2_0_Implementation_Advice.md) at https://openid.net/specs/.

Since this document provides implementation advice rather than defining a normative security profile, it should be published as an informational document, not as a Standards Track specification.

The current metadata and some aspects of the document need to be corrected before publication.

  1. Correct the document metadata

The current front matter contains:

title = "FAPI 2.0 Implementation Advice"
abbrev = "fapi-2-implementation-advice"
ipr = "none"
workgroup = "connect"

[seriesInfo]
name = "Internet-Draft"
value = "fapi-2_0-implementation_advice-01"
status = "standard"

The following changes are needed:

  • "workgroup": Change "connect" to "fapi".
  • "seriesInfo.name": Remove "Internet-Draft". This is not an IETF Internet-Draft. "Informational" should not be substituted as the series name, since it describes a document category rather than a publication series.
  • "seriesInfo.status": The current "standard" value incorrectly identifies the document as Standards Track. The generated document should clearly identify its informational nature.
  • "seriesInfo": Prefer removing the entire block, since this is an OIDF publication rather than an RFC or IETF Internet-Draft. The document identifier and output filename should be managed independently.
  • "ipr": Keep "ipr = "none"" to suppress IETF-specific IPR boilerplate. OIDF copyright and licensing notices must remain in the document.

Note that the current FAPI build pipeline relies on "seriesInfo.value" for output filenames. Removal of "seriesInfo" therefore depends on fixing that build dependency separately.

See "build-all.py" (https://github.com/openid/fapi/blob/master/build-all.py).

  1. Clarify the document's status

The document should clearly distinguish:

  • Its type: Informational implementation guidance.
  • Its publication status: Working Group Draft or another applicable OIDF publication stage.

In particular, the document should not imply that it is an OIDF International Standard or an IETF Standards Track document.

The title, document identifier, revision number, and draft disclaimer should be aligned with the intended publication stage and OIDF naming conventions.

  1. Review normative language

Some sections, particularly the HTTP header recommendations, contain normative requirements using "shall" and "should".

We should review whether these requirements are appropriate for an informational advice document.

In particular, we should distinguish recommendations for implementations from requirements that an ecosystem may choose to adopt.

If the document intends to define new interoperability requirements, we should consider whether those requirements belong in a separate normative specification.

  1. Complete publication readiness checks

Before submission:

  • Update the copyright year and verify that the Notices text conforms to the current OIDF IPR Policy.
  • Complete the Acknowledgements section (currently "todo...").
  • Add or review Security Considerations.
  • Verify the References and their normative/informative classification.
  • Add Document History if required for the publication stage.
  • Ensure that the generated HTML and source filenames follow OIDF publication conventions.
  • Validate the generated HTML against the "openid/publication" checks.

Acceptance criteria

  1. The document is clearly identified as informational guidance from the FAPI Working Group.
  2. No incorrect IETF Internet-Draft or Standards Track metadata appears in the generated document.
  3. The document builds successfully without relying on inappropriate "seriesInfo" values.
  4. The Notices and other publication metadata conform to OIDF requirements.
  5. The document passes the applicable publication checks and is ready for submission to "openid.net/specs/".

References

Lenguaje dominante
HTML
Estrellas
5
Forks
3
Sin PR fusionados en 30 d

Preparar el entorno

Este proyecto no incluye contenedor de desarrollo, Dockerfile ni guía de contribución, así que la configuración corre por tu cuenta: empieza por su README y consulta nuestra guía para la primera contribución para los pasos generales.

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 openid/fapi

Todos los issues de openid/fapi

Issues similares

Más issues de Documentation

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.