= バグ収束曲線やバーンダウンチャートを描画するQuery Chart マクロ =
== Description ==
チケットの件数をカウントして、バグ収束曲線やバーンダウンチャートを描画するWikiマクロです。

Wikiマクロなので、Wikiに貼り付けるだけでなく、タイムラインやレポートと一緒に表示することで進捗をかっこよく表示することができます。

また、このプラグインには、チケットのステータスが変化した日を、カスタムフィールドに保存する機能を同梱しています。これとグラフを組み合わせることで、チケットがクローズした日をグラフにすることができます。

== ScreenShot ==
[[Image(screenshot.png)]]

== Requament ==
このプラグインはTrac 0.11用です。

== Install ==
Subversion を使用して、CodeReposからチェックアウトしてください。コマンドラインクライアントでは、以下のようにします。

{{{
svn checkout http://svn.coderepos.org/share/platform/trac/plugins/querychart
}}}

/trunkに移動して以下のコマンドを実行して下さい:

{{{
$ python setup.py bdist_egg
}}}

distフォルダが作成されます。その中にある*.eggファイルを、TracEnvのplugins ディレクトリにコピーしてください。

== Usage ==
=== Macro ===
以下のようにwikiにマクロを記載することで、グラフを表示します。

{{{
[[QueryChart(args1,args2,...)]]
}}}

args:

 * query: チケットの検索条件。以下の３通りの記載が可能です。
   * TicketQueryマクロのクエリ言語方式：[[BR]]
     以下のように頭に?をつけずに条件を書きます。詳しくは[wiki:TracQuery#QueryLanguage クエリ言語]を参照。[[BR]]
     !query:status=new|assigned&version^=1.0
   * カスタムクエリでURLに表示される方式：[[BR]]
     以下のように、頭に?(:も忘れずに)をつけて各条件を&で区切ります。カスタムクエリの画面で条件を指定して、
     URLの部分を貼り付けるとイイでしょう。[[BR]]
     !query:?status=new&status=assigned&version=^1.0
   * 省略する方式：[[BR]]
     カスタムクエリから作成したレポートの説明欄に貼り付ける場合(つまりブラウザのURLにクエリが表示されて
     いる状態)のみ、省略が可能です。省略すると画面で指定した検索条件となります。
     省略する場合はこの項目(query:…)自体を省略してください。
 * col: 対象とする項目。複数記載すれば複数本線を引ける。少なくとも１つ必須。複数指定する場合はcol=xxx,col=yyyと
   カンマ区切りで記載してください。項目名はフィールド名（Trac内部のフィールド名）と
   ラベル（表示されている項目名）のどちらでも指定可能です。
 * per:(=day,week,free) 集計単位。未指定ならweek
 * start: グラフの左端の日。未指定ならチケットの最も過去の日。yyyy/mm/dd形式
 * end: グラフの右端の日。未指定ならチケットの最も最近の日。yyyy/mm/dd形式
 * width: グラフの幅。px単位で指定。未指定なら536px
 * height: グラフの高さ。px単位で指定。未指定なら300px
 * upper: アップチャートを書く（バグ収束曲線等）。指定しない場合はダウンチャート
例：

{{{
[[QueryChart(query:?milestone=1.0リリース,col:due_close,col:due_assign,per:free,width:500,height:300)]]
}}}

=== Status Logger and Admin Page ===
Trac.iniにてステータスの優先順位と、保存するカスタムフィールドを設定することで、Ticketの変更時に自動的に設定したカスタムフィールドに日付が保存することができます。また、管理画面から一括して日付をセットすることができます。

Tracではクローズしたチケットの差し戻しが可能なことに加え、Trac0.11以降では、ワークフローのカスタマイズが可能なため、「この日を完了日とする」みたいなルールを決める必要があります。このプラグインでは、「ステータスの発生順位」を決めてそれに従って日付をセットします。発生順位の高いものより前に発生順位の低いステータスにならないようにカスタムフィールドに日付がセットされます。

デフォルトのワークフローでは、以下の優先順位でだいたいうまくいくと思います。(ちなみにチケットの作成日はカスタムフィールド用意しなくてもtimeという項目に入るので、コレ使う必要なし）

(1)assigned (2)accepted (3)reopened (4)closed

たとえば、以下のように12/01にアサインした後、12/10にいきなりcloseしたとします。この場合、closedより発生順位の高いaccepted,reopenedにはclosedと同じ12/10の日付がセットされます。さらに、その後12/20にreopenしたとします。reopenedより発生順位の低いclosedは空にクリアされます。

|| ||assigned||accepted||reopened||closed||
||ある時点||2008/12/01||-||-||-||
||その後、12/10にいきなりcloseした||2008/12/01||2008/12/10||2008/12/10||2008/12/10||
||その後、12/20に差し戻し(reopen)した||2008/12/01||2008/12/10||2008/12/20||-||


次に、ステータスの発生日を保存するためのカスタムフィールドを用意してください。これは総てのステータスの文用意する必要はありません。必要な分だけ用意してください。

なお、この項目はプラグインの方で勝手に値を書き換えるため、人は入力しない運用ルールにすることをおすすめします。

発生順位と、どのカスタムフィールドに保存するかをtrac.iniの[QueryChart]カテゴリのorderに設定してください。発生順位に従ってステータスをカンマで区切り、さらに保存するカスタムフィールドをステータスの後にコロンで区切って指定します。

たとえば、デフォルトワークフローの発生順位で、アサインした日をlast_assigned、完了日をlast_closedというカスタムフィールドに保存する場合は、以下のように指定します。ちなみに、カスタムフィールドを1つも指定しないと、日付は保存されません。

{{{
[querychart]
order = assigned:last_assigned, accepted,reopened, closed:last_closed
}}}

プラグインを入れてtrac.iniを設定した後、管理画面から、チケットシステム→QueryChartのリセットボタンを押して、全チケットに対して日付のセットを行ってください。それ以降はチケットの保存時に自動的に日付が指定したカスタムフィールドに保存されます。（TicketDeleteプラグインやBatchModifyプラグインでチケットを変更した場合は、自動で日付が入りません。再度管理画面から日付のセットを行ってください。）

[[Image(Image2.png, link=attachment:Image1.png)]]

ボタンを押すと、全チケットに対して設定したルールで日付がセットされます。（チケットの変更履歴に従って実際にステータスが変化した日がセットされます）

なお、trac.iniの[QueryChart]カテゴリのorderを変更した場合は、このボタンを再度押して日付をセットし直してください。

== License ==
このプラグインのライセンスは修正BSDライセンスです。

このプラグインは、 [http://code.google.com/p/flot/ Flot] というライブラリを使用しています。FlotのライセンスははMIT Licenseです。