From 9211a81d16bd62dec44a6c68b12da0bcc889ddc3 Mon Sep 17 00:00:00 2001 From: "Issei.M" Date: Fri, 25 Apr 2014 15:09:20 +0900 Subject: [PATCH 1/2] =?UTF-8?q?contribution/code/bc.rst=20=E3=82=92?= =?UTF-8?q?=E7=BF=BB=E8=A8=B3=20(fixes=20#294)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- contributing/code/bc.rst | 330 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 330 insertions(+) create mode 100644 contributing/code/bc.rst diff --git a/contributing/code/bc.rst b/contributing/code/bc.rst new file mode 100644 index 0000000..bad1082 --- /dev/null +++ b/contributing/code/bc.rst @@ -0,0 +1,330 @@ +.. note:: + + * 対象バージョン：2.3以降 + * 翻訳更新日：2014/04/25 + +後方互換性の保証について +======================== + +私達はプロジェクトの円滑なアップグレードの保証を最重視している為、Symfonyではすべてのマイナーリリース間の後方互換性を保証します。 +このようなバージョン管理の方式を\ `セマンティックバージョニング`_\ と呼びます。 +セマンティックバージョニングは、互換性のないAPIの変更はメジャーリリース（2.0や3.0など）でのみ行い、マイナーリリース（2.5や2.6のような）では新機能の追加は、そのリリースブランチ（前の例で言う2.x）の既存のAPIの後方互換性が保たれた状態で行われます。 + +.. caution:: + + この保証はSymfony 2.3 から施行されたため、その前のバージョンには適用されません。 + +しかし、後方互換性の破壊はあらゆる場面で起きます。 +実際には、フレームワークに行われるほぼすべての変更がアプリケーションを破壊する可能性があると言っても過言ではありません。 +例えば、Symfonyのクラスをアプリケーションで継承して使っている場合、あなたが既に追加したメソッドとシグネチャの異なる同名のメソッドが追加された時にアプリケーションが壊れてしまいます。 + +同時に、全ての後方互換性の破壊がアプリケーションに影響を与えると言うわけではありません。 +既存のクラスやアーキテクチャに大幅な変更が必要な場合がある一方で、単にメソッド名を変更する等、簡単に解決できる場合もあります。 + +そこで私達はこのページを作りました。"Symfonyコードの利用"セクションでは、どのようにすればアプリケーションを壊す事なく、新しいマイナーバージョンに確実にアップグレードできるかについて説明します。 + +次の"Symfonyコードへの取り組み"は、Symfonyのコントリビュータ向けのセクションです。 +このセクションではユーザが円滑にアップグレードを行えるように、すべてのコントリビュータが守るべき規則の詳細を列挙します。 + +Symfonyコードの利用 +------------------- + +以下のガイドラインに沿ってSymfonyを使用していれば、今後のすべてのマイナーバージョンに円滑にアップグレードする事ができます。 + +インターフェースの利用 +~~~~~~~~~~~~~~~~~~~~~~ + +Symfonyが用意する全てのインターフェースはタイプヒントで指定する事ができ、宣言されている全てのメソッドをコールすることができます。 +これらの規則に従うコードは壊される事はありません。 + +.. caution:: + + ``@internal``\ タグが付いているインターフェースは保証外になります。このようなインターフェースは使用、または実装すべきでありません。 + +インターフェースを実装する場合は、まずそれがAPIインターフェースであるか確認しましょう。次のような、\ ``@api``\ タグの付いている物はAPIインターフェースとなります:: + + /** + * HttpKernelInterface handles a Request to convert it to a Response. + * + * @author Fabien Potencier + * + * @api + */ + interface HttpKernelInterface + { + // ... + } + +APIインターフェースを実装していれば、将来そのコードが壊される事はありません。対照的に、レギュラーインターフェースはマイナーリリース時に新しいメソッドを追加する等の拡張がされる事がある為、アップグレードの際は事前に確認を行い、必要に応じて手動でコードを移行する必要があります。 + +.. note:: + + 容易に移行が可能な変更だけが行われます。また、それらの変更がある際はSymfonyルートディレクトリに配置されるUPGRADEファイルに正確な移行の指示を明記します。 + +次の表は、どのようなユースケースで後方互換性が保たれるかを説明します。 + ++-------------------------------------------------+-----------------+-----------------+ +| ユースケース | レギュラー | API | ++=================================================+=================+=================+ +| **あなたが...** | **する場合は後方互換性を保証...** | ++-------------------------------------------------+-----------------+-----------------+ +| インターフェースへのタイプヒント | Yes | Yes | ++-------------------------------------------------+-----------------+-----------------+ +| メソッドをコール | Yes | Yes | ++-------------------------------------------------+-----------------+-----------------+ +| **あなたがインターフェースを実装し、かつ、...** | **する場合は後方互換性を保証...** | ++-------------------------------------------------+-----------------+-----------------+ +| メソッドを実装 | No [1]_ | Yes | ++-------------------------------------------------+-----------------+-----------------+ +| 実装したメソッドに引数を追加 | No [1]_ | Yes | ++-------------------------------------------------+-----------------+-----------------+ +| 引数にデフォルト値を設定 | Yes | Yes | ++-------------------------------------------------+-----------------+-----------------+ + +.. include:: _api_tagging.rst.inc + +クラスの利用 +~~~~~~~~~~~~ + +Symfonyによって提供されるすべてのクラスはインスタンス化され、publicメソッドおよびプロパティを介してアクセスする事ができます。 + +.. caution:: + + ``@internal``\ タグの付いたクラス、プロパティやメソッド、並びに名前空間に\ ``**Tests**``\ を含むクラスはこの規約の対象外となります。 + これらは内部利用を目的としているので、アプリケーションのコードからアクセスすべきではありません。 + +インターフェースと同様、クラスもAPIクラス、通常クラスと区分されています。 +APIクラスもインターフェースと同様に\ ``@api``\ タグが付けられています:: + + /** + * Request represents an HTTP request. + * + * @author Fabien Potencier + * + * @api + */ + class Request + { + // ... + } + +APIクラスとレギュラークラスの違いは、APIクラスは継承先でオーバーライドしたメソッドは完全に後方互換性が保証されるのに対し、レギュラークラスはその限りではないと言う点です。 +例えば省略可能な引数がメソッドに追加される事があります。その結果、あなたがオーバーライドしたメソッドとのシグネチャに不一致が生じた場合、致命的なエラーが発生するでしょう。 + +.. note:: + + インターフェースと同様に、クラスの変更は最小限に留められ、移行が必要な場合はSymfonyルートディレクトリに配置されるUPGRADEにその詳細な手順を示します。 + +場合によっては、\ ``@api``\ タグがクラス単位ではなく、特定のプロパティやメソッドにのみ付けられている事があります。 +このような場合、そのプロパティやメソッドに対する（下図のAPI列で示すように）後方互換性は保証されますが、それ以外の部分に関してはその限りではないと言う事を意味します。 + +念のため、以下のユースケースと後方互換性保証の対応表を確認して下さい: + ++------------------------------------------------+-----------------+-----------------+ +| ユースケース | レギュラー | API | ++================================================+=================+=================+ +| **あなたが...** | **する場合は後方互換性を保証...** | ++------------------------------------------------+-----------------+-----------------+ +| クラスへのタイプヒント | Yes | Yes | ++------------------------------------------------+-----------------+-----------------+ +| 新しいインスタンスを作成 | Yes | Yes | ++------------------------------------------------+-----------------+-----------------+ +| クラスを継承 | Yes | Yes | ++------------------------------------------------+-----------------+-----------------+ +| publicプロパティにアクセス | Yes | Yes | ++------------------------------------------------+-----------------+-----------------+ +| publicメソッドをコール | Yes | Yes | ++------------------------------------------------+-----------------+-----------------+ +| **あなたがクラスを継承し、かつ、...** | **する場合は後方互換性を保証...** | ++------------------------------------------------+-----------------+-----------------+ +| protectedプロパティにアクセス | No [1]_ | Yes | ++------------------------------------------------+-----------------+-----------------+ +| protectedメソッドをコール | No [1]_ | Yes | ++------------------------------------------------+-----------------+-----------------+ +| publicプロパティをオーバーライド | Yes | Yes | ++------------------------------------------------+-----------------+-----------------+ +| protectedプロパティをオーバーライド | No [1]_ | Yes | ++------------------------------------------------+-----------------+-----------------+ +| publicメソッドをオーバーライド | No [1]_ | Yes | ++------------------------------------------------+-----------------+-----------------+ +| protectedメソッドをオーバーライド | No [1]_ | Yes | ++------------------------------------------------+-----------------+-----------------+ +| 新しいプロパティを追加 | No | No | ++------------------------------------------------+-----------------+-----------------+ +| 新しいメソッドを追加 | No | No | ++------------------------------------------------+-----------------+-----------------+ +| オーバーライドしたメソッドに引数を追加 | No [1]_ | Yes | ++------------------------------------------------+-----------------+-----------------+ +| 引数にデフォルト値を追加 | Yes | Yes | ++------------------------------------------------+-----------------+-----------------+ +| （Reflectionから）privateメソッドのコール | No | No | ++------------------------------------------------+-----------------+-----------------+ +| (Reflectionから) privateプロパティにアクセス | No | No | ++------------------------------------------------+-----------------+-----------------+ + +.. include:: _api_tagging.rst.inc + +Symfony Codeへの取り組み +------------------------ + +Symfonyの改善に貢献する場合、ユーザーの円滑なアップグレードを保証する為に下記で示すルールに厳格に則る必要があります。 + +インターフェースへの変更 +~~~~~~~~~~~~~~~~~~~~~~~~ + +次の表では、既存インターフェースに対して許可されている変更を示します: + +=========================================== ============== ============== +変更の内容 レギュラー API +=========================================== ============== ============== +インターフェースそのものを削除 No No +インターフェース名、あるいは名前空間の変更 No No +親インターフェースの追加 Yes [2]_ Yes [3]_ +親インターフェースの削除 No No +**メソッド** +メソッドの追加 Yes [2]_ No +メソッドの削除 No No +メソッド名の変更 No No +親インターフェースに移動 Yes Yes +デフォルト値を持たない引数の追加 No No +デフォルト値を持つ引数の追加 Yes [2]_ No +引数の削除 Yes [4]_ Yes [4]_ +引数にデフォルト値を設定 Yes [2]_ No +引数のデフォルト値を削除 No No +引数にタイプヒントを設定 No No +引数のタイプヒントを削除 Yes [2]_ No +引数の型を変更 Yes [2]_ [5]_ No +戻り値の型を変更 Yes [2]_ [6]_ No +=========================================== ============== ============== + +クラスへの変更 +~~~~~~~~~~~~~~ + +次の表では、既存クラスに対して許可されている変更を示します: + +======================================== ============== ============== +変更の内容 レギュラー API +======================================== ============== ============== +クラスそのものを削除 No No +finalに変更 No No +abstractに変更 No No +クラス名、あるいは名前空間の変更 No No +親クラスの変更 Yes [7]_ Yes [7]_ +インターフェースの追加 Yes Yes +インターフェースの削除 No No +**publicプロパティ** +publicプロパティの追加 Yes Yes +publicプロパティの削除 No No +スコープの降格 No No +親クラスに移動 Yes Yes +**protectedプロパティ** +protectedプロパティの追加 Yes Yes +protectedプロパティの削除 Yes [2]_ No +スコープの降格 Yes [2]_ No +親クラスに移動 Yes Yes +**privateプロパティ** +privateプロパティの追加 Yes Yes +privateプロパティの削除 Yes Yes +**コンストラクタ** +必須な引数のないコンストラクタの追加 Yes [2]_ Yes [2]_ +コンストラクタの削除 Yes [2]_ No +publicコンストラクタのスコープの降格 No No +protectedコンストラクタのスコープの降格 Yes [2]_ No +親クラスに移動 Yes Yes +**publicメソッド** +publicメソッドの追加 Yes Yes +publicメソッドの削除 No No +メソッド名の変更 No No +スコープの降格 No No +親クラスに移動 Yes Yes +デフォルト値を持たない引数の追加 No No +デフォルト値を持つ引数の追加 Yes [2]_ No +引数の削除 Yes [4]_ Yes [4]_ +引数にデフォルト値を設定 Yes [2]_ No +引数のデフォルト値を削除 No No +引数にタイプヒントを設定 Yes [8]_ No +引数のタイプヒントを削除 Yes [2]_ No +引数の型を変更 Yes [2]_ [5]_ No +戻り値の型を変更 Yes [2]_ [6]_ No +**protectedメソッド** +protectedメソッドの追加 Yes Yes +protectedメソッドの削除 Yes [2]_ No +メソッド名の変更 No No +スコープの降格 Yes [2]_ No +親クラスに移動 Yes Yes +デフォルト値を持たない引数の追加 Yes [2]_ No +デフォルト値を持つ引数の追加 Yes [2]_ No +引数の削除 Yes [4]_ Yes [4]_ +引数にデフォルト値を設定 Yes [2]_ No +引数のデフォルト値を削除 Yes [2]_ No +引数にタイプヒントを設定 Yes [2]_ No +引数のタイプヒントを削除 Yes [2]_ No +引数の型を変更 Yes [2]_ [5]_ No +戻り値の型を変更 Yes [2]_ [6]_ No +**privateメソッド** +protectedメソッドの追加 Yes Yes +protectedメソッドの削除 Yes Yes +メソッド名の変更 Yes Yes +スコープの降格 Yes Yes +デフォルト値を持たない引数の追加 Yes Yes +デフォルト値を持つ引数の追加 Yes Yes +引数の削除 Yes Yes +引数にデフォルト値を設定 Yes Yes +引数のデフォルト値を削除 Yes Yes +引数にタイプヒントを設定 Yes Yes +引数のタイプヒントを削除 Yes Yes +引数の型を変更 Yes Yes +戻り値の型を変更 Yes Yes +======================================== ============== ============== + +.. [1] アプリケーションのコードはSymfonyのアップグレード時に破損する可能性があるが、 + その際はUPGRADEファイルに移行の手順が明記される。 + +.. [2] 基本的に行うべきではない。行う場合はUPGARADEファイルに変更を明記する必要がある。 + +.. [3] 追加される親インターフェースは、現状のインターフェースに存在しない新しいメソッドを定義してはならない。 + +.. [4] 最後の引数（複数可）のみ削除可能。PHPは余分な引数の受け渡しを無視する為。 + +.. [5] 引数の型は互換性がある、またはより曖昧な型にのみ変更可能。許可されている変更は次の通り: + + =================== ============================================================================= + 変更元の型 変更先の型 + =================== ============================================================================= + boolean `boolean値`_\ と等価に評価可能な\ `スカラー型`_ + string `string値`_\ と等価に評価可能な\ `スカラー型`_\ またはオブジェクト + integer `integer値`_\ と等価に評価可能な\ `スカラー型`_ + float `float値`_\ と等価に評価可能な\ `スカラー型`_ + class ```` ```` のスーパークラス、またはこれが実装しているいずれかのインターフェース + interface ```` ```` のスーパーインタフェース + =================== ============================================================================= + +.. [6] 戻り値の型は互換性がある、またはより具体的な型にのみ変更可能。許可されている変更は次の通り: + + =================== ===================================================================================== + 変更元の型 変更先の型 + =================== ===================================================================================== + boolean `boolean値`_\ と等価に評価可能な\ `スカラー型`_ + string `string値`_\ と等価に評価可能な\ `スカラー型`_\ またはオブジェクト + integer `integer値`_\ と等価に評価可能な\ `スカラー型`_ + float `float値`_\ と等価に評価可能な\ `スカラー型`_ + array ``ArrayAccess``\ 、\ ``Traversable``\ そして\ ``Countable``\ を実装しているインスタンス + ``ArrayAccess`` array + ``Traversable`` array + ``Countable`` array + class ```` ```` のサブクラス + interface ```` ```` のサブインターフェース、またはこれを実装しているクラス + =================== ===================================================================================== + +.. [7] 変更される親クラスは、元のクラスの先祖である必要がある。 + +.. [8] 異なる型の値を渡した際にFatalエラーが発生する場合にのみタイプヒントを設定できる。 + +.. _セマンティックバージョニング: http://semver.org/ +.. _スカラー型: http://php.net/manual/ja/function.is-scalar.php +.. _boolean値: http://php.net/manual/ja/function.boolval.php +.. _string値: http://www.php.net/manual/ja/function.strval.php +.. _integer値: http://www.php.net/manual/ja/function.intval.php +.. _float値: http://www.php.net/manual/ja/function.floatval.php + +.. 2014/04/25 issei-m 6c1ded9af043f1711d6349db91711b2e5fc33bb4 From b51a8fb2496a47564046570aa59faaf945cd7464 Mon Sep 17 00:00:00 2001 From: "Issei.M" Date: Wed, 30 Apr 2014 19:42:52 +0900 Subject: [PATCH 2/2] =?UTF-8?q?contributing/code/bc.rst=20=E5=BE=AE?= =?UTF-8?q?=E8=AA=BF=E6=95=B4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- contributing/code/bc.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/contributing/code/bc.rst b/contributing/code/bc.rst index bad1082..af1059b 100644 --- a/contributing/code/bc.rst +++ b/contributing/code/bc.rst @@ -1,7 +1,7 @@ .. note:: * 対象バージョン：2.3以降 - * 翻訳更新日：2014/04/25 + * 翻訳更新日：2014/04/30 後方互換性の保証について ======================== @@ -93,7 +93,7 @@ Symfonyによって提供されるすべてのクラスはインスタンス化 ``@internal``\ タグの付いたクラス、プロパティやメソッド、並びに名前空間に\ ``**Tests**``\ を含むクラスはこの規約の対象外となります。 これらは内部利用を目的としているので、アプリケーションのコードからアクセスすべきではありません。 -インターフェースと同様、クラスもAPIクラス、通常クラスと区分されています。 +インターフェースと同様、クラスもAPIクラス、レギュラークラスと区分されています。 APIクラスもインターフェースと同様に\ ``@api``\ タグが付けられています:: /** @@ -308,7 +308,7 @@ protectedメソッドの削除 Yes Yes string `string値`_\ と等価に評価可能な\ `スカラー型`_\ またはオブジェクト integer `integer値`_\ と等価に評価可能な\ `スカラー型`_ float `float値`_\ と等価に評価可能な\ `スカラー型`_ - array ``ArrayAccess``\ 、\ ``Traversable``\ そして\ ``Countable``\ を実装しているインスタンス + array ``ArrayAccess``\ 、\ ``Traversable``\ および\ ``Countable``\ を実装しているインスタンス ``ArrayAccess`` array ``Traversable`` array ``Countable`` array @@ -327,4 +327,4 @@ protectedメソッドの削除 Yes Yes .. _integer値: http://www.php.net/manual/ja/function.intval.php .. _float値: http://www.php.net/manual/ja/function.floatval.php -.. 2014/04/25 issei-m 6c1ded9af043f1711d6349db91711b2e5fc33bb4 +.. 2014/04/30 issei-m 6c1ded9af043f1711d6349db91711b2e5fc33bb4