Documentation

Fossilによるバグトラッキング

fossil ではバグレポートを"チケット"と呼びます。チケットはコードのチェックインとは別に管理されます。

他の分散バグトラッキングシステムではチケットをソースツリー上のファイルに 保存し、同期とマージはバージョン管理システムに任せる場合があります。 しかしながら fossil では3つの理由により、この方式を採用しませんでした:

  1. fossil におけるチェックインは変更不可能である。 そのため、チケットがチェックインの一部である場合、バグが新たに発見された際に チケットをそのチェックインに追加することができない。

  1. 通常の規模と複雑さのプロジェクトでは何百万ものチケットが 発行される。これらによってソースツリーを散らかしたくない。

  1. チケットの発行を web インターフェースから管理し、 ソースのチェックインとは別の権限で許可を与えたかった。 つまり、チェックイン権限を持つ開発者たちだけにチケットの作成と編集を 任せるのではなく、通りがかりのユーザでもチケットを作れるようにしたかった。

fossil リポジトリは アーティファクト の順序付けのない集合を含んでおり、 (この詳細についてはファイルフォーマット を参照のこと。)それらのうち、いくつかは特殊なフォーマットになっていて、 Ticket Change Artifactsもその一つです。 各チケットには一つ以上のチケット変更アーティファクトが紐付けられています。 チケットはチケット変更アーティファクトによって作成されます。 また、チケットの変更は別のアーティファクトによります。

"push"、"pull"、および"sync" アルゴリズムは他のアーティファクトと同様の 方法でリポジトリ間のチケット変更アーティファクトを共有します。 実際のところ、同期アルゴリズムは同期の際にそのアーティファクトが何を意味するかを 知りません。同期アルゴリズムに関して言えば、全てのアーティファクトは同じなのです。 同期が行われた結果、それぞれのリポジトリはそれらのアーティファクトの意味を 理解するようになります。

チケット変更アーティファクトの解釈

付記: この項目は実装の詳細について触れており、一般的なfossilユーザは無視して構わない。

全てのチケット変更アーティファクトはこれらを含む

The current state of a ticket is found by replaying all ticket change artifacts with the same ticket ID in timestamp order. For a given ticket, all values are initially NULL. As each ticket change artifact is encountered, values are either replaced or appended, according to a flag on the name/value pair. The current values for the fields of a ticket are the values that remain at the end of the replay process.

To create a new ticket, one inserts a ticket change artifact with a new ID. The ticket ID is a random 40-character lower-case hexadecimal number. The "tktnew" page in the fossil web interface creates new ticket IDs using a good source of randomness to insure uniqueness. The name/value pairs on the initial ticket change artifact are the initial values for the fields in the ticket.

Amending a ticket means simply creating a new artifact with the same ticket ID and with name/value pairs for those fields which are changing. Fields of the ticket which are not being modified should not appear as name/value pairs in the new artifact.

This approach to storing ticket state means that independently entered changes are automatically merged together when artifacts are shared between repositories. Tickets do not branch. This approach also makes it trivial to track the historic progression of changes to a ticket.

In order for this scheme to work, the system clocks on machines that add new ticket changes artifacts have to be set close to reality. It is OK for a ticket change artifact timestamp to be off by a few minutes or even a few hours. But if a timestamp on a ticket change artifact is off by months or years, it can seriously confuse the replay algorithm for determining the current ticket state. There are techniques available to cause rogue artifacts to be ignored by fossil. So if a ticket change artifact with a bad timestamp does get into a repository, it can be removed by an administrator. But the best approach is to take steps to insure that timestamps are approximately correct in the first place.

ローカル設定

チケット変更アーティファクトはプロジェクトのグローバルな状態の一部です。 グローバルな状態とはリポジトリ間で同期されているものを示します。 その他に、各リポジトリは(一般的には)共有されないローカルな状態を持ちます。 チケットの name/value ペアはグローバル状態の一部となりますが、 その解釈と表示はローカル状態となります。 そのため、各リポジトリは必要であるかぎり、自身のフォーマット、レポートルール、 表示方法を持つことができます。

各リポジトリは自身の チケットテーブルをデータベース内に持ちます。 そのうち、チケットテーブルの各行は一意なチケットIDを持ちます。 チケットテーブルのその他の列については、チケット変更アーティファクトの name/value ペアの名前を持っています。 一旦リプレイアルゴリズムが走りだすと、チケットテーブル上の指定されていない name/value ペアは無視されます。チケットテーブル上の各列は好きなタイミングで 追加・削除できます。 チケットテーブルが変更されると、リプレイアルゴリズムは自動的に 新しい列名を使ってテーブルを構成し直します。 ここで、チケットテーブルの構造と内容についてはリポジトリのローカル状態であり、 sync,push,pull において他のリポジトリと共有されることはありません。

各リポジトリは新規チケット追加、既存チケット閲覧、既存チケット変更を 行うための webページ生成のためにスクリプトを定義する場合があります。 これらのスクリプトは、"TH1"と呼ばれる Tcl に似た言語を埋め込んだ HTMl で 構成されています。 デフォルトのスクリプトによって作成された新規の fossil リポジトリは TH1言語のドキュメントを何も持っていません。 管理者はチケット入力・表示・編集画面をデフォルトから必要に応じて変更したいと 望むかもしれません。 これらの画面生成スクリプトもリポジトリのローカル状態であり、sync,push,pull で 他のリポジトリと共有されることはありません。

To be continued...