Prepare FAPI 2.0 Implementation Advice for informational publication

オープン
  • 何か問題がありますか？
#886 コメント 0 件 リアクション 0 件 担当者 0 名 GitHub で見る

まだ誰も着手していません。

評価

難易度
5/5
見積もり時間
1週間以上
初心者へのやさしさ
35/100
issue の種類
ドキュメント
明瞭さ
明確に書かれている
活発さ
活発
技術スタック
html
領域
documentation

調査の方向性

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.

索引モデルが issue の本文から書いたものです。

説明

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

主要言語
HTML
スター
5
フォーク
3
30日以内にマージされた PR はありません

環境構築

このプロジェクトには開発コンテナ、Dockerfile、コントリビューションガイドがありません。まず README を読み、一般的な手順ははじめてのコントリビューションガイドを参照してください。

はじめの一歩

  1. issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
  2. 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
  3. リポジトリをフォークし、ブランチを切って変更します。
  4. issue 番号を参照したプルリクエストを送ります。

openid/fapi のほかの issue

openid/fapi の issue をすべて見る

似ている issue

Documentation の issue をもっと見る

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。