From 2c5e5b4007d3d6d661853f62920c1ec396a6859e Mon Sep 17 00:00:00 2001 From: Nobuo Kihara Date: Wed, 14 Mar 2018 17:15:28 +0900 Subject: [PATCH 1/2] docs/internals-ja 2018-03 updates --- docs/internals-ja/README.md | 6 ++ docs/internals-ja/bc.md | 152 ++++++++++++++++++++++++++++++++++ docs/internals-ja/design-decisions.md | 3 + docs/internals-ja/git-workflow.md | 4 +- docs/internals-ja/release.md | 8 +- docs/internals-ja/versions.md | 31 ++++--- 6 files changed, 181 insertions(+), 23 deletions(-) create mode 100644 docs/internals-ja/bc.md diff --git a/docs/internals-ja/README.md b/docs/internals-ja/README.md index 737165d..446f038 100644 --- a/docs/internals-ja/README.md +++ b/docs/internals-ja/README.md @@ -33,6 +33,7 @@ Yii 開発者ドキュメント - [プロジェクトの編成](project-organization.md) - [Yii のバージョニング](versions.md) +- [後方互換性](bc.md) - [新しいバージョンのリリース](release.md) その他 @@ -41,3 +42,8 @@ Yii 開発者ドキュメント ### 例外の階層 ![Yii フレームワークの例外階層](exception_hierarchy.png) + +### データベースのテスト + +[こちら](https://gist.github.com/sergeymakinen/0696a5952f160ea28d7b64c3adfecf6f) に、 +Yii がサポートする全てのデータベースのためのテスト環境構成があります。 diff --git a/docs/internals-ja/bc.md b/docs/internals-ja/bc.md new file mode 100644 index 0000000..d67c6b5 --- /dev/null +++ b/docs/internals-ja/bc.md @@ -0,0 +1,152 @@ +# Backwards Compatibility + +We're strictly not breaking backwards compatibility in patch releases such as `2.x.y.Z` and trying to avoid had to fix +backwards incompatible changes in minor releases such as `2.x.Y`. + +Check [Yii Versioning](versions.md) to learn about version numbering. + +## Usage + +### Interfaces + +Use case | BC? +---------|---- +Type hint with the interface | Yes +Call the interface method | Yes +**Implement the interface and...** | +Implement method | Yes +Add argument to method implemented | Yes +Add default value to an argument | Yes + +### Classes + +Use case | BC? +---------|---- +Type hint with the class | Yes +Create a new instance | Yes +Extend the class | Yes +Access a public property | Yes +Call a public method | Yes +**Extend the class and...** | +Access a protected property | Yes +Call a protected method | Yes +Override a public property | Yes +Override a protected property | Yes +Override a public method | Yes +Override a protected method | Yes +Add a new property | No +Add a new method | No +Add an argument to an overridden method | Yes +Add a default value to an argument | Yes +Call a private method (via Reflection) | No +Access a private property (via Reflection) | No + + +## Development + +### Changing interfaces + +Type of change | BC? +---------------|---- +Remove | No +Change name or namespace | No +Add parent interface | Yes if no new methods are added +Remove parent interface | No +**Interface methods** | +Add method | No +Remove method | No +Change name | No +Move to parent interface | Yes +Add argument without a default value | No +Add argument with a default value | No +Remove argument | Yes (only last ones) +Add default value to an argument | No +Remove default value of an argument | No +Add type hint to an argument | No +Remove type hint of an argument | No +Change argument type | No +Change return type | No +**Constants** | +Add constant | Yes +Remove constant | No +Change value of a constant | Yes except objects that are likely to be serialized. Mandatory to document in UPGRADE.md. + +### Classes + +Type of change | BC? +---------------|---- +Remove | No +Make final | No +Make abstract | No +Change name or namespace | No +Change parent class | Yes but original parent class must remain an ancestor of the class. +Add interface | Yes +Remove interface | No +**Public Properties** | +Add public property | Yes +Remove public property | No +Reduce visibility | No +Move to parent class | Yes +**Protected Properties** | +Add protected property | Yes +Remove protected property | No +Reduce visibility | No +Move to parent class | Yes +**Private Properties** | +Add private property | Yes +Remove private property | Yes +**Constructors** | +Remove constructor | No +Reduce visibility of a public constructor | No +Reduce visibility of a protected constructor | No +Move to parent class | Yes +**Public Methods** | +Add public method | Yes +Remove public method | No +Change name | No +Reduce visibility | No +Move to parent class | Yes +Add argument without a default value | No +Add argument with a default value | No +Remove arguments | Yes, only last ones +Add default value to an argument | No +Remove default value of an argument | No +Add type hint to an argument | No +Remove type hint of an argument | No +Change argument type | No +Change return type | No +**Protected Methods** | +Add protected method | Yes +Remove protected method | No +Change name | No +Reduce visibility | No +Move to parent class | Yes +Add argument without a default value | No +Add argument with a default value | No +Remove arguments | Yes, only last ones +Add default value to an argument | No +Remove default value of an argument | No +Add type hint to an argument | No +Remove type hint of an argument | No +Change argument type | No +Change return type | No +**Private Methods** | +Add private method | Yes +Remove private method | Yes +Change name | Yes +Add argument without a default value | Yes +Add argument with a default value | Yes +Remove argument | Yes +Add default value to an argument | Yes +Remove default value of an argument | Yes +Add type hint to an argument | Yes +Remove type hint of an argument | Yes +Change argument type | Yes +Change return type | Yes +**Static Methods** | +Turn non static into static | No +Turn static into non static | No +**Constants** | +Add constant | Yes +Remove constant | No +Change value of a constant | Yes except objects that are likely to be serialized. Mandatory to document in UPGRADE.md. \ No newline at end of file diff --git a/docs/internals-ja/design-decisions.md b/docs/internals-ja/design-decisions.md index 617bbfd..5a974b6 100644 --- a/docs/internals-ja/design-decisions.md +++ b/docs/internals-ja/design-decisions.md @@ -27,3 +27,6 @@ 7. **セッターメソッドチェイニング** は、意味のある値を返すメソッドがそのクラスに存在する場合は、避けるべきである。 チェイニングは、クラスがビルダーであり、全てのセッターが内部状態を修正するものである場合にサポートされうる。 https://github.com/yiisoft/yii2/issues/13026 +8. ローカルな try-catch の替りに **グローバルな例外/エラーハンドラ** が使われる。 + なぜなら、その方が、ブートストラップなどのように `run()` メソッドのスコープ外で発生するデストラクタなど全てのものをキャッチする点において信頼性が高いからである。 + [#14348](https://github.com/yiisoft/yii2/issues/14348) を参照。 diff --git a/docs/internals-ja/git-workflow.md b/docs/internals-ja/git-workflow.md index bd565e3..ca93c11 100644 --- a/docs/internals-ja/git-workflow.md +++ b/docs/internals-ja/git-workflow.md @@ -113,10 +113,10 @@ php build/build dev/ext > 小さな変更や、ドキュメントの問題、または単純な修正については、課題を作成する必要はありません。 それらについては、プルリクエストだけで十分です。 -### 2. メインの Yii ブランチから最新のコードをフェッチする +### 2. メインの Yii ブランチから最新のコードをプルする ``` -git fetch upstream +git pull upstream ``` 最新のコードに対して作業することを保証するために、すべての新しい寄稿においてこのステップから作業を開始すべきです。 diff --git a/docs/internals-ja/release.md b/docs/internals-ja/release.md index 248efcc..0320725 100644 --- a/docs/internals-ja/release.md +++ b/docs/internals-ja/release.md @@ -50,13 +50,13 @@ フレームワークのリリースの作成では、下記のコマンドの実行します (アプリケーションは常にフレームワークと一緒にリリースされます)。 - ./build release framework - ./build release app-basic - ./build release app-advanced + ./build/build release framework + ./build/build release app-basic + ./build/build release app-advanced エクステンションのリリースの作成では、実行するコマンドは一つだけです (例えば、redis なら) - ./build release redis + ./build/build release redis リリースコマンドは、デフォルトでは、現在チェックアウトされているブランチを元に新しいマイナーバージョンをリリースします。 デフォルトと異なるバージョンをリリースするためには、`--version` オプションを使ってバージョンを指定する必要があります。例えば、 diff --git a/docs/internals-ja/versions.md b/docs/internals-ja/versions.md index 4d0b0bd..635e8d8 100644 --- a/docs/internals-ja/versions.md +++ b/docs/internals-ja/versions.md @@ -2,13 +2,11 @@ Yii バージョン規約 ================== この文書は Yii のバージョン付与ポリシーを要約するものです。 -私たちの現在のバージョン付与戦略は、[ferver](https://github.com/jonathanong/ferver) によって記述されているものです。 -私たちはこれを [Semantic Versioning](http://semver.org/) より現実的で合理的であると考えます -(詳細については [#7408](https://github.com/yiisoft/yii2/issues/7408) を参照してください)。 +私たちの現在のバージョン付与戦略は、[Semantic Versioning](http://semver.org/) の一変種です。 -コア開発者チームの内部では、2.0.x リリースを 100% 後方互換に保つことが重要であることが、何度も強調されました。 -しかし、これは理想としての計画です。 -ferver の記事は、Semantic Versioning を使っても使わなくても、これが現実には達成が困難な計画であることを示す現実世界の例を示しています。 +コア開発者チームの内部では、2.0.x リリースを後方互換に保つことが重要であることが、何度も強調されました。 +しかし、これは理想としての計画です。現実の世界では達成することは困難です。 +後方互換性とは何であるかについての詳細は、[後方互換性](bc.md) を参照して下さい。 要約すれば、Yii 2 に対する私たちのバージョン付与ポリシーは次のようになります。 @@ -33,10 +31,10 @@ ferver の記事は、Semantic Versioning を使っても使わなくても、 ## `2.x.Y`: マイナーリリース -100% 後方互換であるべき、パッチリリースです。 +ほぼ後方互換であるマイナーリリースです。 理想的には、後方互換性を損なわない変更だけを含ませたいと私たちは望んでいます。 -しかし、100% の後方互換性を常に保つことは不可能ですので、アップグレードに関するノートが `UPGRADE.md` に記録されます。 -実際には、2.0.x はより頻繁にリリースされており、また、小さな機能改良をも追加して、ユーザが新機能をより早く享受できるようにしています。 +しかし、すべてを 100% 後方互換に保つことが常に可能である訳ではありませんので、アップグレードに関するノートが `UPGRADE.md` に記録されます。 +実際の運用では、2.0.x はより頻繁にリリースされるので、小さな機能改良の追加も行って、ユーザが新機能をより早く享受できるようにしています。 * 主としてバグ修正と小さな機能強化を含む。 * 大きな機能拡張や修正はしない。 @@ -50,13 +48,13 @@ ferver の記事は、Semantic Versioning を使っても使わなくても、 バグ修正のみを含む、100% 後方互換であるべき、パッチリリースです。 ニュースによる広報やプロジェクトサイトのアップデートはしません (ただし、重大な/セキュリティの問題についての修正を含む場合は、別です)。 -このリリースのプロセスはほぼ自動的に実行されます。 +このリリースのプロセスはほぼ自動化されています。 -* バグ修正のみを含む。機能追加はしない。 -* 不安無しのアップグレードを保証するために、100% 後方互換でなければならない。唯一の例外はセキュリティ問題で、その場合は後方互換性が破られることもある。 -* リリースのサイクルは1～2週間程度。 -* プレリリース (alpha, beta, RC) は不要。 -* リリース時にマスターブランチにマージバックされなければならない。 +* バグ修正のみを含み、機能追加はしない +* 不安無しのアップグレードを保証するために、100% 後方互換でなければならない。唯一の例外はセキュリティ問題で、その場合は後方互換性が破られることもある +* リリースのサイクルは1～2週間程度 +* プレリリース (alpha, beta, RC) は不要 +* リリース時にマスターブランチにマージバックされなければならない ## ブランチ規約 @@ -76,8 +74,7 @@ ferver の記事は、Semantic Versioning を使っても使わなくても、 ## リリース -Yii 2 フレームワークと公式エクステンションのプロジェクトは、ともに、上述のバージョン規約およびブランチ規約に従います。 -ただし、フレームワークと公式エクステンションのプロジェクトは、お互いに独立にリリースされます。 +フレームワークと公式エクステンションのプロジェクトは、お互いに独立にリリースされます。 すなわち、すなわち、フレームワークとエクステンションの間で、バージョン番号が異なることが予想されます。 アプリケーションテンプレートは、常に、フレームワークと同時にリリースされます。 From 0831fa2f09286689cb5a8380df145d7d7bd37c76 Mon Sep 17 00:00:00 2001 From: Nobuo Kihara Date: Wed, 14 Mar 2018 23:34:07 +0900 Subject: [PATCH 2/2] translated bc.md to Japanese --- docs/internals-ja/bc.md | 278 ++++++++++++++++++++++++------------------------ 1 file changed, 139 insertions(+), 139 deletions(-) diff --git a/docs/internals-ja/bc.md b/docs/internals-ja/bc.md index d67c6b5..2339fa2 100644 --- a/docs/internals-ja/bc.md +++ b/docs/internals-ja/bc.md @@ -1,152 +1,152 @@ -# Backwards Compatibility +# 後方互換性 -We're strictly not breaking backwards compatibility in patch releases such as `2.x.y.Z` and trying to avoid had to fix -backwards incompatible changes in minor releases such as `2.x.Y`. +私たちは `2.x.y.Z` のようなパッチリリースにおいては厳密に後方互換性を保持するように努めるとともに、 +`2.x.Y` のようなマイナーリリースにおいても修正が必要となるような後方互換性の無い変更を避けるように努めています。 -Check [Yii Versioning](versions.md) to learn about version numbering. +バージョン番号については [Yii バージョン規約](versions.md) を参照して下さい。 -## Usage +## 使用 -### Interfaces +### インターフェイス -Use case | BC? ----------|---- -Type hint with the interface | Yes -Call the interface method | Yes -**Implement the interface and...** | -Implement method | Yes -Add argument to method implemented | Yes -Add default value to an argument | Yes +ユースケース | 後方互換? +-------------|---------- +インターフェイスのタイプヒント | Yes +インターフェイス・メソッドの呼び出し | Yes +**インターフェイスの実装における ...** | +メソッドの実装 | Yes +実装済みメソッドへの引数の追加 | Yes +引数のデフォルト値の追加 | Yes -### Classes +### クラス -Use case | BC? ----------|---- -Type hint with the class | Yes -Create a new instance | Yes -Extend the class | Yes -Access a public property | Yes -Call a public method | Yes -**Extend the class and...** | -Access a protected property | Yes -Call a protected method | Yes -Override a public property | Yes -Override a protected property | Yes -Override a public method | Yes -Override a protected method | Yes -Add a new property | No -Add a new method | No -Add an argument to an overridden method | Yes -Add a default value to an argument | Yes -Call a private method (via Reflection) | No -Access a private property (via Reflection) | No +ユースケース | 後方互換? +-------------|---------- +クラスのタイプヒント | Yes +新しいインスタンスの作成 | Yes +クラスの拡張 | Yes +パブリック・プロパティへのアクセス | Yes +パブリック・メソッドの呼び出し | Yes +**クラスの拡張における ...** | +プロテクト・プロパティへのアクセス | Yes +プロテクト・メソッドの呼び出し | Yes +パブリック・プロパティのオーバーライド | Yes +プロテクト・プロパティのオーバーライド | Yes +パブリック・メソッドのオーバーライド | Yes +プロテクト・メソッドのオーバーライド | Yes +新しいプロパティの追加 | No +新しいメソッドの追加 | No +オーバーライドされたメソッドへの引数の追加 | Yes +引数のデフォルト値の追加 | Yes +プライベート・メソッドの呼び出し(リフレクション経由) | No +プライベート・プロパティへのアクセス(リフレクション経由) | No -## Development +## 開発 -### Changing interfaces +### インターフェイスの変更 -Type of change | BC? ----------------|---- -Remove | No -Change name or namespace | No -Add parent interface | Yes if no new methods are added -Remove parent interface | No -**Interface methods** | -Add method | No -Remove method | No -Change name | No -Move to parent interface | Yes -Add argument without a default value | No -Add argument with a default value | No -Remove argument | Yes (only last ones) -Add default value to an argument | No -Remove default value of an argument | No -Add type hint to an argument | No -Remove type hint of an argument | No -Change argument type | No -Change return type | No -**Constants** | -Add constant | Yes -Remove constant | No -Change value of a constant | Yes except objects that are likely to be serialized. Mandatory to document in UPGRADE.md. +変更のタイプ | 後方互換? +-------------|---------- +削除 | No +名前または名前空間の変更 | No +親のインターフェイスの追加 | 新しいメソッドが追加されなければ Yes +親のインターフェイスの削除 | No +**インターフェイス・メソッド** | +メソッドの追加 | No +メソッドの削除 | No +名前の変更 | No +親のインターフェイスへの移動 | Yes +デフォルト値を持たない引数の追加 | No +デフォルト値を持つ引数の追加 | No +引数の削除 | Yes (末尾の一つまたは複数の引数のみ) +引数のデフォルト値の追加 | No +引数のデフォルト値の削除 | No +引数のタイプヒントの追加 | No +引数のタイプヒントの削除 | No +引数の型の変更 | No +戻り値の型の変更 | No +**定数** | +定数の追加 | Yes +定数の削除 | No +定数の値の変更 | シリアライズされる可能性のあるオブジェクトを除いて Yes。UPGRADE.md への記載が必須 -### Classes +### クラス -Type of change | BC? ----------------|---- -Remove | No -Make final | No -Make abstract | No -Change name or namespace | No -Change parent class | Yes but original parent class must remain an ancestor of the class. -Add interface | Yes -Remove interface | No -**Public Properties** | -Add public property | Yes -Remove public property | No -Reduce visibility | No -Move to parent class | Yes -**Protected Properties** | -Add protected property | Yes -Remove protected property | No -Reduce visibility | No -Move to parent class | Yes -**Private Properties** | -Add private property | Yes -Remove private property | Yes -**Constructors** | -Remove constructor | No -Reduce visibility of a public constructor | No -Reduce visibility of a protected constructor | No -Move to parent class | Yes -**Public Methods** | -Add public method | Yes -Remove public method | No -Change name | No -Reduce visibility | No -Move to parent class | Yes -Add argument without a default value | No -Add argument with a default value | No -Remove arguments | Yes, only last ones -Add default value to an argument | No -Remove default value of an argument | No -Add type hint to an argument | No -Remove type hint of an argument | No -Change argument type | No -Change return type | No -**Protected Methods** | -Add protected method | Yes -Remove protected method | No -Change name | No -Reduce visibility | No -Move to parent class | Yes -Add argument without a default value | No -Add argument with a default value | No -Remove arguments | Yes, only last ones -Add default value to an argument | No -Remove default value of an argument | No -Add type hint to an argument | No -Remove type hint of an argument | No -Change argument type | No -Change return type | No -**Private Methods** | -Add private method | Yes -Remove private method | Yes -Change name | Yes -Add argument without a default value | Yes -Add argument with a default value | Yes -Remove argument | Yes -Add default value to an argument | Yes -Remove default value of an argument | Yes -Add type hint to an argument | Yes -Remove type hint of an argument | Yes -Change argument type | Yes -Change return type | Yes -**Static Methods** | -Turn non static into static | No -Turn static into non static | No -**Constants** | -Add constant | Yes -Remove constant | No -Change value of a constant | Yes except objects that are likely to be serialized. Mandatory to document in UPGRADE.md. \ No newline at end of file +変更のタイプ | 後方互換? +-------------|---------- +削除 | No +final への変更 | No +abstract への変更 | No +名前または名前空間の変更 | No +親クラスの変更 | Yes ただし元の親クラスは祖先クラス(祖父母クラスなど)として残らなければならない +インターフェイスの追加 | Yes +インターフェイスの削除 | No +**パブリック・プロパティ** | +パブリック・プロパティの追加 | Yes +パブリック・プロパティの削除 | No +可視性の低減 | No +親クラスへの移動 | Yes +**プロテクト・プロパティ** | +プロテクト・プロパティの追加 | Yes +プロテクト・プロパティの削除 | No +可視性の低減 | No +親クラスへの移動 | Yes +**プライベート・プロパティ** | +プライベート・プロパティの追加 | Yes +プライベート・プロパティの削除 | Yes +**コンストラクター** | +コンストラクターの削除 | No +パブリック・コンストラクターの可視性低減 | No +プロテクト・コンストラクターの可視性低減 | No +親クラスへの移動 | Yes +**パブリック・メソッド** | +パブリック・メソッドの追加 | Yes +パブリック・メソッドの削除 | No +名前の変更 | No +可視性の低減 | No +親クラスへの移動 | Yes +デフォルト値を持たない引数の追加 | No +デフォルト値を持つ引数の追加 | No +引数の削除 | Yes (末尾の一つまたは複数の引数のみ) +引数のデフォルト値の追加 | No +引数のデフォルト値の削除 | No +引数のタイプヒントの追加 | No +引数のタイプヒントの削除 | No +引数の型の変更 | No +戻り値の型の変更 | No +**プロテクト・メソッド** | +プロテクト・メソッドの追加 | Yes +プロテクト・メソッドの削除 | No +名前の変更 | No +可視性の低減 | No +親クラスへの移動 | Yes +デフォルト値を持たない引数の追加 | No +デフォルト値を持つ引数の追加 | No +引数の削除 | Yes (末尾の一つまたは複数の引数のみ) +引数のデフォルト値の追加 | No +引数のデフォルト値の削除 | No +引数のタイプヒントの追加 | No +引数のタイプヒントの削除 | No +引数の型の変更 | No +戻り値の型の変更 | No +**プライベート・メソッド** | +プライベート・メソッドの追加 | Yes +プライベート・メソッドの削除 | Yes +名前の変更 | Yes +デフォルト値を持たない引数の追加 | Yes +デフォルト値を持つ引数の追加 | Yes +引数の削除 | Yes +引数のデフォルト値の追加 | Yes +引数のデフォルト値の削除 | Yes +引数のタイプヒントの追加 | Yes +引数のタイプヒントの削除 | Yes +引数の方の変更 | Yes +戻り値の型の変更 | Yes +**スタティック・メソッド** | +非スタティックなメソッドのスタティックへの変更 | No +スタティックなメソッドの非スタティックへの変更 | No +**定数** | +定数の追加 | Yes +定数の削除 | No +定数の値の変更 | シリアライズされる可能性のあるオブジェクトを除いて Yes。UPGRADE.md への記載が必須