docs/internals-ja updated [ci skip] (#13532)

docs/internals-ja/automation.md

@@ -9,12 +9,15 @@ Yii の開発に取り組む際に、自動化できるタスクがいくつか
 - クラスファイルの中の、ゲッターとセッターによって導入されるプロパティを記述する `@property` 注釈の生成。
   `./build/build php-doc/property` を実行して注釈を更新してください。
 
-- コードスタイルと phpdoc コメントの些細な問題の修正。
+- コードスタイルと phpdoc コメントの細かい問題の修正。
   `./build/build php-doc/fix` を実行して修正してください。
   このコマンドは完璧なものではないため、望ましくない変更があるかもしれませんので、コミットする前に変更点をチェックしてください。
   `git add -p` を使って変更をレビューすることが出来ます。
 
-- Mime 型マジックファイル (`framework/helpers/mimeTypes.php`) の Apache HTTPd レポジトリによる更新。
+- Mime タイプマジックファイル (`framework/helpers/mimeTypes.php`) の Apache HTTPd レポジトリによる更新。
   `./build/build mime-type` を実行してファイルを更新して下さい。
 
-上記のコマンドの全てが [release process]() に含まれています。これらをリリースの間に実行しても構いませんが、必要ではありません。
+- CHANGELOG ファイルのエントリの出現順序は、`./build/build release/sort-changelog framework`
+を実行することで更新することが出来ます。
+
+上記のコマンドの全てが [リリースの工程]() に含まれています。これらをリリースとリリースの間に実行しても構いませんが、必要ではありません。

docs/internals-ja/core-code-style.md

@@ -143,11 +143,31 @@ class Foo
 }
 ```
 
-### 4.4 Doc ブロック
+### 4.4 PHPDoc ブロック
+
+ - `@param`、`@var`、`@property` および `@return` は `bool`、`int`、`string`、`array` または `null` として型を宣言しなければなりません。
+   `Model` または `ActiveRecord` のようなクラス名を使うことも出来ます。
+ - 型付きの配列に対しては `ClassName[]` を使います。
+ - PHPDoc の最初の行には、メソッドの目的を記述しなければなりません。
+ - メソッドが何かをチェックする (たとえば、`isActive`, `hasClass` など) ものである場合は、
+   最初の行は `Checks whether` で始まらなければなりません。
+ - `@return` は、厳密に何が返されるのかを明示的に記述しなければなりません。
+
+```php
+/**
+ * Checks whether the IP is in subnet range
+ *
+ * @param string $ip an IPv4 or IPv6 address
+ * @param int $cidr the CIDR lendth
+ * @param string $range subnet in CIDR format e.g. `10.0.0.0/8` or `2001:af::/64`
+ * @return bool whether the IP is in subnet range
+ */
+ private function inRange($ip, $cidr, $range)
+ {
+   // ...
+ }
+```
 
-`@param`、`@var`、`@property` および `@return` は `bool`、`int`、`string`、`array` または `null` として型を宣言しなければなりません。
-`Model` または `ActiveRecord` のようなクラス名を使うことも出来ます。
-型付きの配列に対しては `ClassName[]` を使います。
 
 ### 4.5 コンストラクタ
 

docs/internals-ja/design-decisions.md

@@ -23,3 +23,7 @@
    unsigned の場合、32 bit システムでは、文字列を使って表現しなければならなくなる。
    また、unsigned int はサイズを倍にするとはいうものの、そのような広大な数値空間を必要とするテーブルを持っている場合は、unsigned に頼るより bigint または mediumint を使用する方が安全である。
    <https://github.com/yiisoft/yii/pull/1923#issuecomment-11881967>
+6. [ヘルパか、独立した非スタティックなクラスか](https://github.com/yiisoft/yii2/pull/12661#issuecomment-251599463)
+7. **セッターメソッドチェイニング** は、意味のある値を返すメソッドがそのクラスに存在する場合は、避けるべきである。
+   チェイニングは、クラスがビルダーであり、全てのセッターが内部状態を修正するものである場合にサポートされうる。
+   https://github.com/yiisoft/yii2/issues/13026

docs/internals-ja/git-workflow.md

@@ -1,8 +1,8 @@
 Yii 2 寄稿者のための Git ワークフロー
 =====================================
 
-Yii の開発に寄稿したい、ですって? すばらしい! 
-ただし、あなたの修正案が速やかに採用されるチャンスを増やすために、以下のステップを踏むようにしてください。
+で、Yii の開発に貢献したい、と。すばらしい。 
+でも、あなたの修正案が速やかに採用されるチャンスを増やすために、以下のステップを踏むようにしてください。
 あなたが git と github については初めてだという場合は、最初に [github help](http://help.github.com/) や [try git](https://try.github.com) を精査したり、[git internal data model](http://nfarina.com/post/9868516270/git-is-simpler) についていくらか学習したりする必要があるかもしれません。
 
 あなたの開発環境を準備する
@@ -19,6 +19,8 @@ git clone git@github.com:YOUR-GITHUB-USERNAME/yii2.git
 
 Linux において、GitHub で GIT を設定するのに問題が生じたり、"Permission Denied (publickey)" のようなエラーが発生したりする場合は、[setup your GIT installation to work with GitHub](http://help.github.com/linux-set-up-git/) に従ってください。
 
+> Tip: あなたが Git に精通していない場合は、素晴らしい無料の [プロ Git ブック](https://git-scm.com/book/en/v2) を読むことをお勧めします。
+
 ### 2. メインの Yii リポジトリを "upstream" という名前でリモートとして追加する
 
 Yii をクローンしたディレクトリ、通常は "yii2" に入って、以下のコマンドを打ち込みます。
@@ -31,18 +33,26 @@ git remote add upstream git://github.com/yiisoft/yii2.git
 
 以下のステップは、翻訳またはドキュメントだけに取り組みたい場合は、必要ではありません。
 
-- `composer update` を実行して、依存パッケージをインストールします ([composer をグローバルにインストール](https://getcomposer.org/doc/00-intro.md#globally) したものと仮定しています)。
+- `composer install` を実行して、依存パッケージをインストールします ([composer をグローバルにインストール](https://getcomposer.org/doc/00-intro.md#globally) したものと仮定しています)。
 
 > Note: `Problem 1 The requested package bower-asset/jquery could not be found in any version, there may be a typo in the package name.` というようなエラーが生ずる場合は、`composer global require "fxp/composer-asset-plugin:^1.2.0"` を実行する必要があります。
+JavaScript を扱おうとしている場合は、
+
+- `npm install` を実行して JavaScript テストツール群とその依存ライブラリをインストールします
+([Node.js と NPM のインストール](https://nodejs.org/en/download/package-manager/) は完了しているものとします)。
+
+> Note: JavaScript のテストが依存している [jsdom](https://github.com/tmpvar/jsdom) ライブラリは、Node.js 4 以降を必要とします。
+  Node.js 6 または 7 を使用することをより強く推奨します。
 
-- `php build/build dev/app basic` を実行して、ベーシックアプリケーションをクローンし、その依存パッケージをインストールします。
+  - `php build/build dev/app basic <fork>` を実行し、ベーシックアプリケーションをクローンし、ベーシックアプリケーションのための composer 依存パッケージをインストールします
+  ここで `<fork>` は、`git@github.com:my_nickname/yii2-app-basic.git` のような、あなたのレポジトリのフォークの URL です。
+  あなたがコアフレームワークの貢献者である場合は、フォークの指定を省略しても構いません。
   このコマンドは外部 composer パッケージは通常どおりインストールしますが、yii2 レポジトリは現在チェックアウトされているものをリンクします。
   これで、インストールされる全てのコードについて、一つのインスタンスを持つことになります。
   
-  必要であれば、アドバンストアプリケーションについても同様にします: `php build/build dev/app advanced`。
+  必要であれば、アドバンストアプリケーションについても同様にします: `php build/build dev/app advanced <fork>`。
   
-  このコマンドは後日、依存パッケージを更新するためにも使用されます。
-  このコマンドは内部的に `composer update` を実行します。
+  このコマンドは後日、依存パッケージを更新するためにも使用されます。このコマンドは内部的に `composer update` を実行します。
 
 > Note: デフォルトの git レポジトリの Url を使うため、SSH 経由で github からクローンすることになります。
 > `build` コマンドに `--useHttp` フラグを追加すれば、代りに HTTP を使うことが出来ます。
@@ -63,20 +73,29 @@ phpunit をグローバルにインストールしていない場合は、代り
 例えば、バリデータと redis のためのテストだけを走らせるためには、`phpunit --group=validators,redis` とします。
 利用できるグループのリストを取得するためには、`phpunit --list-groups` を実行してください。
 
+JavaScript の単体テストは、レポジトリのルートディレクトリで `npm test` を走らせることによって実行することが出来ます。
+
+> Note: タイムアウトエラー、例えば `Error: timeout of 2000ms exceeded. Ensure the done() callback is being called in this test.` になる場合は、
+  タイムアウトになる時間を延ばすことが出来ます。
+  `npm test -- --timeout 30000`
+  (`--` を忘れないように。追加の引数を渡すために必要です)。
+
 ### エクステンション
 
 エクステンションに取り組むためには、エクステンションのレポジトリをクローンする必要があります。
 私たちは、あなたに代ってそれをするコマンドを作っています。
 
 ```
