実験的、非推奨、廃止

これらの用語は、技術や仕様と一般的に関連しており、 MDN Web Docs で技術の状態をラベル付けするために使用されます。これらの用語の定義については、 MDN Web Docs は Browser Compatibility Data (BCD) リポジトリーと連携しています。 これらの用語は、 MDN Web Docs で使用するという文脈で下記に記述します。

実験的

MDN Web Docs で、ある技術が実験的 (experimental) と記述されている場合、それは、その技術がまだ発展途上で未熟であり、現在ウェブのプラットフォームに追加される(または追加を検討している)過程にあることを意味しています。 ある技術を実験的であると示すことは、何らかの制作プロジェクト(つまり、単なるデモや実験ではないプロジェクト)でその技術を使用する前に慎重に考えるべきであるということを示します。読者は実験的な機能を試し、ブラウザーベンダーや 標準規格の作成者にフィードバックを提供することが推奨されます。

実験的 (experimental) とマークされた技術は、次の一方または両方が成り立つちます。

  • 主要なブラウザーのレンダリングエンジンのリリースビルドで、実装され既定で有効になっているものが 1 つだけである。
  • 対応するレンダリングエンジンの数に関係なく、環境設定やフラグなどの設定変更によってのみ対応している。
  • 定義している仕様が、後方互換性のない方法で大幅に変更される可能性がある(つまり、その機能に依存する既存のコードを破壊する可能性がある)。

メモ: 1 つのレンダリングエンジンでしかリリースされていない機能は、他のレンダリングエンジンのプレビュービルドで(あるいは環境設定やフラグを設定することで)利用できても、実験的とみなされます。

以下の条件を 1 つ以上満たす場合、技術の実験的の状態ではなくなる可能性があります。

  • 2 つ以上の主要なブラウザーレンダリングエンジンで既定で対応している。
  • 単一のブラウザー用レンダリングエンジンで2年以上にわたって既定で対応しており、大きな変更がない。
  • 定義している仕様が、互換性を失わせる形で変化することはないとみられる。

これらの条件の例については、 experimental flag(BCD ドキュメント)を参照してください。

通常、ある技術が複数の主要なブラウザーで対応している場合、仕様が安定していることになりますが、常にそうであるとは限りません。 他にも、仕様が安定していても、ブラウザーのネイティブ対応がされていない技術もあるかもしれません。例えば、 IMSC は JavaScript のポリフィルで使用されています。

アクティブな仕様や標準化プロセスの一部であり、非推奨とマークされていない機能または技術は、標準化路線にあると言います。

非推奨

MDN Web Docs で非推奨 (deprecated) という用語は、推奨されなくなった API や技術を示すために使用されます。非推奨の API や技術は、将来的に削除されるかもしれませんし、互換性のためだけに残されていてまだ動作する可能性があるかもしれません。非推奨ですと表示された機能は使用しないことをお勧めします。

非推奨の定義の詳細については、deprecated flag(BCD ドキュメント)を参照してください。

廃止

MDN Web Docs において、廃止 (obsolete) という用語は、過去には、もう推奨されないだけでなく、ブラウザーに実装されなくなった API や技術を示すために使用されていました。 廃止非推奨の区別はあまり有益ではないため、 MDN Web Docs では廃止という用語は使用しなくなりました。

メモ: もし、廃止の用語を見つけたら、それを削除するか、非推奨という言葉で置き換えてください。

コンテンツ削除のガイドライン

新しい仕様の開発中や HTML のような生きた標準の進化の過程で、新しい要素、メソッド、プロパティなどが仕様に追加され、しばらくの間そこにとどまり、その後削除されることがあります。これはとてもすばやく起こることもあれば、新しいアイテムが削除される前に数ヶ月、あるいは数年間仕様に残ることもあります。このような場合、仕様からアイテムを削除する際に、どのように処理するかを決めるのは難しいことです。

ここでは、何かが仕様から削除されたときにどうするかを決定するのに役立つガイドラインをいくつか紹介します。

メモ: この説明では、「アイテム」という言葉は、要素や要素の属性、インターフェイスや個々のメソッド、プロパティ、インターフェイスの他にもメンバーなど、仕様の一部となり得る何らかのものを意味して使用されています。

アイテムが実装されなかった場合

