6ecc392f1c 2008-07-20 drh: <h1>Bug-Tracking In <a href="index.wiki">Fossil</a></h1> 6ecc392f1c 2008-07-20 drh: 6ecc392f1c 2008-07-20 drh: A bug-report in fossil is called a "ticket". Tickets are tracked 6ecc392f1c 2008-07-20 drh: separately from code check-ins (baselines). 6ecc392f1c 2008-07-20 drh: 6ecc392f1c 2008-07-20 drh: Some other distributed bug-tracking systems store tickets as files within 6ecc392f1c 2008-07-20 drh: the source tree and thereby leverage the syncing and merging capabilities 6ecc392f1c 2008-07-20 drh: of the versioning system to sync and merge tickets. This approach is 6ecc392f1c 2008-07-20 drh: rejected in fossil for three reasons: 6ecc392f1c 2008-07-20 drh: 6ecc392f1c 2008-07-20 drh: 1. Check-ins (a.k.a. "baselines") in fossil are immutable. So if 6ecc392f1c 2008-07-20 drh: tickets were part of the check-in, then there would no way to add 6ecc392f1c 2008-07-20 drh: new tickets to a check-in as new bugs are discovered. 6ecc392f1c 2008-07-20 drh: 6ecc392f1c 2008-07-20 drh: 2. Any project of reasonable size and complexity will generate thousands 6ecc392f1c 2008-07-20 drh: and thousands of tickets, and we do not want all those ticket files 6ecc392f1c 2008-07-20 drh: cluttering the source tree. 6ecc392f1c 2008-07-20 drh: 6ecc392f1c 2008-07-20 drh: 3. We want tickets to be managed from the web interface and to have a 6ecc392f1c 2008-07-20 drh: permission system that is distinct from check-in permissions. 6ecc392f1c 2008-07-20 drh: In other words, we do not want to restrict the creation and editing 6ecc392f1c 2008-07-20 drh: of tickets to developers with check-in privileges and an installed 6ecc392f1c 2008-07-20 drh: copy of the fossil executable. Casual passers-by on the internet should 6ecc392f1c 2008-07-20 drh: be permitted to create tickets. 6ecc392f1c 2008-07-20 drh: 6ecc392f1c 2008-07-20 drh: Recall that a fossil repository consists of an 6ecc392f1c 2008-07-20 drh: unordered collection of <i>artifacts</i>. (See the 6ecc392f1c 2008-07-20 drh: <a href="fileformat.wiki">file format document</a> for details.) 6ecc392f1c 2008-07-20 drh: Some artifacts have a special format, and among those are 6ecc392f1c 2008-07-20 drh: <a href="fileformat.wiki#tktchng">Ticket Change Artifacts</a>. 6ecc392f1c 2008-07-20 drh: One or more ticket change artifacts are associated with each 6ecc392f1c 2008-07-20 drh: ticket. A ticket is created by a ticket change artifact. 6ecc392f1c 2008-07-20 drh: Each subsequent modification of the ticket is a separate artifact. 6ecc392f1c 2008-07-20 drh: 6ecc392f1c 2008-07-20 drh: The "push", "pull", and "sync" algorithms shared ticket change artifacts 6ecc392f1c 2008-07-20 drh: between repositories in the same way as every other artifact. In fact, 6ecc392f1c 2008-07-20 drh: the sync algorithm has no knowledge of the meaning of the artifacts it 6ecc392f1c 2008-07-20 drh: is syncing. As far as the sync algorithm is concerned, all artifacts are 6ecc392f1c 2008-07-20 drh: alike. After the sync has occurs, the individual repositories must try 6ecc392f1c 2008-07-20 drh: to make sense of the meaning of the various artifacts for themselves. 6ecc392f1c 2008-07-20 drh: 6ecc392f1c 2008-07-20 drh: <h2>Interpretation Of Ticket Change Artifacts</h2> 6ecc392f1c 2008-07-20 drh: 6ecc392f1c 2008-07-20 drh: Every ticket change artifact contains (among other things) 6ecc392f1c 2008-07-20 drh: 6ecc392f1c 2008-07-20 drh: * a timestamp, 6ecc392f1c 2008-07-20 drh: * a ticket UUID, and 6ecc392f1c 2008-07-20 drh: * one or more name/value pairs. 6ecc392f1c 2008-07-20 drh: 6ecc392f1c 2008-07-20 drh: The current state of a ticket is found by replaying all ticket 6ecc392f1c 2008-07-20 drh: change artifacts with the same ticket UUID in timestamp order. 6ecc392f1c 2008-07-20 drh: For a given ticket, all values are initially NULL. As each 6ecc392f1c 2008-07-20 drh: ticket change artifact is encountered, values are either replaced 6ecc392f1c 2008-07-20 drh: or appended, according to a flag on the name/value pair. The current 6ecc392f1c 2008-07-20 drh: values for the fields of a ticket are the values that remain at the 6ecc392f1c 2008-07-20 drh: end of the replay process. 6ecc392f1c 2008-07-20 drh: 6ecc392f1c 2008-07-20 drh: To create a new ticket, on has merely to insert a ticket change 6ecc392f1c 2008-07-20 drh: artifact with a randomly generated ticket UUID. The ticket UUID 6ecc392f1c 2008-07-20 drh: is a random 40-character lower-case hexadecimal number. New 6ecc392f1c 2008-07-20 drh: ticket UUIDs should be chosen using good randomness so that two 6ecc392f1c 2008-07-20 drh: ore more users do not accidently cause a conflict by generating 6ecc392f1c 2008-07-20 drh: the same UUID. The name/value pairs on the initial ticket change 6ecc392f1c 2008-07-20 drh: artifact are the initial values for the fields in the ticket. 6ecc392f1c 2008-07-20 drh: 6ecc392f1c 2008-07-20 drh: Amending a ticket means simply creating a new artifact with the 6ecc392f1c 2008-07-20 drh: same ticket UUID and with name/value pairs for those fields which 6ecc392f1c 2008-07-20 drh: are changing. Fields of the ticket which are not being modified 6ecc392f1c 2008-07-20 drh: should not appear as name/value pairs in the new artifact. 6ecc392f1c 2008-07-20 drh: 6ecc392f1c 2008-07-20 drh: This approach to storing ticket state means that independently entered 6ecc392f1c 2008-07-20 drh: changes are automatically merged together when artifacts are shared 6ecc392f1c 2008-07-20 drh: between repositories. Tickets do not branch. This approach also makes 6ecc392f1c 2008-07-20 drh: it trivial to track the historic progression of changes to a ticket. 6ecc392f1c 2008-07-20 drh: 6ecc392f1c 2008-07-20 drh: In order for this scheme to work, the system clocks on machines that 6ecc392f1c 2008-07-20 drh: add new ticket changes artifacts have to be set close to reality. 6ecc392f1c 2008-07-20 drh: It is OK for a ticket change artifact timestamp to be off by a few 6ecc392f1c 2008-07-20 drh: minutes or even a few hours. But if a timestamp on a ticket change 6ecc392f1c 2008-07-20 drh: artifact is off by months or years, it can seriously confuse the 6ecc392f1c 2008-07-20 drh: replay algorithm for determining the current ticket state. There 6ecc392f1c 2008-07-20 drh: are techniques available to cause rogue artifacts to be ignored 6ecc392f1c 2008-07-20 drh: by fossil. So if a ticket change artifact with a bad timestamp 6ecc392f1c 2008-07-20 drh: does get into a repository, it can be removed by an adminstrator. 6ecc392f1c 2008-07-20 drh: But the best approach is to take steps to insure that timestamps 6ecc392f1c 2008-07-20 drh: are approximately correct in the first place. 6ecc392f1c 2008-07-20 drh: 6ecc392f1c 2008-07-20 drh: <h2>Local Configuration</h2> 6ecc392f1c 2008-07-20 drh: 6ecc392f1c 2008-07-20 drh: The ticket change artifacts are part of the global state for a project. 6ecc392f1c 2008-07-20 drh: The global state is that which is shared between repositories during 6ecc392f1c 2008-07-20 drh: a sync. Each repository also has local state which is not (normally) 6ecc392f1c 2008-07-20 drh: shared. The name/value pairs for a ticket are part of global state, 6ecc392f1c 2008-07-20 drh: but the interpretation and display of that information is local state. 6ecc392f1c 2008-07-20 drh: Hence, each repository is free to set up its own ticket display and 6ecc392f1c 2008-07-20 drh: input formats and reporting rules according to its own particular needs. 6ecc392f1c 2008-07-20 drh: 6ecc392f1c 2008-07-20 drh: Each repository defines its own TICKET table in its database. There is 6ecc392f1c 2008-07-20 drh: one row in the TICKET table for each unique ticket UUID. The 6ecc392f1c 2008-07-20 drh: names of columns in the TICKET table correspond to the names in 6ecc392f1c 2008-07-20 drh: the name/value pairs of ticket change artifacts. When running the replay 6ecc392f1c 2008-07-20 drh: algorithm, if a name/value pair is seen which has no corresponding column 6ecc392f1c 2008-07-20 drh: in the TICKET table, then that name/value pair is ignored. 6ecc392f1c 2008-07-20 drh: 6ecc392f1c 2008-07-20 drh: Each repository also defines scripts used to generate web pages for 6ecc392f1c 2008-07-20 drh: creating new tickets, viewing existing tickets, and modifying an 6ecc392f1c 2008-07-20 drh: existing ticket. These scripts consist of HTML with an embedded 6ecc392f1c 2008-07-20 drh: scripts written an a TCL-like language called "TH1". Each fossil 6ecc392f1c 2008-07-20 drh: repository is create with default scripts. There is currently no 6ecc392f1c 2008-07-20 drh: documentation on the TH1 langauage. Administrators wishing to 6ecc392f1c 2008-07-20 drh: customize their ticket entry, viewing, and editing screens should 6ecc392f1c 2008-07-20 drh: modify the default scripts to suit their needs.
File Annotation