SHA1 Hash:	efb759a07da0ea5c540e2b73ae63d8c636bf8673
Date:	2008-10-26 02:16:51
User:	drh
Comment:	Change the default subsystem list for tickets to an empty set. Update documentation to begin making a clearer distinction between local state and global state.
Timelines:	ancestors | descendants | both | trunk
Other Links:	files | ZIP archive | manifest

• branch=trunk inherited from [a28c83647d]
• sym-trunk inherited from [a28c83647d]

Modified src/tktsetup.c from [953c7e0a99] to [866d7baa7c].

@@ -215,11 +215,12 @@
 @   Deferred
 @   Fixed
 @   Tested
 @   Closed
 @ }
-@ set subsystem_choices {one two three}
+@ set subsystem_choices {
+@ }
 ;
 
 /*
 ** Return the ticket common code.
 */

Modified www/fileformat.wiki from [e95af362bc] to [49c16eb396].

@@ -1,22 +1,37 @@
 <h1 align="center">
 Fossil File Formats
 </h1>
 
-<p>The state of a fossil repository is kept simple so that it can
+<p>The global state of a fossil repository is kept simple so that it can
 endure in useful form for decades or centuries.
 A fossil repository is intended to be readable,
 searchable, and extensible by people not yet born.</p>
 
 <p>
-The global state of a fossil repository is determined by an unordered
+The global state of a fossil repository is an unordered
 set of <i>artifacts</i>.
 An artifact might be a source code file, the text of a wiki page,
 part of a trouble ticket, or one of several special control artifacts
 used to show the relationships between other artifacts within the
 project.  Each artifact is normally represented on disk as a separate
 file.  Artifacts can be text or binary.
+</p>
+
+<p>
+In addition to the global state,
+each fossil repository also contains local state.
+The local state consists of web-page formatting
+preferences, authorized users, ticket display and reporting formats,
+and so forth.  The global state is shared in common among all
+repositories for the same project, whereas the local state is often
+different in separate repositories.
+The local state is not versioned and is not synchronized
+with the global state.
+The local state is not composed of artifacts and is not intended to be enduring.
+This document is concerned with global state only.  Local state is only
+mentioned here in order to distinguish it from global state.
 </p>
 
 <p>
 Each artifact in the repository is named by its SHA1 hash.
 No prefixes or meta information is added to a artifact before
@@ -331,11 +346,11 @@
 <p>A ticket-change artifact represents a change to a trouble ticket.
 The following cards are allowed on a ticket change artifact:</p>
 
 <blockquote>
 <b>D</b> <i>time-and-date-stamp</i><br />
-<b>J</b> ?<b>+</b>?<i>name value</i><br />
+<b>J</b> ?<b>+</b>?<i>name</i> ?<i>value</i>?<br />
 <b>K</b> <i>ticket-id</i><br />
 <b>U</b> <i>user-name</i><br />
 <b>Z</b> <i>checksum</i>
 </blockquote>
 
@@ -350,15 +365,19 @@
 is specified by the K card.  A ticket exists if it contains one or
 more changes.  The first "change" to a ticket is what brings the
 ticket into existance.</p>
 
 <p>
-J cards specify changes to "fields" of the ticket.  Each fossil
-server has a ticket configuration which specifies the fields its
-understands.  This is not a limit on the fields that can appear
-on the J cards, however.  If a J card specifies a field that a
-particular fossil server does not recognize, then that J card
+J cards specify changes to the "value" of "fields" in the ticket.
+If the <i>value</i> parameter of the J card is omitted, then the
+field is set to an empty string.
+Each fossil server has a ticket configuration which specifies the fields its
+understands.  The ticket configuration is part of the local state for
+the repository and thus can vary from one repository to another.
+Hencd a J card might specify a <i>field</i> that do not exist in the
+local ticket configuration.  If a J card specifies a <i>field</i> that
+is not in the local configuration, then that J card
 is simply ignored.</p>
 
 <p>
 The first argument of the J card is the field name.  The second
 value is the field value.  If the field name begins with "+" then

Modified www/sync.wiki from [63112b2762] to [7118e0761e].

@@ -15,17 +15,27 @@
 Synchronization is simply the process of sharing artifacts between
 servers so that all servers have copies of all artifacts.  Because
 artifacts are unordered, the order in which artifacts are received
 at a server is inconsequential.  It is assumed that the SHA1 hashes
 of artifacts are unique - that every artifact has a different SHA1 hash.
-To first approximation, synchronization proceeds by sharing lists
+To a first approximation, synchronization proceeds by sharing lists
 SHA1 hashes of available artifacts, then sharing those artifacts that
 are not found on one side or the other of the connection.  In practice,
 a repository might contain millions of artifacts.  The list of
 SHA1 hashes for this many artifacts can be large.  So optimizations are
 employed that usually reduce the number of SHA1 hashes that need to be
 shared to a few hundred.</p>
+
+<p>Each repository also has local state.  The local state determines
+the web-page formatting preferences, authorized users, ticket formats,
+and similar information that varies from one repository to another.
+The local state is not transfered by the <b>push</b>, <b>pull</b>,
+and <b>sync</b> command, though some local state is transfered during
+a <b>clone</b> in order to initialize the local state of the new
+repository.  The <b>configuration push</b> and <b>configuration pull</b>
+commands can be used to send or receive local state.</p>
+
 
 <h2>2.0 Transport</h2>
 
 <p>All communication between client and server is via HTTP requests.
 The server is listening for incoming HTTP requests.  The client
@@ -275,11 +285,19 @@
 cookie and the server must structure the cookie payload in such
 a way that it can tell if the cookie it sees is its own cookie or
 a cookie from another server.  (Typically the server will embed
 its servercode as part of the cookie.)</p>
 
-<h3>3.9 Error Cards</h3>
+<h3>3.9 Request-Configuration Cards</h3>
+
+<i>TBD...</i>
+
+<h3>3.10 Configuration Cards</h3>
+
+<i>TBD...</i>
+
+<h3>3.11 Error Cards</h3>
 
 <p>If the server discovers anything wrong with a request, it generates
 an error card in its reply.  When the client sees the error card,
 it displays an error message to the user and aborts the sync
 operation.  An error card looks like this:</p>
@@ -295,11 +313,16 @@
 (ASCII 0x5C) is represented as two backslashes "\\".  Apart from
 space and newline, no other whitespace characters nor any
 unprintable characters are allowed in
 the error message.</p>
 
-<h3>3.10 Unknown Cards</h3>
+<h3>3.12 Comment Cards</h3>
+
+<p>Any card that begins with "#" (ASCII 0x23) is a comment card and
+is silently ignored.</p>
+
+<h3>3.13 Unknown Cards</h3>
 
 <p>If either the client or the server sees a card that is not
 described above, then it generates an error and aborts.</p>
 
 <h2>4.0 Phantoms And Clusters</h2>
@@ -463,10 +486,13 @@
     <li> <b>file</b> <i>artifact-id size</i> <b>\n</b> <i>content</i>
     <li> <b>file</b> <i>artifact-id delta-artifact-id size</i> <b>\n</b> <i>content</i>
     <li> <b>igot</b> <i>artifact-id</i>
     <li> <b>gimme</b> <i>artifact-id</i>
     <li> <b>cookie</b>  <i>cookie-text</i>
+    <li> <b>reqconfig</b> <i>parameter-name</i>
+    <li> <b>config</b> <i>parameter-name size</i> <b>\n</b> <i>content</i>
+    <li> <b>#</b> <i>arbitrary-text...</i>
     <li> <b>error</b> <i>error-message</i>
     </ul>
 <li>Phantoms are artifacts that a repository knows exist but does not possess.
 <li>Clusters are artifacts that contain IDs of other artifacts.
 <li>Clusters are created automatically on the server during a pull.