もしそのアイテムが、ブラウザーのリリースバージョンで実装されたことがなく、環境設定やフラグで隠された形でも実装がなくなった場合、ドキュメントからそのアイテムへの参照をすべて削除してください。

  • そのアイテムに、そのアイテムだけを記述したドキュメントページ(RTCPeerConnection.close() など)があれば、そのページを削除してください。 削除されたアイテムがインターフェイスの場合、そのインターフェイスのプロパティとメソッドを記述したサブページも同様に削除するという意味です。
  • プロパティ、属性、メソッドなどのリストから、そのアイテムを削除してください。例えばインターフェイスのメソッドの場合、これはインターフェイスの概要ページの「メソッド」節から削除するという意味です。
  • インターフェイスや要素などの概要ページのテキストを検索し、削除されたアイテムを参照しているものがないか調べてください。文法上の問題や他の問題を残さないように注意しながら、それらの参照を削除してください。これは、単に単語を削除するだけでなく、文や段落をより意味のあるものに書き換える必要がある場合もあります。また、使用するアイテムの説明文が長い場合は、コンテンツの節全体を削除することもあります。
  • 同様に、関連する API や技術に関するガイドやチュートリアルの中に、そのアイテムについての説明がないか探してみてください。文法上の問題や他の問題を残さないように注意しながら、それらの参照を削除してください。これは、単に単語を削除するだけでなく、より意味が通るように文章や段落を書き直すことを意味している場合もあります。また、使用するアイテムの説明が長い場合は、コンテンツの節全体を削除することもあります。
  • 他の場所に説明がある場合に備えて、削除されたアイテムへの参照がないか MDN Web Docs を検索してください。実装されなかったのであれば、広く語られることもないでしょうから、そうである可能性は低いでしょう。これらの言及も削除してください。
  • ブラウザー互換性データリポジトリーの JSON ファイルに削除されたアイテムのデータが格納されている場合、JSON コードからそれらのオブジェクトを削除し、その変更でプルリクエストを送信し、コミットメッセージとプルリクエスト説明で理由を説明してください。その際、JSON の構文が崩れないかどうか、注意して調べてください。

ブラウザーでフラグに隠された実装されたアイテムがある場合

もしそのアイテムが 1 つまたは複数のブラウザーで実装されていたとしても、環境設定やフラグの後ろだけであれば、そのアイテムをすぐに文書から削除しないでください。代わりに、以下のようにそのアイテムを非推奨としてマークしてください。

  • browser-compat-data リポジトリー内のアイテムの状態データは、プルリクエストを送信することで更新してください。
  • そのインターフェイスや要素などの概要ページの情報テキストを検索して、削除されたアイテムを参照しているかどうかを確認する。適切な場所に警告ボックスを追加し、「[アイテム]は仕様から削除され、近いうちにブラウザーからも削除される予定です。新しい方法については、[ページへのリンク]を参照してください。」という内容の警告ボックスを適切な場所に追加してください。
  • 同様に、関連する API や技術に関するガイドやチュートリアルの中で、そのアイテムに関する説明がないか探してみてください。同様の警告を追加してください。
  • 他の場所に説明がある場合に備えて、 MDN Web Docs で削除されたアイテムを参照しているものを検索してください。そこにも同様の警告ボックスを追加してください。
  • 将来的には、ドキュメント内のアイテムを実際に削除することを決定することもあります。通常はこのようなことはしませんが、特に活用されていないアイテムや興味のないアイテムについてはそうすることもあります。
  • ブラウザー互換性データリポジトリーの関連項目を更新し、影響を受けるアイテムが廃止されたことを反映してください。

ブラウザーでフラグなしで実装されたアイテムである場合

環境設定やフラグを必要とせず、そのアイテムが1つ以上のリリースビルドのブラウザーで実装された場合、以下のようにそのアイテムを非推奨としてマークします。

  • プルリクエストを送信することで、ブラウザーコンパットデータリポジトリーのアイテムのステータスデータを更新します。
  • そのインターフェイスや要素などの概要ページの情報テキストを検索し、除去されたアイテムが参照されていないか調べます。適切な場所に「[item] は仕様から除去され、非推奨です。将来ブラウザーから除去される可能性がありますので、使用しないでください。新しい方法については、[ページへのリンク]を参照してください。」という警告ボックスを追加してください。
  • 同様に、関連するAPIや技術に関するガイドやチュートリアルで、そのアイテムに関するディスカッションがないか見ていってください。同様の警告を追加してください。
  • 他の場所に説明がある場合に備えて、削除されたアイテムに参照する MDN Web Docs を検索してください。そこにも同様の警告ボックスを追加してください。
  • これらのアイテムがドキュメントから削除されることは、もしあったとしても、すぐにはないかもしれません。
  • ブラウザー互換性データリポジトリーの関連項目を更新し、該当するアイテムを非推奨にしてください。

警告メッセージの文言や、上記のガイドラインで提案された文章の他の変更については、常識的な範囲で使用してください。 異なる形で、異なる文言や処理することが必要になります。 迷ったときは、MDN Web Docs チャットルームで遠慮なく相談してください。

仕様書が競合した場合のドキュメントのガイドライン

時々 (まれに) 仕様書の異なるバージョン (特に W3C と WHATWG) が競合することがあります。例えば、一方のバージョンがある機能を非推奨とする一方で、もう一方が非推奨にしない場合などがあります。 このような場合、何が真実なのか、例えば、ブラウザーは実際にどうしているかを考慮し、「重要」なメモを書いて最新の状態を要約してください。 例えば、 2019 年 1 月時点の inputmode グローバル属性には競合があり、次のように要約されています。

警告: 仕様の競合があります。 WHATWG 仕様では inputmode がリストアップされており、最近のブラウザーはこれに対応する方向で動いています。 しかし W3C HTML 5.2 仕様書ではこれをリストアップしていません(つまり廃止とマークしています)。 合意が得られるまでは、 WHATWG の定義が正しいと考えるべきでしょう。

関連情報