後方互換性

Topics

歴史的に WordPress はバージョン間の後方互換性を維持することで知られてきました。Gutenberg でも可能な限り製品版の公開 API に対してこの先例に従います。後方互換性を維持しない稀なケースはそれが避けられず、かつ、後方互換性の破壊が以下の場合に限ります。

  • 破壊が、API 表面のできる限り小さな部分に限定されること
  • 破壊が、サードパーティの開発者に対して明確に、Dev Notes (開発ノート) としてドキュメントされること

製品版公開 API の範囲

Gutenberg のコードベースは、異なるタイプの2つのパッケージから構成されます。

  • 製品版パッケージ: WordPress スクリプトとしてリリースされるパッケージ (例: wp-components、wp-editor 等)
  • 開発版パッケージ: 開発ツールを構成するパッケージ。サードパーティー開発者はこの開発ツールを使用してテーマやプラグインのコードを lint、テスト、整形、ビルドします (例: @wordpress/scrips、@wordpress/env 等)。一般にサードパーティプロジェクトでは npm の依存として使用します。

後方互換性は製品版パッケージにのみ維持され、更新は WordPress の更新を通して行われます。

製品版パッケージは wp グローバル変数を使用してサードパーティ開発者に API を提供します。API には JavaScript 関数、変数、React コンポーネントが含まれます。

Top ↑

後方互換性を保つには – JavaScript 関数

  • 関数名を変えないでください。
  • 関数の引数の順番を変えないでください。
  • 関数の戻り値の型を変えないでください。
  • 新規の引数や引数の意味の変更などの引数の変更は、以前の呼び出しがすべて可能であることを保証できる場合において、可能です。

Top ↑

後方互換性を保つには – React コンポーネント

  • コンポーネント名を変えないでください。
  • コンポーネントの props を削除しないでください。
  • 既存の prop 値のサポートは続けてください。コンポーネントが prop に関数を取る場合には、その prop で新しいタイプを受け入れる形でコンポーネントを更新できます。ただし現在の利用を妨げる変更はできません。
  • 新しい props の追加は認められます。
  • React のコンテキストの依存性は、以前のコンテキストの契約が破られない限りにおいて、追加、削除できます。

Top ↑

後方互換性を保つには – ブロック

  • 既存のブロックの利用を妨げないでください。あるいは、エディターがロードされた際に「invalid (不正)」としてマークしてください。
  • 既存のブロックのスタイルを保証してください。
  • マークアップの変更は可能な限り最小に留めてください。ブロックの保存したマークアップの変更が必要な場合には、以前のバージョンのブロックを不正とし、ブロックの 非推薦バージョン に追加してください。

Top ↑

クラス名と DOM の更新

React コンポーネントツリー内のクラス名や DOM ノードは、公開 API の一部とみなさないため変更できます。

変更する場合、本来サードパーティはツリー内のクラス名や DOM ノードに依存してはならないのですが、それでもサードパーティコードのスタイルや動作に影響を与えないよう注意してください。影響を与える場合は変更をドキュメントし、Dev Notes を書いてください。

Top ↑

非推奨

プロジェクトが進むと既存の API の欠点が見つかったり、新機能のサポートのために更新が必要になります。このような場合、既存の API が壊れないことを保証するため新しい代替 API を構築します。

サードパーティの開発者が古い API を使用した場合には、deprecated ヘルパーを使用して非推奨を伝えるメッセージを表示し代替の API を提案できます。

機能が非推奨になった時期をよりクリアにできます。支援メソッドの since と plugin オプションを使用してください。

例:

deprecated( 'wp.components.ClipboardButton', {
    since: '10.3',
    plugin: 'Gutenberg',
    alternative: 'wp.compose.useCopyToClipboard',
} );

Top ↑

Dev Notes (開発ノート)

Dev Notes (開発ノート) とは WordPress のリリースに先立ち make/core サイトに投稿される記事 のことで、サードパーティ開発者に API の重要な変更を伝えます。変更には以下が含まれます。

  • 新しい API
  • 既存のプラグインやテーマに影響を与える可能性のある API の変更 (例: クラス名の変更等)
  • 避けられなかった後方互換性の破壊。理由と移行フローを付記する。
  • 重要な非推奨 (破壊がない場合も)。理由と移行フローを付記する。

Top ↑

Dev Notes ワークフロー

  • プルリクエスト (PR) での作業の際に Dev Notes の必要性が出てきた場合、PR にラベル Needs Dev Note を追加する。
  • 可能であれば、なぜ Dev Notes が必要かを説明するコメントを PR に追加する。
  • WordPress 次期リリースの最初のベータが公開される際に、そのリリースのコードにマージされた PR のうちラベル Needs Dev Note の付いた PR のリストを作成する。
  • PR ごとに Dev Notes を書き、WordPress リリースリードと協調して Dev Notes を公開する。
  • PR の Dev Notes が公開されたら、ラベル Needs Dev Note を PR から削除する。

原文

最終更新日: