Commit 8183ae72 by Nobuo Kihara

docs/internals-ja/* - revised [ci skip]

parent 87c002d5
...@@ -2,7 +2,7 @@ Yii2 繧ウ繧「繝輔Ξ繝シ繝繝ッ繝シ繧ッ縺ョ繧ウ繝シ繝峨せ繧ソ繧、繝ォ ...@@ -2,7 +2,7 @@ Yii2 繧ウ繧「繝輔Ξ繝シ繝繝ッ繝シ繧ッ縺ョ繧ウ繝シ繝峨せ繧ソ繧、繝ォ
======================================= =======================================
下記のコードスタイルが Yii 2.x コアと公式エクステンションの開発に用いられています。 下記のコードスタイルが Yii 2.x コアと公式エクステンションの開発に用いられています。
コアに対してプルリクエストをしたいときは、これを使用することを考慮してください。 コアに対してコードをプルリクエストをしたいときは、これを使用することを考慮してください。
私たちは、あなたが自分のアプリケーションにこのコードスタイルを使うことを強制するものではありません。 私たちは、あなたが自分のアプリケーションにこのコードスタイルを使うことを強制するものではありません。
あなたにとってより良いコードスタイルを自由に選んでください。 あなたにとってより良いコードスタイルを自由に選んでください。
...@@ -22,7 +22,7 @@ Yii2 繧ウ繧「繝輔Ξ繝シ繝繝ッ繝シ繧ッ縺ョ繧ウ繝シ繝峨せ繧ソ繧、繝ォ ...@@ -22,7 +22,7 @@ Yii2 繧ウ繧「繝輔Ξ繝シ繝繝ッ繝シ繧ッ縺ョ繧ウ繝シ繝峨せ繧ソ繧、繝ォ
- クラス内の定数はアンダースコアで区切られた大文字だけで宣言されなければならない。 - クラス内の定数はアンダースコアで区切られた大文字だけで宣言されなければならない。
- メソッド名は `camelCase` で宣言されなければならない。 - メソッド名は `camelCase` で宣言されなければならない。
- プロパティ名は `camelCase` で宣言されなければならない。 - プロパティ名は `camelCase` で宣言されなければならない。
- プロパティ名は private である場合はアンダースコアで開始しなければならない。 - プロパティ名は private である場合はアンダースコアで始まらなければならない。
- `else if` ではなく常に `elseif` を使用すること。 - `else if` ではなく常に `elseif` を使用すること。
2. ファイル 2. ファイル
...@@ -30,9 +30,9 @@ Yii2 繧ウ繧「繝輔Ξ繝シ繝繝ッ繝シ繧ッ縺ョ繧ウ繝シ繝峨せ繧ソ繧、繝ォ ...@@ -30,9 +30,9 @@ Yii2 繧ウ繧「繝輔Ξ繝シ繝繝ッ繝シ繧ッ縺ョ繧ウ繝シ繝峨せ繧ソ繧、繝ォ
### 2.1. PHP タグ ### 2.1. PHP タグ
- PHP コードは `<?php ?>` または `<?=` タグを使わなければなりません。他のタグ、例えば `<?` は使ってはなりません。 - PHP コードは `<?php ?>` または `<?=` タグを使わなければなりません。他のタグの変種、例えば `<?` を使ってはなりません。
- ファイルが PHP コードのみを含む場合は、末尾の `?>` を含むべきではありません。 - ファイルが PHP コードのみを含む場合は、末尾の `?>` を含むべきではありません。
- 各行の末尾に空白を追加しないこと。 - 各行の末尾に空白を追加してはいけません。
- PHP コードを含む全てのファイルの名前は `.php` という拡張子で終るべきです。 - PHP コードを含む全てのファイルの名前は `.php` という拡張子で終るべきです。
### 2.2. 文字エンコーディング ### 2.2. 文字エンコーディング
...@@ -51,26 +51,26 @@ PHP 繧ウ繝シ繝峨 BOM 辟。縺励 UTF-8 縺ョ縺ソ繧剃スソ繧上↑縺代l縺ー縺ェ繧翫∪縺帙s ...@@ -51,26 +51,26 @@ PHP 繧ウ繝シ繝峨 BOM 辟。縺励 UTF-8 縺ョ縺ソ繧剃スソ繧上↑縺代l縺ー縺ェ繧翫∪縺帙s
- クラスは `CamelCase` で命名されなければなりません。 - クラスは `CamelCase` で命名されなければなりません。
- 中括弧は常にクラス名の下の行に書かれるべきです。 - 中括弧は常にクラス名の下の行に書かれるべきです。
- 全てのクラスは PHPDoc に従ったドキュメンテーションブロックを持たなければなりません。 - 全てのクラスは PHPDoc に従ったドキュメントブロックを持たなければなりません。
- クラス内のすべてのコードは単一のタブによってインデントされなければなりません。 - クラス内のすべてのコードは単一のタブによってインデントされなければなりません。
- 単一の PHP ファイルにはクラスが一つだけあるべきです。 - 一つの PHP ファイルにはクラスが一つだけあるべきです。
- 全てのクラスは名前空間に属すべきです。 - 全てのクラスは名前空間に属すべきです。
- クラス名はファイル名と一致すべきです。クラスの名前空間はディレクトリ構造と一致すべきです。 - クラス名はファイル名と合致すべきです。クラスの名前空間はディレクトリ構造と合致すべきです。
```php ```php
/** /**
* ドキュメンテーション * ドキュメント
*/ */
class MyClass extends \yii\Object implements MyInterface class MyClass extends \yii\Object implements MyInterface
{ {
// code // コード
} }
``` ```
### 4.1. 定数 ### 4.1. 定数
クラスの定数はアンダースコアで区切られた大文字だけで宣言されなければなりません。 クラスの定数はアンダースコアで区切られた大文字だけで宣言されなければなりません。
例えば: 例えば、
```php ```php
<?php <?php
...@@ -82,17 +82,17 @@ class Foo ...@@ -82,17 +82,17 @@ class Foo
``` ```
### 4.2. プロパティ ### 4.2. プロパティ
- Public なクラスメンバーを宣言するときは `public` キーワードを明示的に指定します。 - Public なクラスメンバを宣言するとき`public` キーワードを明示的に指定します。
- Public および protected な変数はクラスの冒頭で、すべてのメソッドの宣言に先立って宣言されるべきです。 - Public および protected な変数はクラスの冒頭で、すべてのメソッドの宣言に先立って宣言されるべきです。
Private な変数もまたクラスの冒頭で宣言されるべきですが、 Private な変数もまたクラスの冒頭で宣言されるべきですが、
変数がクラスのメソッドのごく一部分にのみ関係する場合は、変数を扱う一群のメソッドの直前に追加してもかまいません。 変数がクラスのメソッドのごく一部分にのみ関係する場合は、変数を扱う一群のメソッドの直前に追加しても構いません。
- クラスにおけるプロパティの宣言の順序は public から始まり、protected、private と続くべきです。 - クラスにおけるプロパティの宣言の順序は public から始まり、protected、private と続くべきです。
- より読みやすいように、プロパティの宣言は空行を挟まずに続け、プロパティ宣言とメソッド宣言のブロック間には2行の空行を挟むべきです。 - より読みやすいように、プロパティの宣言は空行を挟まずに続け、プロパティ宣言とメソッド宣言のブロック間には2行の空行を挟むべきです。
- Private 変数は `$_varName` のように名付けるべきです。 - Private 変数は `$_varName` のように名付けるべきです。
- Public なクラスメンバーとスタンドアロンな変数は、先頭を小文字にした `$camelCase` で名付けるべきです。 - Public なクラスメンバとスタンドアロな変数は、先頭を小文字にした `$camelCase` で名付けるべきです。
- 説明的な名前を使うこと。`$i``$j` のような変数は使わないようにしましょう。 - 説明的な名前を使うこと。`$i``$j` のような変数は使わないようにしましょう。
例えば: 例えば、
```php ```php
<?php <?php
...@@ -109,17 +109,17 @@ class Foo ...@@ -109,17 +109,17 @@ class Foo
- 関数およびメソッドは、先頭を小文字にした `camelCase` で名付けるべきです。 - 関数およびメソッドは、先頭を小文字にした `camelCase` で名付けるべきです。
Functions and methods should be named using `camelCase` with first letter lowercase. Functions and methods should be named using `camelCase` with first letter lowercase.
- 名前は、関数の目的を示す自己説明的なものであるべきです。 - 名前は、関数の目的を示す自己説明的なものであるべきです。
- クラスのメソッドは常に `private``protected` または `public` を使って、可視性を宣言すべきです。`var` は許可されません。 - クラスのメソッドは常に修飾子 `private``protected` または `public` を使って、可視性を宣言すべきです。`var` は許可されません。
- 関数の開始の中括弧は関数宣言の次の行に置くべきです。 - 関数の開始の中括弧は関数宣言の次の行に置くべきです。
~~~ ~~~
/** /**
* ドキュメンテーション * ドキュメント
*/ */
class Foo class Foo
{ {
/** /**
* ドキュメンテーション * ドキュメント
*/ */
public function bar() public function bar()
{ {
...@@ -154,7 +154,7 @@ $config = [ ...@@ -154,7 +154,7 @@ $config = [
]; ];
``` ```
既存の変数の型を変えることは悪い慣行であるとみなされます。本当に必要でない限り、そのようなコードを書かないように努めましょう。 既存の変数の型を変えることは悪い慣行であると見なされます。本当に必要でない限り、そのようなコードを書かないように努めましょう。
```php ```php
...@@ -167,13 +167,13 @@ public function save(Transaction $transaction, $argument2 = 100) ...@@ -167,13 +167,13 @@ public function save(Transaction $transaction, $argument2 = 100)
### 5.2 文字列 ### 5.2 文字列
- 変数およびシングルクォーツを含まない文字列には、シングルクォーツを使います。 - 文字列が変数および一重引用符を含まない場合は、一重引用符を使います。
```php ```php
$str = 'Like this.'; $str = 'Like this.';
``` ```
- 文字列がシングルクォーツを含む場合は、余分なエスケープを避けるためにダブルクォーツを使ってもかまいません。 - 文字列が一重引用符を含む場合は、余計なエスケープを避けるために二重引用符を使ってもかまいません。
#### 変数置換 #### 変数置換
...@@ -206,7 +206,7 @@ $sql = "SELECT *" ...@@ -206,7 +206,7 @@ $sql = "SELECT *"
### 5.3 配列 ### 5.3 配列
配列には、開発者は PHP 5.4 の短縮構文を使用しています。 配列には、私たちは PHP 5.4 の短縮構文を使用しています。
#### 添え字配列 #### 添え字配列
...@@ -218,7 +218,7 @@ $sql = "SELECT *" ...@@ -218,7 +218,7 @@ $sql = "SELECT *"
$arr = [3, 14, 15, 'Yii', 'Framework']; $arr = [3, 14, 15, 'Yii', 'Framework'];
``` ```
一つの行に多すぎる要素がある場合は: 一つの行には多過ぎるほど要素がたくさんある場合は:
```php ```php
$arr = [ $arr = [
...@@ -243,9 +243,9 @@ $config = [ ...@@ -243,9 +243,9 @@ $config = [
- 制御文の条件は括弧の前と後に一つの空白を持たなければなりません。 - 制御文の条件は括弧の前と後に一つの空白を持たなければなりません。
- 括弧の中の演算子は空白によって区切られるべきです。 - 括弧の中の演算子は空白によって区切られるべきです。
- 開始の括弧は同じ行に置きます。 - 開始の中括弧は同じ行に置きます。
- 終了の括弧は新しい行に置きます。 - 終了の中括弧は新しい行に置きます。
- 単一行の文に対しても、常に括弧を使用します。 - 単一行の文に対しても、常に中括弧を使用します。
```php ```php
if ($event === null) { if ($event === null) {
...@@ -263,7 +263,7 @@ if (!$model && null === $event) ...@@ -263,7 +263,7 @@ if (!$model && null === $event)
#### switch #### switch
switch には下記の書式を使用します: switch には下記の書式を使用します。
```php ```php
switch ($this->phpType) { switch ($this->phpType) {
...@@ -297,7 +297,7 @@ doIt('a', [ ...@@ -297,7 +297,7 @@ doIt('a', [
### 5.6 無名関数 (lambda) の宣言 ### 5.6 無名関数 (lambda) の宣言
`function`/`use` トークンと開始括弧の間の空白に注意: `function`/`use` トークンと開始括弧の間の空白に注意してください。
```php ```php
// 良い // 良い
...@@ -308,7 +308,7 @@ $sum = array_reduce($numbers, function ($r, $x) use ($n) { ...@@ -308,7 +308,7 @@ $sum = array_reduce($numbers, function ($r, $x) use ($n) {
return $r; return $r;
}); });
// bad // 悪い
$n = 100; $n = 100;
$mul = array_reduce($numbers, function($r, $x) use($n) { $mul = array_reduce($numbers, function($r, $x) use($n) {
$this->doMagic(); $this->doMagic();
...@@ -317,21 +317,21 @@ $mul = array_reduce($numbers, function($r, $x) use($n) { ...@@ -317,21 +317,21 @@ $mul = array_reduce($numbers, function($r, $x) use($n) {
}); });
``` ```
ドキュメンテーション ドキュメント
-------------------- ------------
- ドキュメンテーションの文法については [phpDoc](http://phpdoc.org/) を参照してください。 - ドキュメントの文法にいては [phpDoc](http://phpdoc.org/) を参照してください。
- ドキュメンテーションの無いコードは許容されません。 - ドキュメントの無いコドは許容されません。
- 全てのクラスファイルは、ファイルレベルの doc ブロックを各ファイルの先頭に持ち、 - 全てのクラスファイルは、ファイルレベルの doc ブロックを各ファイルの先頭に持ち、
クラスレベルの doc ブロックを各クラスの直前に持たなければなりません。 クラスレベルの doc ブロックを各クラスの直前に持たなければなりません。
- メソッドが何も返さないときは `@return` を使う必要はありません。 - メソッドが実際に何も返さないときは `@return` を使う必要はありません。
- `yii\base\Object` から派生するクラスのすべての仮想プロパティは、クラスの doc ブロックで `@property` タグでドキュメントされます。 - `yii\base\Object` から派生するクラスのすべての仮想プロパティは、クラスの doc ブロックで `@property` タグでドキュメントされます。
これらの注釈は、`build` ディレクトリで `./build php-doc` コマンドを走らせることにより、 これらの注釈は、`build` ディレクトリで `./build php-doc` コマンドを走らせることにより、
対応する getter や setter の `@return``@param` タグから自動的に生成されます。 対応する getter や setter の `@return``@param` タグから自動的に生成されます。
getter や setter によって導入されるプロパティに対してドキュメンテーションのメッセージを getter や setter に `@property` タグを追加することによって、
明示的に与えるために `@property` タグを追加することが出来ます。 これらのメソッドによって導入されるプロパティに対してドキュメントのメッセージを明示的に与えることが出来ます。
これは `@return` において記述されているのとは違う説明を与えたい場合に有用です。 これは `@return` で記述れているのとは違う説明を与えたい場合に有用です。
例えば: 下記が一例です。
```php ```php
<?php <?php
...@@ -341,15 +341,14 @@ $mul = array_reduce($numbers, function($r, $x) use($n) { ...@@ -341,15 +341,14 @@ $mul = array_reduce($numbers, function($r, $x) use($n) {
* @property array 全ての属性に対するエラーの配列。エラーが無い場合は空の配列が返される。 * @property array 全ての属性に対するエラーの配列。エラーが無い場合は空の配列が返される。
* 結果は二次元の配列である。詳細な説明は [[getErrors()]] を参照。 * 結果は二次元の配列である。詳細な説明は [[getErrors()]] を参照。
* @return array 全ての属性または特定の属性に対するエラー。エラーが無い場合は空の配列が返される。 * @return array 全ての属性または特定の属性に対するエラー。エラーが無い場合は空の配列が返される。
* 全ての属性に対する配列を返す場合、結果は、下記のように、二次元の配列である: * 全ての属性に対するエラーを返す場合、結果は、下記のような二次元の配列になる。
* ... * ...
*/ */
public function getErrors($attribute = null) public function getErrors($attribute = null)
``` ```
>Note|注意: これ以降読みやすさを考慮してドキュメンテーションの内容を日本語に翻訳していますが >Note|注意: ここでは読みやすさを考慮してドキュメントの内容を日本語に翻訳していますが
コアコードや公式エクステンションに対して寄稿する場合は当然ながらコメントは英語だけを コアコードや公式エクステンションに対して寄稿する場合は当然ながらコメントには英語だけを使う必要があるでしよう
使わなければなりません
#### ファイル #### ファイル
...@@ -407,14 +406,14 @@ public function getEventHandlers($name) ...@@ -407,14 +406,14 @@ public function getEventHandlers($name)
上記の例に見られるように、phpDoc コメントの書式設定には markdown を使っています。 上記の例に見られるように、phpDoc コメントの書式設定には markdown を使っています。
ドキュメンテーションの中でクラス、メソッド、プロパティをクロスリンクするために使う追加の文法があります: ドキュメントの中でクラス、メソッド、プロパティをクロスリンクするために使える追加の文法があります。
- `'[[canSetProperty]] ` は、同じクラス内の `canSetProperty` メソッドまたはプロパティへのクロスリンクを生成します。 - `'[[canSetProperty]] ` は、同じクラス内の `canSetProperty` メソッドまたはプロパティへのクロスリンクを生成します。
- `'[[Component::canSetProperty]]` は、同じ名前空間内の `Component` クラスの `canSetProperty` メソッドへのクロスリンクを生成します。 - `'[[Component::canSetProperty]]` は、同じ名前空間内の `Component` クラスの `canSetProperty` メソッドへのクロスリンクを生成します。
- `'[[yii\base\Component::canSetProperty]]` は、`yii\base` 名前空間の`Component` クラスの `canSetProperty` メソッドへのクロスリンクを生成します。 - `'[[yii\base\Component::canSetProperty]]` は、`yii\base` 名前空間の`Component` クラスの `canSetProperty` メソッドへのクロスリンクを生成します。
- `'[[Component]]` は、同じ名前空間内の `Component` クラスへのクロスリンクを生成します。ここでも、クラス名に名前空間を追加することが可能です。 - `'[[Component]]` は、同じ名前空間内の `Component` クラスへのクロスリンクを生成します。ここでも、クラス名に名前空間を追加することが可能です。
上記のリンクにクラス名やメソッド名以外のラベルを付けるために、次の例で示されている書式を使うことが出来ます: 上記のリンクにクラス名やメソッド名以外のラベルを付けるためには、次の例で示されている文法を使うことが出来ます。
``` ```
... [[header|ヘッダセル]] に表示されているように ... [[header|ヘッダセル]] に表示されているように
...@@ -422,7 +421,7 @@ public function getEventHandlers($name) ...@@ -422,7 +421,7 @@ public function getEventHandlers($name)
`|` の前の部分がメソッド、プロパティ、クラスへの参照であり、`|` の後ろの部分がリンクのラベルです。 `|` の前の部分がメソッド、プロパティ、クラスへの参照であり、`|` の後ろの部分がリンクのラベルです。
下記の書式を使って公式ガイドにリンクすることも可能です: 下記の文法を使ってガイドにリンクすることも可能です:
```markdown ```markdown
[ガイドへのリンク](guide:file-name.md) [ガイドへのリンク](guide:file-name.md)
...@@ -440,11 +439,11 @@ public function getEventHandlers($name) ...@@ -440,11 +439,11 @@ public function getEventHandlers($name)
### `=== []` 対 `empty()` ### `=== []` 対 `empty()`
かの名時は `empty()` を使います。 可能な場合は `empty()` を使います。
### 複数の return ポイント ### 複数の return ポイント
条件のネストが込み入ってきた場合は、早期の return を使います。メソッドが短いものである場合は、特に問題にしません。 条件の入れ子が込み入ってきた場合は、早期の return を使います。メソッドが短いものである場合は、特に問題にしません。
### `self` 対 `static` ### `self` 対 `static`
...@@ -456,7 +455,8 @@ public function getEventHandlers($name) ...@@ -456,7 +455,8 @@ public function getEventHandlers($name)
### 「何かをするな」を示す値 ### 「何かをするな」を示す値
コンポーネントに対して「何かをしない」という設定を許可するプロパティは `false` の値を受け入れるべきです。`null``''`、または `[]` は、そのような値として受け取られるべきではありません。 コンポーネントに対して「何かをしない」という設定を許可するプロパティは `false` の値を受け入れるべきです。
`null``''`、または `[]` がそういう値であると見なされるべきではありません。
### ディレクトリ/名前空間の名前 ### ディレクトリ/名前空間の名前
......
...@@ -2,8 +2,9 @@ Yii 2 蟇ィソ閠縺溘a縺ョ Git 繝ッ繝シ繧ッ繝輔Ο繝シ ...@@ -2,8 +2,9 @@ Yii 2 蟇ィソ閠縺溘a縺ョ 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) についていくらか学習したりする必要があるかもしれません。 あなたが 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) についていくらか学習したりする必要があるかもしれません。
### 1. github で Yii リポジトリを [Fork](http://help.github.com/fork-a-repo/) し、あなたのフォークをあなたの開発環境にクローンする ### 1. github で Yii リポジトリを [Fork](http://help.github.com/fork-a-repo/) し、あなたのフォークをあなたの開発環境にクローンする
...@@ -16,7 +17,7 @@ Linux 縺ォ縺翫>縺ヲ縲;itHub 縺ァ GIT 繧定ィュ螳壹☆繧九縺ォ蝠城。後′逕溘§縺溘j縲 ...@@ -16,7 +17,7 @@ Linux 縺ォ縺翫>縺ヲ縲;itHub 縺ァ GIT 繧定ィュ螳壹☆繧九縺ォ蝠城。後′逕溘§縺溘j縲
### 2. メインの Yii リポジトリを "upstream" という名前でリモートとして追加する ### 2. メインの Yii リポジトリを "upstream" という名前でリモートとして追加する
Yii をクローンしたディレクトリ、すなわち "yii2" に入って、以下のコマンドを打ち込みます: Yii をクローンしたディレクトリ、通常は "yii2" に入ります。そして、以下のコマンドを打ち込みます:
``` ```
git remote add upstream git://github.com/yiisoft/yii2.git git remote add upstream git://github.com/yiisoft/yii2.git
...@@ -24,13 +25,13 @@ git remote add upstream git://github.com/yiisoft/yii2.git ...@@ -24,13 +25,13 @@ git remote add upstream git://github.com/yiisoft/yii2.git
### 3. あなたが取り組んでいる問題が、修正するために著しい努力を要求するものである場合は、それに対する課題(issue)が作成されていることを確認する ### 3. あなたが取り組んでいる問題が、修正するために著しい努力を要求するものである場合は、それに対する課題(issue)が作成されていることを確認する
全ての新機能とバグ修正は、議論とドキュメンテーションのための単一の参照ポイントを提供するために、それに結びつく課題を持つべきです。 全ての新機能とバグ修正は、議論とドキュメントのための単一の参照ポイントを提供るために、それに結びつく課題を持つべきです。
数分間時間を取って、既存の課題リストに目を通し、あなたが寄稿しようとしている問題に合致するものが無いかどうか調べてください。 数分間時間を取って、既存の課題リストに目を通し、あなたが寄稿しようとしている問題に合致するものが無いかどうか調べてください。
もし課題リストにすでに挙っているのを見つけた場合は、その課題にコメントを残して、あなたがその項目について取り組もうとしていることを示してください。 もし課題リストにすでに挙っているのを見つけた場合は、その課題にコメントを残して、あなたがその項目について取り組もうとしていることを示してください。
あなたが取り組もうとしている問題に合致する既存の課題が見つからなかった場合は、新しい課題を作成してください。単純な修正であれば、直接にプルリクエストをしてください。 あなたが取り組もうとしている問題に合致する既存の課題が見つからなかった場合は、新しい課題を作成してください。単純な修正であれば、直接にプルリクエストをしてください。
こうすることで、開発チームはあなたの提案をレビューし、将来にわたって適切なフィードバックを提供することが可能になります。 こうすることで、開発チームはあなたの提案をレビューし、将来にわたって適切なフィードバックを提供することが可能になります。
> 小さな変更や、ドキュメンテーションの問題、または単純な修正については、課題を作成する必要はありません。それらについては、プルリクエストだけで十分です。 > 小さな変更や、ドキュメントの問題、または純な修正については、課題を作成する必要はありません。それらについては、プルリクエストだけで十分です。
### 4. メインの Yii ブランチから最新のコードをフェッチする ### 4. メインの Yii ブランチから最新のコードをフェッチする
...@@ -38,7 +39,7 @@ git remote add upstream git://github.com/yiisoft/yii2.git ...@@ -38,7 +39,7 @@ git remote add upstream git://github.com/yiisoft/yii2.git
git fetch upstream git fetch upstream
``` ```
すべての新しい寄稿において、最新のコードに対して作業することを確実にするために、この作業から開始すべきです。 最新のコードに対して作業することを保証するために、すべての新しい寄稿においてこのステップから作業を開始すべきです。
### 5. 現在の Yii のマスターブランチに基いて、あなたの寄稿のための新しいブランチを作成する ### 5. 現在の Yii のマスターブランチに基いて、あなたの寄稿のための新しいブランチを作成する
...@@ -47,14 +48,14 @@ git fetch upstream ...@@ -47,14 +48,14 @@ git fetch upstream
独立したバグ修正や変更は、各々、それ自身のブランチに入れるべきです。 独立したバグ修正や変更は、各々、それ自身のブランチに入れるべきです。
ブランチの名前は説明的なものにし、あなたのコードが関係する課題の番号で始まるようにしてください。 ブランチの名前は説明的なものにし、あなたのコードが関係する課題の番号で始まるようにしてください。
特定の課題を修正するものでない場合は、番号を省略してください。 特定の課題を修正するものでない場合は、番号を省略してください。
例えば: 例えば、
``` ```
git checkout upstream/master git checkout upstream/master
git checkout -b 999-name-of-your-branch-goes-here git checkout -b 999-name-of-your-branch-goes-here
``` ```
### 6. 魔法を使ってあなたのコードを書く ### 6. あなたの魔法を使って、あなたのコードを書く
動くことを確認してくださいね :) 動くことを確認してくださいね :)
...@@ -65,21 +66,21 @@ git checkout -b 999-name-of-your-branch-goes-here ...@@ -65,21 +66,21 @@ git checkout -b 999-name-of-your-branch-goes-here
CHANGELOG ファイルを編集して、あなたの修正を追加します。 CHANGELOG ファイルを編集して、あなたの修正を追加します。
新しい行は、ファイル冒頭の "Work in progress" 見出しの下に挿入してください。 新しい行は、ファイル冒頭の "Work in progress" 見出しの下に挿入してください。
チェンジログの行は、下記のどちらかのように書いてください: チェンジログの行は、下記のどちらかのように書いてください。
``` ```
Bug #999: バグ修正の内容説明 (あなたの名前) Bug #999: バグ修正の内容説明 (あなたの名前)
Enh #999: 機能拡張の内容説明 (あなたの名前) Enh #999: 機能拡張の内容説明 (あなたの名前)
``` ```
`#999``Bug` または `Enh` が示している課題番号です。 `#999``Bug` または `Enh` が参照している課題番号です。
チェンジログはタイプ(`Bug`, `Enh`)によってグループ化し、課題番号順に並べます。 チェンジログは、タイプ (`Bug`, `Enh`) によってグループ化し、課題番号順に並べます。
非常に小さな修正、すなわち、タイポやドキュメンテーションの修正については、CHANGELOG を更新する必要はありません。 非常に小さな修正、すなわち、タイポやドキュメントの修正については、CHANGELOG を更新する必要はありません。
### 8. 修正をコミットする ### 8. 修正をコミットする
以下のコマンドを使って、コミットしたいファイルや変更を [staging area](http://gitref.org/basic/#add) に追加します: 以下のコマンドを使って、コミットしたいファイルや変更を [staging area](http://gitref.org/basic/#add) に追加します。
``` ```
git add path/to/my/file.php git add path/to/my/file.php
...@@ -87,14 +88,14 @@ git add path/to/my/file.php ...@@ -87,14 +88,14 @@ git add path/to/my/file.php
`-p` オプションを使って、コミットに含める変更を選択することも出来ます。 `-p` オプションを使って、コミットに含める変更を選択することも出来ます。
説明的なコミットメッセージをいれて修正をコミットしてください。 説明的なコミットメッセージを付けて修正をコミットしてください。
github があなたのコミットを自動的にチケットとリンクするように、`#XXX` という書式でチケット番号に言及することを忘れないでください: github があなたのコミットを自動的にチケットとリンクするように、必ず `#XXX` でチケット番号に言及してください。
``` ```
git commit -m "A brief description of this change which fixes #42" git commit -m "#42 を解決する変更の短い説明をここに入れる"
``` ```
### 9. 最新の Yii コードを upstream からあなたのブランチに pull する ### 9. 最新の Yii コードを upstream からあなたのブランチにプルする
``` ```
git pull upstream master git pull upstream master
...@@ -104,7 +105,7 @@ git pull upstream master ...@@ -104,7 +105,7 @@ git pull upstream master
もし何かマージ衝突がある場合は、ここでそれを修正してから再度変更をコミットすべきです。 もし何かマージ衝突がある場合は、ここでそれを修正してから再度変更をコミットすべきです。
こうすると、Yii 開発チームがワンクリックであなたの変更をマージすることが確実に出来るようになります。 こうすると、Yii 開発チームがワンクリックであなたの変更をマージすることが確実に出来るようになります。
### 10. 衝突をすべて解消したら、あなたのコードを github にプッシュする ### 10. 衝突をすべて解決したら、あなたのコードを github にプッシュする
``` ```
git push -u origin 999-name-of-your-branch-goes-here git push -u origin 999-name-of-your-branch-goes-here
...@@ -118,11 +119,11 @@ git push -u origin 999-name-of-your-branch-goes-here ...@@ -118,11 +119,11 @@ git push -u origin 999-name-of-your-branch-goes-here
github 上のあなたのリポジトリに入って、"Pull Request" をクリックし、右側にあるブランチを選び、コメントボックスにもう少し詳細を記述します。 github 上のあなたのリポジトリに入って、"Pull Request" をクリックし、右側にあるブランチを選び、コメントボックスにもう少し詳細を記述します。
プルリクエストを課題とリンクさせるために、プルコメントのどこかに `#999` という書式で課題番号を記載します。 プルリクエストを課題とリンクさせるために、プルコメントのどこかに `#999` という書式で課題番号を記載します。
> 各プルリクエストは単一の課題を解決すべきものであることに注意してください。 > 全てのプルリクエストはそれぞれ一つの課題を解決すべきものであることに注意してください。
### 12. 誰かがあなたのコードをレビューする ### 12. 誰かがあなたのコードをレビューする
誰かがあなたのコードをレビューします。あなたは修正を求められるかも知れません。その場合は、ステップ #6 に戻ってください 誰かがあなたのコードをレビューします。あなたは修正を求められるかも知れません。その場合は、ステップ #6 に戻ってください
(現在のプルリクエストが open である限りは、別の新しいプルリクエストをする必要はありません)。 (現在のプルリクエストが open である限りは、別の新しいプルリクエストをする必要はありません)。
あなたのコードが受け入れられた場合は、コードはメインブランチにマージされて、次回の Yii のリリースの一部となります。 あなたのコードが受け入れられた場合は、コードはメインブランチにマージされて、次回の Yii のリリースの一部となります。
受け入れられなくても、落胆しないでください。 受け入れられなくても、落胆しないでください。
...@@ -143,16 +144,16 @@ git push origin --delete 999-name-of-your-branch-goes-here ...@@ -143,16 +144,16 @@ git push origin --delete 999-name-of-your-branch-goes-here
退行 (regression) を早期に発見するために、github 上の Yii コードベースへのマージは、すべて [Travis CI](http://travis-ci.org) に取り上げられて、自動化されたテストにかけられます。 退行 (regression) を早期に発見するために、github 上の Yii コードベースへのマージは、すべて [Travis CI](http://travis-ci.org) に取り上げられて、自動化されたテストにかけられます。
コアチームとしては、このサービスに過大な負担をかけたくないために、 コアチームとしては、このサービスに過大な負担をかけたくないために、
以下の場合にはマージの説明に [`[ci skip]`](http://about.travis-ci.org/docs/user/how-to-skip-a-build/) が含まれるようにします。 以下の場合にはマージの説明に [`[ci skip]`](http://about.travis-ci.org/docs/user/how-to-skip-a-build/) が含まれるようにしてください。
すなわち、プルリクエストが: すなわち、プルリクエストが、
* javascript、css または画像ファイルだけに影響する場合 * javascript、css または画像ファイルだけに影響する場合
* ドキュメンテーションを更新する場合 * ドキュメントを更新する場合
* 固定の文字列だけを修正する(例えば、翻訳をアップデートする)場合 * 固定の文字列だけを修正する (例えば、翻訳をアップデートする) 場合
がそうです。 がそうです。
このようにすることによって、そもそもテストによってカバーされない変更に対しては、最初から travis がテストランを開始しないようにしています。 このようにすることによって、そもそもテストによってカバーされない変更に対しては、travis がテストランを開始しないようにすることが出来ます。
### コマンド概要 (上級の寄稿者向け) ### コマンド概要 (上級の寄稿者向け)
......
課題を報告する 課題を報告する
============== ==============
あなたが報告する課題(issue)がより迅速に解決されるように、課題を作成するときには下記のガイドラインに従って下さい: あなたが報告する課題 (issue) がより迅速に解決されるように、課題を作成するときには下記のガイドラインに従って下さい。
* PHP と Yii のバージョン、オペレーティングシステムとウェブサーバのタイプ、および、ブラウザのタイプとバージョンについて、情報を提供してください; * PHP と Yii のバージョン、オペレーティングシステムとウェブサーバのタイプ、および、ブラウザのタイプとバージョンについて、情報を提供してください
* 出来れば、**完全な**エラーのコールスタックを提供して下さい。問題を説明するスクリーンショットは大いに歓迎されます。 * 出来れば、**完全な**エラーのコールスタックを提供して下さい。問題を説明するスクリーンショットは大いに歓迎されます。
* 問題を再現する手順を記述して下さい。問題を再現するコードを提供してくださるならば、なお一層良いでしょう。 * 問題を再現する手順を記述して下さい。問題を再現するコードを提供してくださるならば、なお一層良いでしょう。
......
...@@ -2,40 +2,40 @@ ...@@ -2,40 +2,40 @@
================ ================
Yii は国際的なアプリケーションと開発者にとって役に立つように、数多くの言語に翻訳されています。 Yii は国際的なアプリケーションと開発者にとって役に立つように、数多くの言語に翻訳されています。
貢献が大いに歓迎される主な領域はドキュメンテーションとフレームワークメッセージです。 貢献が大いに歓迎される主な領域はドキュメンとフレームワークメッセージです。
フレームワークメッセージ フレームワークメッセージ
------------------------ ------------------------
フレームワークは二種類のメッセージを持っています: 一つは開発者向けの例外メッセージで、これは決して翻訳されません。 フレームワークは二種類のメッセージを持っています一つは開発者向けの例外メッセージで、これは決して翻訳されません。
もう一つはエンドユーザーが実際に目にする検証エラーのようなメッセージです。 もう一つはエンドユーザーが実際に目にする検証エラーのようなメッセージです。
メッセージの翻訳を開始するためには: メッセージの翻訳を開始するためには:
1. `framework/messages/config.php` をチェックして、あなたの言語が `languages` のリストに挙っていることを確認してください。 1. `framework/messages/config.php` をチェックして、あなたの言語が `languages` のリストに挙っていることを確認してください。
もし挙っていなければ、あなたの言語をそこに追加します(リストをアルファベット順に保つことを忘れないでください)。 もし挙っていなければ、あなたの言語をそこに追加します (リストをアルファベット順に保つことを忘れないでください)。
言語コードの形式は、例えば `ru``zh-CN` のように、[IETF言語タグ](http://ja.wikipedia.org/wiki/IETF%E8%A8%80%E8%AA%9E%E3%82%BF%E3%82%B0) に従うべきです。 言語コードの形式は、例えば `ru``zh-CN` のように、[IETF言語タグ](http://ja.wikipedia.org/wiki/IETF%E8%A8%80%E8%AA%9E%E3%82%BF%E3%82%B0) に従うべきです。
2. `framework` に入って、`yii message/extract messages/config.php` を走らせます。 2. `framework` に入って、`yii message/extract messages/config.php` を走らせます。
3. `framework/messages/your_language/yii.php` のメッセージを翻訳します。ファイルは必ず UTF-8 エンコーディングを使って保存してください。 3. `framework/messages/your_language/yii.php` のメッセージを翻訳します。ファイルは必ず UTF-8 エンコーディングを使って保存してください。
4. [プルリクエスト](https://github.com/yiisoft/yii2/blob/master/docs/internals/git-workflow.md)をします。 4. [プルリクエスト](https://github.com/yiisoft/yii2/blob/master/docs/internals/git-workflow.md) をします。
あなたの翻訳を最新状態に保つために、`yii message/extract messages/config.php` を再び走らせることが出来ます。 あなたの翻訳を最新状態に保つために、`yii message/extract messages/config.php` を再び走らせることが出来ます。
れによって、変更のなかった箇所には触れることなく、自動的にメッセージを再抽出することが出来ます。 のコマンドは、変更のなかった箇所には触れることなく、自動的にメッセージを再抽出してくれます。
翻訳ファイルの中で、配列の各要素は、メッセージ(キー)と翻訳(値)をあらわします。 翻訳ファイルの中で、配列の各要素は、メッセージ(キー)と翻訳(値)をあらわします。
値が空の場合は、メッセージは翻訳されないものと見なされます。 値が空文字列の場合は、メッセージは翻訳されないものと見なされます。
翻訳が不要になったメッセージは、翻訳が一組の '@@' マークで囲まれます。 翻訳が不要になったメッセージは、翻訳が一組の '@@' マークで囲まれます。
メッセージ文字列は複数形書式とともに使うことが出来ます。 メッセージ文字列は複数形書式とともに使うことが出来ます。
詳細はガイドの [国際化](../guide-ja/tutorial-i18n.md) の節を参照してください。 詳細はガイドの [国際化](../guide-ja/tutorial-i18n.md) の節を参照してください。
ドキュメンテーション ドキュメン
-------------------- ------------
ドキュメンテーションの翻訳は `docs/<original>-<language>` の下に置きます。 ドキュメンの翻訳は `docs/<original>-<language>` の下に置きます。
ここで `<original>` は、`guide``internals` などの元の文書の名前であり、`<language>` は文書の翻訳先の言語コードです。 ここで `<original>` は、`guide``internals` などの元の文書の名前であり、`<language>` は文書の翻訳先の言語コードです。
例えば、ロシア語のガイドの翻訳は `docs/guide-ru` です。 例えば、ロシア語のガイドの翻訳は `docs/guide-ru` です。
初期の仕事が完了した後は、最新の翻訳以後に変更された元の文書の箇所を取得するために、`build` ディレクトリにある専用のコマンドを使うことが出来ます: 初期の仕事が完了した後は、最新の翻訳以後に変更されたソース文書の箇所を取得するために、`build` ディレクトリにある専用のコマンドを使うことが出来ます。
``` ```
php build translation "../docs/guide" "../docs/guide-ru" "Russian guide translation report" > report_guide_ru.html php build translation "../docs/guide" "../docs/guide-ru" "Russian guide translation report" > report_guide_ru.html
......
...@@ -12,7 +12,7 @@ Yii バージョン規約 ...@@ -12,7 +12,7 @@ Yii バージョン規約
* 不安無しのアップグレードを保証するために、100% 後方互換でなければならない。唯一の例外はセキュリティ問題で、その場合は後方互換性が破られることもある。 * 不安無しのアップグレードを保証するために、100% 後方互換でなければならない。唯一の例外はセキュリティ問題で、その場合は後方互換性が破られることもある。
* リリースのサイクルは1~2ヶ月程度。 * リリースのサイクルは1~2ヶ月程度。
* プレリリース (alpha, beta, RC) は不要。 * プレリリース (alpha, beta, RC) は不要。
* 常にマスターブランチにマージバックされるべき (少なくとも週に一回は手作業で) * 定期的に (少なくとも週に一回は手作業で) マスターブランチにマージバックされるべき
## マイナーリリース `2.X.0` ## マイナーリリース `2.X.0`
...@@ -23,7 +23,7 @@ Yii バージョン規約 ...@@ -23,7 +23,7 @@ Yii バージョン規約
* `UPGRADE-2.X.md` ファイルに記録される非後方互換な変更を含みうる。 * `UPGRADE-2.X.md` ファイルに記録される非後方互換な変更を含みうる。
* リリースのサイクルは6~8ヶ月程度。 * リリースのサイクルは6~8ヶ月程度。
* プレリリースが必要: `2.X.0-alpha`, `2.X.0-beta`, `2.X.0-rc` * プレリリースが必要: `2.X.0-alpha`, `2.X.0-beta`, `2.X.0-rc`
* 大きなニュースのリリースとマーケティングの試みを要求する。 * 大きなニュースリリースとマーケティング努力を必要とする。
## メジャーリリース `X.0.0` ## メジャーリリース `X.0.0`
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment