チケットの書き方(まだ書きかけ)
TracNav menu
BTSへの登録をする上でのガイドです。 このガイドに従わなければならないわけではありませんが、 迷った時の助けになると思います。 まだ方針がはっきりしていないものなどは記載されていませんが、 随時追記していく予定です。
チケットを登録してみよう
チケットを登録する際の手順は以下のようになります。
- 画面右上のナビゲーションバーの『チケットの作成』をクリックして チケット登録画面に移動します。
- まずチケット属性を指定しましょう。
- 『チケットの種類』は、新しい機能の要求であれば『新機能/拡張』を、
それ以外は『不具合』を使用しましょう。
『タスク』は主に開発者が使っていきます。
- 『機能区分』(コンポーネント)を選択しましょう。 適切なものがあればそれを選択します。 不明なら『その他/一般』を選択しておいてください。
- 使用しているmeadowのバージョンも忘れずに指定しましょう。 もし複数の系列で不具合が確認されている場合は、 古い系列を指定して下さい。 例えば meadow 2.10 と meadow 3.00 の両方で確認されている場合は、 2.10 を指定します。 確認された他のバージョン番号は詳細説明内にて記載して下さい。
- そのほかのフィールドは、明示的に指定したいものがあれば指定してください。なければそのままで結構です。
- 『概要』は、その1行で大体のことがわかるようなものが望ましいです。 多少長めであっても構いません。
- 『詳細』欄には詳細な内容を記述します。
ここでは Wiki書式が使用できますので活用してください。
- svn先端を使ってる人は対象リビジョンも記述しましょう。 リビジョンは "r2345" のように書くのが良いでしょう。
- 関連するメールがあるのならば、それをリンクとして加えましょう (参照: MLアーカイブへのリンク)
- 他のメールからの引用やファイルの内容、パッチ情報などはクオート({{{ ... }}})しましょう。(参照: 書式付クォート)
- 再現性についても記載しましょう。その現象は決まった操作で再現できるのか、 再現手順は明確でないものの確実に発生しているのか、 .emacs を 読み込ませない場合(meadow -q で起動)でも再現するのか、 といった情報は、問題解決のための大きなヒントになります。
- 『プレビュー』ボタンを押して、詳細説明の記述が望み通りになっているかを 確認しましょう。この時点ではまだチケットは登録されていません。
- 間違いがないか確認できたら『保存』ボタンで登録作業を完了します。
より適した表現をしよう
Tracのチケットは、Wikiページと同様にWiki書式が使用できます。 これにより、表現豊かで読みやすいものにすることが出来ます。 チケット作成時の説明文や、コメントに使えます。 どのような見栄えになるかはプレビューボタンで確認することが出来ます。
Trac Wiki の書式は簡単に覚えられる程度のものですが、 代表的なものを以下に列挙しておきます。
他のチケットなどの参照
チケットやチェンジセットへのリンクを簡単に記述することができます。 チケット作成時に良く使うのは他のチケットへの参照(例: #123 もしくは ticket:123)や、 関連するチェンジセット(ex r2044 もしくは [2044]) でしょう。
クォート
プログラムコードはなるべくクォートしましょう。 クォートする事で固定ピッチのフォントが使用されて読み易くなります。 またクォートする事でWiki の書式は適用されなくなるので、 コードをそのまま書く事が出来て記述し易くなります。
複数行の画面出力や emacs lisp コードなどを記述する時は
ブロッククォート {{{\n...\n}}}\nを使用しましょう。
例:
{{{
(defun my-func ()
(interactive)
(message "hello")
t)
}}}
上の中括弧によるクォートをを本文中で使う事も出来ます。これをインライン
クォートと呼びます。インラインクォートはバッククォート(`)で囲む書き方も
あり、こちらの方が使い易いでしょう。
本文中に lisp やCのコード/変数名などを記載する場合は
クォートすると読み易くなりますので活用して下さい。
例:
... その場合は`(setq debug-on-error t)`を評価してからコマンドを実行し...
書式付クォート
ブロッククォートのひとつとして、書式付クォートというものがあります。{{{の次の行に #!diffといった1行を 指定することで、クォートの中身を見やすい形に整形したり、色づけして表示してくれます。 例えば#!diffと書けばdiff出力として、#!cと書けばC言語プログラムとして扱います。 また#!htmlと書けばWiki書式ではなく生のHTML記述をすることも出来ます。 ただし残念ながらemacs lisp のための書式指定は出来ないので、 emacs lispの場合は書式指定をしない通常のクォートを使用してください。
diff/patch の添付方法
基本指針を上げておきます。
- unified diff (svnでは標準、diffでのオプションは-u)で作成してください。
- チケット作成後に添付ファイル(attachment)として追加してください。
- 小さめ(20数行以内程度?)のdiff/patchは、チケット作成時に詳細説明の中に記述してもかまいません。 その際は書式付でクオート({{{)すると、見栄えが良くなります。
パッチ情報を本文中に記述する場合は、以下のようにフォーマット指定付きで`{{{'を使うのが良いです。 単なる{{{による表現とは違い、diffとして見やすく表現してくれます。
{{{
#!diff
===================================================================
--- main.py (revision 2151)
+++ main.py (working copy)
@@ -28,6 +28,7 @@
from trac.web.clearsilver import HDFWrapper
from trac.web.href import Href
from trac.web.session import Session
+from trac.localization import LocalizationModule
# Environment cache for multithreaded front-ends:
try:
}}}
こうすると以下のように表示されます。
-
main.py
old new 28 28 from trac.web.clearsilver import HDFWrapper 29 29 from trac.web.href import Href 30 30 from trac.web.session import Session 31 from trac.localization import LocalizationModule 31 32 32 33 # Environment cache for multithreaded front-ends: 33 34 try:
添付した場合も同様の表示をしてくれますのでご安心を ただし、形式はファイル名の拡張子で判断されますので、拡張子は *.diffあるいは*.patchとしてください。
