Fossil SCM
Documented several special-case rules for certain cards as footnotes in the fileformat.wiki card summary table.
Commit
a3bfeb85213895eb4b5f53b2af5e9e79bee2cf19e599ce4385fbf0230304dd39
Parent
188ffef23db2804…
1 file changed
+35
-19
+35
-19
| --- www/fileformat.wiki | ||
| +++ www/fileformat.wiki | ||
| @@ -32,11 +32,11 @@ | ||
| 32 | 32 | with the global state. |
| 33 | 33 | The local state is not composed of artifacts and is not intended to be enduring. |
| 34 | 34 | This document is concerned with global state only. Local state is only |
| 35 | 35 | mentioned here in order to distinguish it from global state. |
| 36 | 36 | |
| 37 | -<a name="names"></a> | |
| 37 | +<a id="names"></a> | |
| 38 | 38 | <h2>1.0 Artifact Names</h2> |
| 39 | 39 | |
| 40 | 40 | Each artifact in the repository is named by a hash of its content. |
| 41 | 41 | No prefixes, suffixes, or other information is added to an artifact before |
| 42 | 42 | the hash is computed. The artifact name is just the (lower-case |
| @@ -54,11 +54,11 @@ | ||
| 54 | 54 | |
| 55 | 55 | Prior to Fossil version 2.0, all names were formed from the SHA1 hash of |
| 56 | 56 | the artifact. The key innovation in Fossil 2.0 was adding support for |
| 57 | 57 | alternative hash algorithms. |
| 58 | 58 | |
| 59 | -<a name="structural"></a> | |
| 59 | +<a id="structural"></a> | |
| 60 | 60 | <h2>2.0 Structural Artifacts</h2> |
| 61 | 61 | |
| 62 | 62 | A structural artifact is an artifact with a particular format |
| 63 | 63 | that is used to define the relationships between other artifacts in the |
| 64 | 64 | repository. |
| @@ -100,11 +100,11 @@ | ||
| 100 | 100 | not how the artifacts are stored on disk. It is the artifact format that |
| 101 | 101 | is intended to be enduring. The specifics of how artifacts are stored on |
| 102 | 102 | disk, though stable, is not intended to live as long as the |
| 103 | 103 | artifact format. |
| 104 | 104 | |
| 105 | -<a name="manifest"></a> | |
| 105 | +<a id="manifest"></a> | |
| 106 | 106 | <h3>2.1 The Manifest</h3> |
| 107 | 107 | |
| 108 | 108 | A manifest defines a check-in. |
| 109 | 109 | A manifest contains a list of artifacts for |
| 110 | 110 | each file in the project and the corresponding filenames, as |
| @@ -256,11 +256,11 @@ | ||
| 256 | 256 | consistent. |
| 257 | 257 | |
| 258 | 258 | A sample manifest from Fossil itself can be seen |
| 259 | 259 | [/artifact/28987096ac | here]. |
| 260 | 260 | |
| 261 | -<a name="cluster"></a> | |
| 261 | +<a id="cluster"></a> | |
| 262 | 262 | <h3>2.2 Clusters</h3> |
| 263 | 263 | |
| 264 | 264 | A cluster is an artifact that declares the existence of other artifacts. |
| 265 | 265 | Clusters are used during repository synchronization to help |
| 266 | 266 | reduce network traffic. As such, clusters are an optimization and |
| @@ -282,11 +282,11 @@ | ||
| 282 | 282 | prior cards in the cluster. The <b>Z</b> card is required. |
| 283 | 283 | |
| 284 | 284 | An example cluster from Fossil can be seen |
| 285 | 285 | [/artifact/d03dbdd73a2a8 | here]. |
| 286 | 286 | |
| 287 | -<a name="ctrl"></a> | |
| 287 | +<a id="ctrl"></a> | |
| 288 | 288 | <h3>2.3 Control Artifacts</h3> |
| 289 | 289 | |
| 290 | 290 | Control artifacts are used to assign properties to other artifacts |
| 291 | 291 | within the repository. |
| 292 | 292 | Allowed cards in a control artifact are as follows: |
| @@ -336,11 +336,11 @@ | ||
| 336 | 336 | artifact. The <b>Z</b> card is the usual required artifact checksum. |
| 337 | 337 | |
| 338 | 338 | An example control artifacts can be seen [/info/9d302ccda8 | here]. |
| 339 | 339 | |
| 340 | 340 | |
| 341 | -<a name="wikichng"></a> | |
| 341 | +<a id="wikichng"></a> | |
| 342 | 342 | <h3>2.4 Wiki Pages</h3> |
| 343 | 343 | |
| 344 | 344 | A wiki artifact defines a single version of a |
| 345 | 345 | single wiki page. |
| 346 | 346 | Wiki artifacts accept |
| @@ -380,11 +380,11 @@ | ||
| 380 | 380 | artifact that includes a <b>C</b> card. |
| 381 | 381 | |
| 382 | 382 | An example wiki artifact can be seen |
| 383 | 383 | [/artifact?name=7b2f5fd0e0&txt=1 | here]. |
| 384 | 384 | |
| 385 | -<a name="tktchng"></a> | |
| 385 | +<a id="tktchng"></a> | |
| 386 | 386 | <h3>2.5 Ticket Changes</h3> |
| 387 | 387 | |
| 388 | 388 | A ticket-change artifact represents a change to a trouble ticket. |
| 389 | 389 | The following cards are allowed on a ticket change artifact: |
| 390 | 390 | |
| @@ -426,11 +426,11 @@ | ||
| 426 | 426 | escapes defined for the <b>C</b> card of a manifest. |
| 427 | 427 | |
| 428 | 428 | An example ticket-change artifact can be seen |
| 429 | 429 | [/artifact/91f1ec6af053 | here]. |
| 430 | 430 | |
| 431 | -<a name="attachment"></a> | |
| 431 | +<a id="attachment"></a> | |
| 432 | 432 | <h3>2.6 Attachments</h3> |
| 433 | 433 | |
| 434 | 434 | An attachment artifact associates some other artifact that is the |
| 435 | 435 | attachment (the source artifact) with a ticket or wiki page or |
| 436 | 436 | technical note to which |
| @@ -468,11 +468,11 @@ | ||
| 468 | 468 | |
| 469 | 469 | The <b>Z</b> card is the usual checksum over the rest of the attachment artifact. |
| 470 | 470 | The <b>Z</b> card is required. |
| 471 | 471 | |
| 472 | 472 | |
| 473 | -<a name="event"></a> | |
| 473 | +<a id="event"></a> | |
| 474 | 474 | <h3>2.7 Technical Notes</h3> |
| 475 | 475 | |
| 476 | 476 | A technical note or "technote" artifact (formerly known as an "event" artifact) |
| 477 | 477 | associates a timeline comment and a page of text |
| 478 | 478 | (similar to a wiki page) with a point in time. Technotes can be used |
| @@ -536,11 +536,11 @@ | ||
| 536 | 536 | technote. The format of the <b>W</b> card is exactly the same as for a |
| 537 | 537 | [#wikichng | wiki artifact]. |
| 538 | 538 | |
| 539 | 539 | The <b>Z</b> card is the required checksum over the rest of the artifact. |
| 540 | 540 | |
| 541 | -<a name="forum"></a> | |
| 541 | +<a id="forum"></a> | |
| 542 | 542 | <h3>2.8 Forum Posts</h3> |
| 543 | 543 | |
| 544 | 544 | Forum posts are intended as a mechanism for users and developers to |
| 545 | 545 | discuss a project. Forum posts are like messages on a mailing list. |
| 546 | 546 | |
| @@ -611,11 +611,11 @@ | ||
| 611 | 611 | [#wikichng | wiki artifact]. |
| 612 | 612 | |
| 613 | 613 | The <b>Z</b> card is the required checksum over the rest of the artifact. |
| 614 | 614 | |
| 615 | 615 | |
| 616 | -<a name="summary"></a> | |
| 616 | +<a id="summary"></a> | |
| 617 | 617 | <h2>3.0 Card Summary</h2> |
| 618 | 618 | |
| 619 | 619 | The following table summarizes the various kinds of cards that appear |
| 620 | 620 | on Fossil artifacts. A blank entry means that combination of card and |
| 621 | 621 | artifact is not legal. A number or range of numbers indicates the number |
| @@ -722,11 +722,11 @@ | ||
| 722 | 722 | <td> </td> |
| 723 | 723 | <td> </td> |
| 724 | 724 | <td> </td> |
| 725 | 725 | <td> </td> |
| 726 | 726 | <td> </td> |
| 727 | -<td align=center><b>0-1</b></td> | |
| 727 | +<td align=center><b>0-1</b><sup><nowiki>[4]</nowiki></sup></td> | |
| 728 | 728 | </tr> |
| 729 | 729 | <tr> |
| 730 | 730 | <td><b>I</b> <i>in-reply-to</i></td> |
| 731 | 731 | <td> </td> |
| 732 | 732 | <td> </td> |
| @@ -733,11 +733,11 @@ | ||
| 733 | 733 | <td> </td> |
| 734 | 734 | <td> </td> |
| 735 | 735 | <td> </td> |
| 736 | 736 | <td> </td> |
| 737 | 737 | <td> </td> |
| 738 | -<td align=center><b>0-1</b></td> | |
| 738 | +<td align=center><b>0-1</b><sup><nowiki>[4]</nowiki></sup></td> | |
| 739 | 739 | </tr> |
| 740 | 740 | <tr> |
| 741 | 741 | <td><b>J</b> <i>name</i> ?<i>value</i>?</td> |
| 742 | 742 | <td> </td> |
| 743 | 743 | <td> </td> |
| @@ -799,11 +799,11 @@ | ||
| 799 | 799 | <td> </td> |
| 800 | 800 | <td align=center><b>0-1</b></td> |
| 801 | 801 | <td> </td> |
| 802 | 802 | <td> </td> |
| 803 | 803 | <td align=center><b>0-1</b></td> |
| 804 | -<td align=center><b>0-1</b></td> | |
| 804 | +<td align=center><b>0-1</b><sup><nowiki>[5]</nowiki></sup></td> | |
| 805 | 805 | </tr> |
| 806 | 806 | <tr> |
| 807 | 807 | <td><b>Q</b> (<b>+</b>|<b>-</b>)<i>uuid</i> ?<i>uuid</i>?</td> |
| 808 | 808 | <td align=center><b>0+</b></td> |
| 809 | 809 | <td> </td> |
| @@ -823,18 +823,18 @@ | ||
| 823 | 823 | <td> </td> |
| 824 | 824 | <td> </td> |
| 825 | 825 | <td> </td> |
| 826 | 826 | <td> </td> |
| 827 | 827 | <tr> |
| 828 | -<td><b>T</b> (<b>+</b>|<b>*</b>|<b>-</b>)<i>tagname</i> <i>uuid</i> ?<i>value</i>?</td> | |
| 828 | +<td><b>T</b> (<b>+</b>|<b>*</b>|<b>-</b>)<i>tagname</i> <i>uuid</i> ?<i>value</i>?<sup><nowiki>[1]</nowiki></sup></td> | |
| 829 | 829 | <td align=center><b>0+</b></td> |
| 830 | 830 | <td> </td> |
| 831 | -<td align=center><b>1+</b></td> | |
| 831 | +<td align=center><b>1+</b><sup><nowiki>[2]</nowiki></sup></td> | |
| 832 | 832 | <td> </td> |
| 833 | 833 | <td> </td> |
| 834 | 834 | <td> </td> |
| 835 | -<td align=center><b>0+</b></td> | |
| 835 | +<td align=center><b>0+</b><sup><nowiki>[3]</nowiki></sup></td> | |
| 836 | 836 | <td> </td> |
| 837 | 837 | </tr> |
| 838 | 838 | <tr> |
| 839 | 839 | <td><b>U</b> <i>username</i></td> |
| 840 | 840 | <td align=center><b>1</b></td> |
| @@ -868,18 +868,34 @@ | ||
| 868 | 868 | <td align=center><b>1</b></td> |
| 869 | 869 | <td align=center><b>1</b></td> |
| 870 | 870 | </tr> |
| 871 | 871 | </table> |
| 872 | 872 | |
| 873 | +Footnotes: | |
| 874 | + | |
| 875 | +1) T-card names may not be made up of only hexadecimal characters, as | |
| 876 | + they would be indistinguishable from a hash prefix. | |
| 877 | + | |
| 878 | +2) Tags in [#ctrl | Control Artifacts] may not be | |
| 879 | + self-referential. i.e. they may not start with <tt>*</tt>. | |
| 880 | + | |
| 881 | +3) Tags in [#event | Technotes] must be self-referential. i.e. they | |
| 882 | + must start with <tt>*</tt>. | |
| 883 | + | |
| 884 | +4) [#forum | Forum Posts] must have either one H-card or one | |
| 885 | + I-card, not both. | |
| 886 | + | |
| 887 | +5) [#forum | Forum Post] P-cards must have only a single parent | |
| 888 | + hash. i.e. they may not have merge parents. | |
| 873 | 889 | |
| 874 | -<a name="addenda"></a> | |
| 890 | +<a id="addenda"></a> | |
| 875 | 891 | <h2>4.0 Addenda</h2> |
| 876 | 892 | |
| 877 | 893 | This section contains additional information which may be useful when |
| 878 | 894 | implementing algorithms described above. |
| 879 | 895 | |
| 880 | -<a name="outofordercards"></a> | |
| 896 | +<a id="outofordercards"></a> | |
| 881 | 897 | <h3>4.1 Relaxed Card Ordering Due To An Historical Bug</h3> |
| 882 | 898 | |
| 883 | 899 | All cards of a structural artifact should be in lexicographical order. |
| 884 | 900 | The Fossil implementation verifies this and rejects any structural |
| 885 | 901 | artifact which has out-of-order cards. Futhermore, when Fossil is |
| 886 | 902 |
| --- www/fileformat.wiki | |
| +++ www/fileformat.wiki | |
| @@ -32,11 +32,11 @@ | |
| 32 | with the global state. |
| 33 | The local state is not composed of artifacts and is not intended to be enduring. |
| 34 | This document is concerned with global state only. Local state is only |
| 35 | mentioned here in order to distinguish it from global state. |
| 36 | |
| 37 | <a name="names"></a> |
| 38 | <h2>1.0 Artifact Names</h2> |
| 39 | |
| 40 | Each artifact in the repository is named by a hash of its content. |
| 41 | No prefixes, suffixes, or other information is added to an artifact before |
| 42 | the hash is computed. The artifact name is just the (lower-case |
| @@ -54,11 +54,11 @@ | |
| 54 | |
| 55 | Prior to Fossil version 2.0, all names were formed from the SHA1 hash of |
| 56 | the artifact. The key innovation in Fossil 2.0 was adding support for |
| 57 | alternative hash algorithms. |
| 58 | |
| 59 | <a name="structural"></a> |
| 60 | <h2>2.0 Structural Artifacts</h2> |
| 61 | |
| 62 | A structural artifact is an artifact with a particular format |
| 63 | that is used to define the relationships between other artifacts in the |
| 64 | repository. |
| @@ -100,11 +100,11 @@ | |
| 100 | not how the artifacts are stored on disk. It is the artifact format that |
| 101 | is intended to be enduring. The specifics of how artifacts are stored on |
| 102 | disk, though stable, is not intended to live as long as the |
| 103 | artifact format. |
| 104 | |
| 105 | <a name="manifest"></a> |
| 106 | <h3>2.1 The Manifest</h3> |
| 107 | |
| 108 | A manifest defines a check-in. |
| 109 | A manifest contains a list of artifacts for |
| 110 | each file in the project and the corresponding filenames, as |
| @@ -256,11 +256,11 @@ | |
| 256 | consistent. |
| 257 | |
| 258 | A sample manifest from Fossil itself can be seen |
| 259 | [/artifact/28987096ac | here]. |
| 260 | |
| 261 | <a name="cluster"></a> |
| 262 | <h3>2.2 Clusters</h3> |
| 263 | |
| 264 | A cluster is an artifact that declares the existence of other artifacts. |
| 265 | Clusters are used during repository synchronization to help |
| 266 | reduce network traffic. As such, clusters are an optimization and |
| @@ -282,11 +282,11 @@ | |
| 282 | prior cards in the cluster. The <b>Z</b> card is required. |
| 283 | |
| 284 | An example cluster from Fossil can be seen |
| 285 | [/artifact/d03dbdd73a2a8 | here]. |
| 286 | |
| 287 | <a name="ctrl"></a> |
| 288 | <h3>2.3 Control Artifacts</h3> |
| 289 | |
| 290 | Control artifacts are used to assign properties to other artifacts |
| 291 | within the repository. |
| 292 | Allowed cards in a control artifact are as follows: |
| @@ -336,11 +336,11 @@ | |
| 336 | artifact. The <b>Z</b> card is the usual required artifact checksum. |
| 337 | |
| 338 | An example control artifacts can be seen [/info/9d302ccda8 | here]. |
| 339 | |
| 340 | |
| 341 | <a name="wikichng"></a> |
| 342 | <h3>2.4 Wiki Pages</h3> |
| 343 | |
| 344 | A wiki artifact defines a single version of a |
| 345 | single wiki page. |
| 346 | Wiki artifacts accept |
| @@ -380,11 +380,11 @@ | |
| 380 | artifact that includes a <b>C</b> card. |
| 381 | |
| 382 | An example wiki artifact can be seen |
| 383 | [/artifact?name=7b2f5fd0e0&txt=1 | here]. |
| 384 | |
| 385 | <a name="tktchng"></a> |
| 386 | <h3>2.5 Ticket Changes</h3> |
| 387 | |
| 388 | A ticket-change artifact represents a change to a trouble ticket. |
| 389 | The following cards are allowed on a ticket change artifact: |
| 390 | |
| @@ -426,11 +426,11 @@ | |
| 426 | escapes defined for the <b>C</b> card of a manifest. |
| 427 | |
| 428 | An example ticket-change artifact can be seen |
| 429 | [/artifact/91f1ec6af053 | here]. |
| 430 | |
| 431 | <a name="attachment"></a> |
| 432 | <h3>2.6 Attachments</h3> |
| 433 | |
| 434 | An attachment artifact associates some other artifact that is the |
| 435 | attachment (the source artifact) with a ticket or wiki page or |
| 436 | technical note to which |
| @@ -468,11 +468,11 @@ | |
| 468 | |
| 469 | The <b>Z</b> card is the usual checksum over the rest of the attachment artifact. |
| 470 | The <b>Z</b> card is required. |
| 471 | |
| 472 | |
| 473 | <a name="event"></a> |
| 474 | <h3>2.7 Technical Notes</h3> |
| 475 | |
| 476 | A technical note or "technote" artifact (formerly known as an "event" artifact) |
| 477 | associates a timeline comment and a page of text |
| 478 | (similar to a wiki page) with a point in time. Technotes can be used |
| @@ -536,11 +536,11 @@ | |
| 536 | technote. The format of the <b>W</b> card is exactly the same as for a |
| 537 | [#wikichng | wiki artifact]. |
| 538 | |
| 539 | The <b>Z</b> card is the required checksum over the rest of the artifact. |
| 540 | |
| 541 | <a name="forum"></a> |
| 542 | <h3>2.8 Forum Posts</h3> |
| 543 | |
| 544 | Forum posts are intended as a mechanism for users and developers to |
| 545 | discuss a project. Forum posts are like messages on a mailing list. |
| 546 | |
| @@ -611,11 +611,11 @@ | |
| 611 | [#wikichng | wiki artifact]. |
| 612 | |
| 613 | The <b>Z</b> card is the required checksum over the rest of the artifact. |
| 614 | |
| 615 | |
| 616 | <a name="summary"></a> |
| 617 | <h2>3.0 Card Summary</h2> |
| 618 | |
| 619 | The following table summarizes the various kinds of cards that appear |
| 620 | on Fossil artifacts. A blank entry means that combination of card and |
| 621 | artifact is not legal. A number or range of numbers indicates the number |
| @@ -722,11 +722,11 @@ | |
| 722 | <td> </td> |
| 723 | <td> </td> |
| 724 | <td> </td> |
| 725 | <td> </td> |
| 726 | <td> </td> |
| 727 | <td align=center><b>0-1</b></td> |
| 728 | </tr> |
| 729 | <tr> |
| 730 | <td><b>I</b> <i>in-reply-to</i></td> |
| 731 | <td> </td> |
| 732 | <td> </td> |
| @@ -733,11 +733,11 @@ | |
| 733 | <td> </td> |
| 734 | <td> </td> |
| 735 | <td> </td> |
| 736 | <td> </td> |
| 737 | <td> </td> |
| 738 | <td align=center><b>0-1</b></td> |
| 739 | </tr> |
| 740 | <tr> |
| 741 | <td><b>J</b> <i>name</i> ?<i>value</i>?</td> |
| 742 | <td> </td> |
| 743 | <td> </td> |
| @@ -799,11 +799,11 @@ | |
| 799 | <td> </td> |
| 800 | <td align=center><b>0-1</b></td> |
| 801 | <td> </td> |
| 802 | <td> </td> |
| 803 | <td align=center><b>0-1</b></td> |
| 804 | <td align=center><b>0-1</b></td> |
| 805 | </tr> |
| 806 | <tr> |
| 807 | <td><b>Q</b> (<b>+</b>|<b>-</b>)<i>uuid</i> ?<i>uuid</i>?</td> |
| 808 | <td align=center><b>0+</b></td> |
| 809 | <td> </td> |
| @@ -823,18 +823,18 @@ | |
| 823 | <td> </td> |
| 824 | <td> </td> |
| 825 | <td> </td> |
| 826 | <td> </td> |
| 827 | <tr> |
| 828 | <td><b>T</b> (<b>+</b>|<b>*</b>|<b>-</b>)<i>tagname</i> <i>uuid</i> ?<i>value</i>?</td> |
| 829 | <td align=center><b>0+</b></td> |
| 830 | <td> </td> |
| 831 | <td align=center><b>1+</b></td> |
| 832 | <td> </td> |
| 833 | <td> </td> |
| 834 | <td> </td> |
| 835 | <td align=center><b>0+</b></td> |
| 836 | <td> </td> |
| 837 | </tr> |
| 838 | <tr> |
| 839 | <td><b>U</b> <i>username</i></td> |
| 840 | <td align=center><b>1</b></td> |
| @@ -868,18 +868,34 @@ | |
| 868 | <td align=center><b>1</b></td> |
| 869 | <td align=center><b>1</b></td> |
| 870 | </tr> |
| 871 | </table> |
| 872 | |
| 873 | |
| 874 | <a name="addenda"></a> |
| 875 | <h2>4.0 Addenda</h2> |
| 876 | |
| 877 | This section contains additional information which may be useful when |
| 878 | implementing algorithms described above. |
| 879 | |
| 880 | <a name="outofordercards"></a> |
| 881 | <h3>4.1 Relaxed Card Ordering Due To An Historical Bug</h3> |
| 882 | |
| 883 | All cards of a structural artifact should be in lexicographical order. |
| 884 | The Fossil implementation verifies this and rejects any structural |
| 885 | artifact which has out-of-order cards. Futhermore, when Fossil is |
| 886 |
| --- www/fileformat.wiki | |
| +++ www/fileformat.wiki | |
| @@ -32,11 +32,11 @@ | |
| 32 | with the global state. |
| 33 | The local state is not composed of artifacts and is not intended to be enduring. |
| 34 | This document is concerned with global state only. Local state is only |
| 35 | mentioned here in order to distinguish it from global state. |
| 36 | |
| 37 | <a id="names"></a> |
| 38 | <h2>1.0 Artifact Names</h2> |
| 39 | |
| 40 | Each artifact in the repository is named by a hash of its content. |
| 41 | No prefixes, suffixes, or other information is added to an artifact before |
| 42 | the hash is computed. The artifact name is just the (lower-case |
| @@ -54,11 +54,11 @@ | |
| 54 | |
| 55 | Prior to Fossil version 2.0, all names were formed from the SHA1 hash of |
| 56 | the artifact. The key innovation in Fossil 2.0 was adding support for |
| 57 | alternative hash algorithms. |
| 58 | |
| 59 | <a id="structural"></a> |
| 60 | <h2>2.0 Structural Artifacts</h2> |
| 61 | |
| 62 | A structural artifact is an artifact with a particular format |
| 63 | that is used to define the relationships between other artifacts in the |
| 64 | repository. |
| @@ -100,11 +100,11 @@ | |
| 100 | not how the artifacts are stored on disk. It is the artifact format that |
| 101 | is intended to be enduring. The specifics of how artifacts are stored on |
| 102 | disk, though stable, is not intended to live as long as the |
| 103 | artifact format. |
| 104 | |
| 105 | <a id="manifest"></a> |
| 106 | <h3>2.1 The Manifest</h3> |
| 107 | |
| 108 | A manifest defines a check-in. |
| 109 | A manifest contains a list of artifacts for |
| 110 | each file in the project and the corresponding filenames, as |
| @@ -256,11 +256,11 @@ | |
| 256 | consistent. |
| 257 | |
| 258 | A sample manifest from Fossil itself can be seen |
| 259 | [/artifact/28987096ac | here]. |
| 260 | |
| 261 | <a id="cluster"></a> |
| 262 | <h3>2.2 Clusters</h3> |
| 263 | |
| 264 | A cluster is an artifact that declares the existence of other artifacts. |
| 265 | Clusters are used during repository synchronization to help |
| 266 | reduce network traffic. As such, clusters are an optimization and |
| @@ -282,11 +282,11 @@ | |
| 282 | prior cards in the cluster. The <b>Z</b> card is required. |
| 283 | |
| 284 | An example cluster from Fossil can be seen |
| 285 | [/artifact/d03dbdd73a2a8 | here]. |
| 286 | |
| 287 | <a id="ctrl"></a> |
| 288 | <h3>2.3 Control Artifacts</h3> |
| 289 | |
| 290 | Control artifacts are used to assign properties to other artifacts |
| 291 | within the repository. |
| 292 | Allowed cards in a control artifact are as follows: |
| @@ -336,11 +336,11 @@ | |
| 336 | artifact. The <b>Z</b> card is the usual required artifact checksum. |
| 337 | |
| 338 | An example control artifacts can be seen [/info/9d302ccda8 | here]. |
| 339 | |
| 340 | |
| 341 | <a id="wikichng"></a> |
| 342 | <h3>2.4 Wiki Pages</h3> |
| 343 | |
| 344 | A wiki artifact defines a single version of a |
| 345 | single wiki page. |
| 346 | Wiki artifacts accept |
| @@ -380,11 +380,11 @@ | |
| 380 | artifact that includes a <b>C</b> card. |
| 381 | |
| 382 | An example wiki artifact can be seen |
| 383 | [/artifact?name=7b2f5fd0e0&txt=1 | here]. |
| 384 | |
| 385 | <a id="tktchng"></a> |
| 386 | <h3>2.5 Ticket Changes</h3> |
| 387 | |
| 388 | A ticket-change artifact represents a change to a trouble ticket. |
| 389 | The following cards are allowed on a ticket change artifact: |
| 390 | |
| @@ -426,11 +426,11 @@ | |
| 426 | escapes defined for the <b>C</b> card of a manifest. |
| 427 | |
| 428 | An example ticket-change artifact can be seen |
| 429 | [/artifact/91f1ec6af053 | here]. |
| 430 | |
| 431 | <a id="attachment"></a> |
| 432 | <h3>2.6 Attachments</h3> |
| 433 | |
| 434 | An attachment artifact associates some other artifact that is the |
| 435 | attachment (the source artifact) with a ticket or wiki page or |
| 436 | technical note to which |
| @@ -468,11 +468,11 @@ | |
| 468 | |
| 469 | The <b>Z</b> card is the usual checksum over the rest of the attachment artifact. |
| 470 | The <b>Z</b> card is required. |
| 471 | |
| 472 | |
| 473 | <a id="event"></a> |
| 474 | <h3>2.7 Technical Notes</h3> |
| 475 | |
| 476 | A technical note or "technote" artifact (formerly known as an "event" artifact) |
| 477 | associates a timeline comment and a page of text |
| 478 | (similar to a wiki page) with a point in time. Technotes can be used |
| @@ -536,11 +536,11 @@ | |
| 536 | technote. The format of the <b>W</b> card is exactly the same as for a |
| 537 | [#wikichng | wiki artifact]. |
| 538 | |
| 539 | The <b>Z</b> card is the required checksum over the rest of the artifact. |
| 540 | |
| 541 | <a id="forum"></a> |
| 542 | <h3>2.8 Forum Posts</h3> |
| 543 | |
| 544 | Forum posts are intended as a mechanism for users and developers to |
| 545 | discuss a project. Forum posts are like messages on a mailing list. |
| 546 | |
| @@ -611,11 +611,11 @@ | |
| 611 | [#wikichng | wiki artifact]. |
| 612 | |
| 613 | The <b>Z</b> card is the required checksum over the rest of the artifact. |
| 614 | |
| 615 | |
| 616 | <a id="summary"></a> |
| 617 | <h2>3.0 Card Summary</h2> |
| 618 | |
| 619 | The following table summarizes the various kinds of cards that appear |
| 620 | on Fossil artifacts. A blank entry means that combination of card and |
| 621 | artifact is not legal. A number or range of numbers indicates the number |
| @@ -722,11 +722,11 @@ | |
| 722 | <td> </td> |
| 723 | <td> </td> |
| 724 | <td> </td> |
| 725 | <td> </td> |
| 726 | <td> </td> |
| 727 | <td align=center><b>0-1</b><sup><nowiki>[4]</nowiki></sup></td> |
| 728 | </tr> |
| 729 | <tr> |
| 730 | <td><b>I</b> <i>in-reply-to</i></td> |
| 731 | <td> </td> |
| 732 | <td> </td> |
| @@ -733,11 +733,11 @@ | |
| 733 | <td> </td> |
| 734 | <td> </td> |
| 735 | <td> </td> |
| 736 | <td> </td> |
| 737 | <td> </td> |
| 738 | <td align=center><b>0-1</b><sup><nowiki>[4]</nowiki></sup></td> |
| 739 | </tr> |
| 740 | <tr> |
| 741 | <td><b>J</b> <i>name</i> ?<i>value</i>?</td> |
| 742 | <td> </td> |
| 743 | <td> </td> |
| @@ -799,11 +799,11 @@ | |
| 799 | <td> </td> |
| 800 | <td align=center><b>0-1</b></td> |
| 801 | <td> </td> |
| 802 | <td> </td> |
| 803 | <td align=center><b>0-1</b></td> |
| 804 | <td align=center><b>0-1</b><sup><nowiki>[5]</nowiki></sup></td> |
| 805 | </tr> |
| 806 | <tr> |
| 807 | <td><b>Q</b> (<b>+</b>|<b>-</b>)<i>uuid</i> ?<i>uuid</i>?</td> |
| 808 | <td align=center><b>0+</b></td> |
| 809 | <td> </td> |
| @@ -823,18 +823,18 @@ | |
| 823 | <td> </td> |
| 824 | <td> </td> |
| 825 | <td> </td> |
| 826 | <td> </td> |
| 827 | <tr> |
| 828 | <td><b>T</b> (<b>+</b>|<b>*</b>|<b>-</b>)<i>tagname</i> <i>uuid</i> ?<i>value</i>?<sup><nowiki>[1]</nowiki></sup></td> |
| 829 | <td align=center><b>0+</b></td> |
| 830 | <td> </td> |
| 831 | <td align=center><b>1+</b><sup><nowiki>[2]</nowiki></sup></td> |
| 832 | <td> </td> |
| 833 | <td> </td> |
| 834 | <td> </td> |
| 835 | <td align=center><b>0+</b><sup><nowiki>[3]</nowiki></sup></td> |
| 836 | <td> </td> |
| 837 | </tr> |
| 838 | <tr> |
| 839 | <td><b>U</b> <i>username</i></td> |
| 840 | <td align=center><b>1</b></td> |
| @@ -868,18 +868,34 @@ | |
| 868 | <td align=center><b>1</b></td> |
| 869 | <td align=center><b>1</b></td> |
| 870 | </tr> |
| 871 | </table> |
| 872 | |
| 873 | Footnotes: |
| 874 | |
| 875 | 1) T-card names may not be made up of only hexadecimal characters, as |
| 876 | they would be indistinguishable from a hash prefix. |
| 877 | |
| 878 | 2) Tags in [#ctrl | Control Artifacts] may not be |
| 879 | self-referential. i.e. they may not start with <tt>*</tt>. |
| 880 | |
| 881 | 3) Tags in [#event | Technotes] must be self-referential. i.e. they |
| 882 | must start with <tt>*</tt>. |
| 883 | |
| 884 | 4) [#forum | Forum Posts] must have either one H-card or one |
| 885 | I-card, not both. |
| 886 | |
| 887 | 5) [#forum | Forum Post] P-cards must have only a single parent |
| 888 | hash. i.e. they may not have merge parents. |
| 889 | |
| 890 | <a id="addenda"></a> |
| 891 | <h2>4.0 Addenda</h2> |
| 892 | |
| 893 | This section contains additional information which may be useful when |
| 894 | implementing algorithms described above. |
| 895 | |
| 896 | <a id="outofordercards"></a> |
| 897 | <h3>4.1 Relaxed Card Ordering Due To An Historical Bug</h3> |
| 898 | |
| 899 | All cards of a structural artifact should be in lexicographical order. |
| 900 | The Fossil implementation verifies this and rejects any structural |
| 901 | artifact which has out-of-order cards. Futhermore, when Fossil is |
| 902 |