-php build/build dev/ext <extension-name>
+php build/build dev/ext <extension-name> <fork>
 ```
 
 ここで `<extension-name>` がエクステンションの名前、例えば `redis` です。
+そして `<fork>` は、`git@github.com:my_nickname/yii2-redis.git` のような、あなたのエクステンションのフォークの URL です。
+あなたがコアフレームワークの貢献者である場合は、フォークの指定を省略しても構いません。
 
 エクステンションをアプリケーションテンプレートのどちらかでテストしたい場合は、通常そうするように、アプリケーションの `composer.json` にそれを追加するだけです。
-例えば、ベーシックアプリケーションの `require` セクションに `"yiisoft/yii2-redis": "*"` を追加します。
-`php build/build dev/app basic` を実行すると、エクステンションとその依存パッケージがインストールされ、`extensions/redis` に対するシンボリックリンクが作成されます。
+例えば、ベーシックアプリケーションの `require` セクションに `"yiisoft/yii2-redis": "~2.0.0"` を追加します。
+`php build/build dev/app basic <fork>` を実行すると、エクステンションとその依存パッケージがインストールされ、`extensions/redis` に対するシンボリックリンクが作成されます。
 こうすることで、composer の vendor ディレクトリではなく、直接に yii2 のレポジトリで作業をすることが出来るようになります。
 
 > Note: デフォルトの git レポジトリの Url を使うため、SSH 経由で github からクローンすることになります。

docs/internals-ja/versions.md

@@ -6,9 +6,9 @@ Yii バージョン規約
 私たちはこれを [Semantic Versioning](http://semver.org/) より現実的で合理的であると考えます
 (詳細については [#7408](https://github.com/yiisoft/yii2/issues/7408) を参照してください)。
 
-コア開発者チームの内部では、2.0.x リリースを 100% 後方互換に保つことが重要であることが、何度かに渡って強調されました。
+コア開発者チームの内部では、2.0.x リリースを 100% 後方互換に保つことが重要であることが、何度も強調されました。
 しかし、これは理想としての計画です。
-ferver の記事は、Semantic Versioning を使おうが使うまいが、これが現実には達成が困難な計画であることを示す現実世界の実例を示しています。
+ferver の記事は、Semantic Versioning を使っても使わなくても、これが現実には達成が困難な計画であることを示す現実世界の例を示しています。
 
 要約すれば、Yii 2 に対する私たちのバージョン付与ポリシーは次のようになります。