実験的、非推奨、廃止

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

実験的

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

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

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

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

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

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

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

通常、ある技術が複数の主要なブラウザーで対応している場合、仕様が安定していることになりますが、常にそうであるとは限りません。 他にも、仕様が安定していても、ブラウザーのネイティブ対応がされていない技術もあるかもしれません。例えば、IMSC (en-US) は 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 つまたは複数のブラウザーで実装されていたとしても、環境設定やフラグの後ろだけであれば、その項目をすぐに文書から削除しないでください。代わりに、以下のようにその項目を非推奨としてマークしてください。

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

ブラウザーでフラグなしで実装された項目である場合

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

  • その項目に、その項目だけを記述したドキュメントページがある場合(RTCPeerConnection.close() など)、deprecated_header マクロをそのページのトップに追加し、以下の status: フロントマター項目を加えてください。
    status:
      - deprecated
    
  • その要素、インターフェイス、API の概要ページで、仕様から削除された項目を含む項目のリストを探し、そのリストの項目名の後に deprecated_inline マクロを追加してください。
  • 同様に、関連する API や技術に関するガイドやチュートリアルの中で、その項目に関する説明がないか探してみてください。同様の警告を追加してください。
  • 他の場所に説明がある場合に備えて、削除されたアイテムに参照する MDN Web Docs を検索してください。そこにも同様の警告ボックスを追加してください。
  • これらの項目がドキュメントから削除されることは、もしあったとしても、すぐにはないかもしれません。
  • ブラウザ互換性データリポジトリーの関連項目を更新し、該当する項目を非推奨にしてください。

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

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

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

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