Yoshi Yamaguchi

OTEP-0266: OTEPを仕様リポジトリへ移動

OTEPのドキュメントとPRを仕様リポジトリに戻しましょう。

動機

OTEPを仕様に戻すことで、2つの主要な課題を解決します。

  • そのツールインフラの保守（現在ひどく古くなっています）
  • 仕様内に既存のトリアージおよび投票プロセスに組み込むこと

解説

もともとOTEPは、無関係で破壊的な設計を分離しておくために、別のリポジトリとして保持されていました。 通常のPRとOTEPの間にはいくつかの違いがあります。

  • OTEPは方向性を示すものであり、実際に仕様に取り込まれる際には変更される可能性があります。
  • OTEPは仕様PRよりも多くの承認を必要とします。
  • OTEPは異なるPRワークフローを持っています（意図的な省略によるものか、意識的な決定によるものかを問わず）。たとえば、停滞チェックやリンティングなどです。

OpenTelemetryが安定化するにつれて、OTEPを仕様の外に置いておく必要性は薄れてきており、私たちは次のような課題に直面しています。

  • OTEPのツールを最新の状態に保つこと
  • リポジトリの存在を周知すること
    • OpenTelemetryの新しいコントリビューターは、OTEPに記録されている決定事項を見つけられないことがよくあります。
    • 仕様リポジトリの確認には慣れているものの、あまり頻繁に作業されないOTEPリポジトリには慣れていない人たちからレビューを得ること

これらを解決するために、OTEPを仕様リポジトリ内のディレクトリに移動しましょう。 また、OTEPの既存の標準に合わせて、すべてのツールと期待されるレビューを更新します。 OTEPのメンテナーが仕様のメンテナーと同じであることを踏まえると、これによって受け入れの基準が変わることはないはずです。

内部の詳細

以下の変更が発生します。

  • 次のファイルが仕様リポジトリに移動されます。
    • text/ ディレクトリ -> oteps/text/
    • 0000-template.md -> oteps/0000-template.md
  • 仕様の Makefile を更新して、リンティング、スペルチェック、リンクチェック、およびotepsディレクトリのTOC化を含めます。
  • 仕様リポジトリへのインポート時に、OTEPのMarkdownを一度限りクリーンアップします。
  • 既存のOTEP PRをクローズし、仕様リポジトリに対して再度オープンするよう依頼します。
  • OTEPをタグ付けするための仕様リポジトリ内の新しいラベル、およびPRオープン時にこれらを設定する自動化を追加します。
  • OTEPに関するセクションを含めるように、コントリビューションガイドラインを更新します。
  • OTEPが規範的ではなく、拡張提案プロセスの一部であることを説明するoteps/README.md ファイルを追加します。
  • すべてのOTEPのヘッダーに、内容が規範的ではなく拡張提案プロセスの一部であるという免責事項を追加します。

トレードオフと緩和策

仕様リポジトリへの移動は、リポジトリの残りの部分とは異なる品質基準、そしてある程度異なるプロセスを持つディレクトリができることを意味します。 これは、OTEPのための明確で目立つラベルを使用し、現在のOTEPステータスの重要な側面を維持するために仕様リポジトリのプロセスガイドラインを更新することで緩和できます。

先行技術と代替技術

OTEPはもともと、他のエコシステムにおける一般的な拡張提案プロセスをもとにしており、そこでは拡張機能がコアリポジトリの外に置かれ、より厳格な基準と評価に従います。 私たちは上記で議論した理由から、これがOpenTelemetryにとって問題であることに気づきつつあります。 さらに、設計をコアコードから分離しておく他の多くのエコシステムとは異なり、OpenTelemetryは仕様リポジトリと実装リポジトリを通じて、すでに 設計をコアコードから分離しています。 これらの他のOSSプロジェクトとは異なり、私たちの仕様は一般に、受け入れ前に厳格な議論、設計、プロトタイピングを必要とします。 仕様への受け入れ後であっても、エコシステムへの改善のロールアウトにはまだ作業が必要です。 つまり、OpenTelemetryの仕様には「小さな」変更というものは存在しません。 他のプロジェクトでは拡張機能となるような、小さく見える中規模の変更か、OTEPを必要とする大規模な変更のいずれかしかないのです。

未解決の問題

OTEPプロセスのどの部分を持ち越すことが重要でしょうか。 この説明で見落としていることはあるでしょうか。

今後の課題

将来的には、opentelemetry.ioサイト内でOTEPをより検索しやすく、発見しやすく、目立たせる方法を検討できるでしょう。

さらに、OTEPラベルの付いたPRの停滞期限を延長することも検討できます。