英語に自信がなくてもできるCakePHPへの貢献 -バグ報告編-

CakePHP(またはオープンソースプロダクト)のコアコードのバグ・不満・修正・設計について言及したい、しかし英語わからない、面倒くさい、なんとなく怖い、といった方向け。

導入

CakePHPへの貢献は色々な方法があります。バグ報告、パッチ、ドキュメント、議論、有用なプラグインの作成、etc..
といっても、英語書かなきゃいけないというプレッシャーは大きいはず。
しかし怖がることはありません!
最低限の情報提供だけでもそれは有益なことです。
私たちの使っているフレームワークのコミュニティにはたくさんの、英語のネイティブではない人々がおり、その人達によってCakePHPは支えられているのです。

バグ報告

CakePHPへの貢献の中で、まず一番簡単で楽なのはなんといってもバグ報告です。
今回はこのバグ報告について、実例を見ながら、どうすればバグ報告をできるかを説明します。

チケット管理システム

CakePHPのバグトラック、またはチケット管理のシステムはLighthouseでホストされており、そのCakePHP専用のサイトは
http://cakephp.lighthouseapp.com/projects/42648-cakephp/overview
にあります。

アカウントが無い場合は作成しましょう。
※フォームの最後の項目で簡単なクイズがありますが、これは例えばお伽話のフレーズの一部の単語などとなっており、英語圏で生活していないと難題だったりします。しかし、フレーズを検索すればすぐ出てくるようなものばかりなので、ググりましょう
アカウントを作成したら、ログインしてください。
dashboardにいる場合は、報告したいプロジェクトを選択します。

右側のサイドバーに「Create new ticket」というボタンが見えます。これをクリックして新規チケットを発行する画面に移ります。

またこのボタンの下にある注意書きも見ておきましょう。
バグ報告時に気をつけること

When creating a bug report, please include as much relevant information as possible. Please include code to reproduce the issue. Or even better, make a unit test. Either change an existing test or add a new test to show that the expected behavior is not occuring.
訳:バグ報告を作成する際には、できるだけ多くの関連情報を記載してください。また、ユニットテストを行うこともより好ましいです。これは既存のテストを変更するか、期待する動作が起こっていないことを示すテストを追加するということです。

さて、自分が発行したとあるチケットを例として見ながら、フォームを入力していきましょう。
http://cakephp.lighthouseapp.com/projects/42648/tickets/2285-relative-protocol-url-was-replaced-by-asset-filter
入力する必要があるのは、タイトル、本文だけです。

タイトル

適切でわかりやすい一文にすることがベストですが、自動翻訳にかけるか、単語の羅列でも構わないでしょう。
ちなみに例では時制が過去形となっていて違和感があるというか明らかに間違ってますが、こんないい加減さでも伝わるもんは伝わります。(べ、別にわざとじゃなくて素なんだからね

本文

初期状態で、既に3つの見出しがついています。
先頭の#が4つついているのはマークダウン形式の見出しレベルの指定で、これはh4を表します。
この直下に伝えたいことを述べましょう。

#### What I did(自分がしたこと)
自分が試した例を挙げます。
再現性が高いものが望ましいです。
特定の環境でしか起きないならばその環境も書きましょう。(OSとか、バージョンとか
単純に、ファイルの特定行を抜き出して書くだけでもいいでしょう。
例では、

app/Config/core.php:
Configure::write('Asset.filter.js', 'custom_javascript_output_filter.php');
view:
<?php echo $this->Html->script('//example.com/js/hoge.js'); ?>

としても良かったことでしょう。


#### What happened(何が起こったか)
上記で試したことによって起こった結果を書きましょう。
これには出力、トレース、ログなどを含めてなるべく細かに報告したほうが良いです。(英語をいっぱい書けというわけではありません)
「エラーが起きた」「動かない」だけだと何も伝わりませんね。これは日本語でも同じです。
例では出力されたHTMLのソースからコピーしたものを貼りつけています。
どれを見せたらいいかわからない場合などは、画面キャプチャ画像を添付するのもいいでしょう。フォームの最後のところに添付するファイルの入力が用意されています。


#### What I expected to happen(何が起こると期待したか)
こうなって欲しい、ということを書きます。
例ではまたしても時制が(中の人の英語力が知れますね)・・・まあ主語と目的語があればなんとなく伝わります。
パッチを書いてあれば、それを載せるのもいいでしょう。これにはCakeBingist、フォークしたレポジトリのトピックブランチを活用しましょう。


その他
他に言いたいことがあれば、見出しを追加して書きましょう。
または、テンプレートを消して1から書いてももちろん問題ありません。
最後に感謝を述べるのも良い習慣です。どんなに小さくとも感謝の言葉は嬉しいものです。#で、あんたはやってるの?っていう質問は締め切りました

その他の項目

Who's responsible?(誰が担当?)や、タグについては、運営側が補完してくれることがほとんどで、出来る範囲でその助けとなるようにタグを書くだけで良いでしょう。
担当については、こちらで勝手に指定してしまうと、「なんでやねん」ってことになることがほとんどなので、もし特定のコア開発者と会話した後などであっても、指定しないようにしましょう。

その後

フォームを送信(右下にある「CREATE TICKET」のボタンをクリック)した後は、運営側がまずそのチケットを評価します。

  • 報告が間違ってる(invalid)
  • 保留(hold)
  • こっちでは問題ない(works-for-me)
  • 修正されない(won't-fix)

などのステータスが付与されるか、new(新規)のまま解決(resolved)を待つことになります。
この時にタグやマイルストーン、担当などを設定してくれることでしょう。
更に、それが問題として認識されれば、コアチーム中心にその解決のためのコミットが作成され、コードに反映されます。
あなたが解決する必要はありません。出来る人がやる、それが原則です。(もちろん、あなたが解決策、パッチを提供することは非常に助けになり、大切なことです)

最後に

ネットのコミュニケーションでもボディーランゲージは非常に有効です。
また、私達にはコードという最大の共通言語があります。
何も難しいことはありませんね!誰にでもバグ報告はできます
コアのコードの一部をあなたのプロジェクト固有に変更するという暴挙を繰り返したりなどする必要はないのです。
共通のプロジェクトへの貢献こそが、人々、またはあなた自身の大切な財産となり、全てにわたって最上の利益となるベストプラクティスなのです。