5523218023 2009-08-24 drh: <title>Fossil Documentation</title> 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 904ee40b93 2009-01-23 drh: separately from code check-ins. 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: 904ee40b93 2009-01-23 drh: 1. Check-ins in fossil are immutable. So if 7083eb1a1c 2008-11-20 drh: tickets were part of the check-in, then there would be 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: 9d10726d48 2008-07-29 drh: The "push", "pull", and "sync" algorithms share 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 9d10726d48 2008-07-29 drh: alike. After the sync has occurs, the individual repositories must 9d10726d48 2008-07-29 drh: 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> 9d10726d48 2008-07-29 drh: 6ba52ae761 2009-02-21 drh: <i>Note: The following is implementation detail which can be safely ignored by 6ba52ae761 2009-02-21 drh: casual users of fossil.</i> 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, e8c4f69c50 2008-10-24 drh: * a ticket ID, 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 e8c4f69c50 2008-10-24 drh: change artifacts with the same ticket ID 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: 9d10726d48 2008-07-29 drh: To create a new ticket, one inserts a ticket change e8c4f69c50 2008-10-24 drh: artifact with a new ID. The ticket ID 9d10726d48 2008-07-29 drh: is a random 40-character lower-case hexadecimal number. The "tktnew" e8c4f69c50 2008-10-24 drh: page in the fossil web interface creates new ticket IDs 9d10726d48 2008-07-29 drh: using a good source of randomness to insure uniqueness. 9d10726d48 2008-07-29 drh: 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 e8c4f69c50 2008-10-24 drh: same ticket ID 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 9eb6ea75c1 2008-11-11 kejoki: does get into a repository, it can be removed by an administrator. 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 e8c4f69c50 2008-10-24 drh: one row in the TICKET table for each unique ticket ID. 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 9d10726d48 2008-07-29 drh: in the TICKET table, then that name/value pair is ignored. Columns can 9d10726d48 2008-07-29 drh: be added or removed from the TICKET table at any time. Whenever the 9d10726d48 2008-07-29 drh: TICKET table is modified, the replay algorithm automatically reruns 9d10726d48 2008-07-29 drh: to repopulate the table using the new column names. Note that the TICKET 9eb6ea75c1 2008-11-11 kejoki: table schema and content is part of the local state of a repository 9d10726d48 2008-07-29 drh: and is not shared with other repositories during a sync, push, or pull. 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 9eb6ea75c1 2008-11-11 kejoki: scripts written an a Tcl-like language called "TH1". Every new fossil 109114baf4 2009-09-21 drh: repository is created with default scripts. Paul Ruizendaal has written 109114baf4 2009-09-21 drh: documentation on the TH1 language that is available at 109114baf4 2009-09-21 drh: [http://www.sqliteconcepts.org/THManual.pdf]. Administrators wishing to 6ecc392f1c 2008-07-20 drh: customize their ticket entry, viewing, and editing screens should 9d10726d48 2008-07-29 drh: modify the default scripts to suit their needs. These screen generator 9d10726d48 2008-07-29 drh: scripts are part of the local state of a repository and are not shared 9d10726d48 2008-07-29 drh: with other repositories during a sync, push, or pull. 9d10726d48 2008-07-29 drh: 9d10726d48 2008-07-29 drh: <i>To be continued...</i>
File Annotation