Fossil SCM
Improved introduction to "forum.wiki"
Commit
44ab80ea2bbdaf1780cdc40a57d490f6826ffee3e55181d57a8a394a5808ddb9
Parent
13c95f0c7537746…
1 file changed
+53
-99
+53
-99
| --- www/forum.wiki | ||
| +++ www/forum.wiki | ||
| @@ -1,113 +1,67 @@ | ||
| 1 | 1 | <title>Fossil Forums</title> |
| 2 | 2 | |
| 3 | 3 | <h2>Introduction</h2> |
| 4 | 4 | |
| 5 | -As of Fossil 2.7, Fossil includes a built-in discussion forum feature. | |
| 6 | - | |
| 7 | -Any project complex enough to benefit from being managed by Fossil and | |
| 8 | -which has more than one user can probably also benefit from having a | |
| 9 | -discussion forum. Even if your project has a discussion forum already, | |
| 10 | -there are many benefits to using Fossil's built-in forum feature, some | |
| 11 | -of which you cannot get by using third-party alternatives: | |
| 12 | - | |
| 13 | - * <b>Easy to Administer:</b> Third-party discussion forum and mailing | |
| 14 | - list software tends to be difficult to install, set up, and | |
| 15 | - administer. The Fossil forum feature aims to be as close to | |
| 16 | - zero-configuration as is practical. | |
| 5 | +Fossil includes a built-in discussion forum, designed to substitute | |
| 6 | +for a mailing list. Email notification is available to receive posts, | |
| 7 | +but the web-based UI must be used to enter new posts. Advantages of | |
| 8 | +the forum include: | |
| 9 | + | |
| 10 | + * <b>Easy to Administer:</b> If you have already set up a | |
| 11 | + [./server/|Fossil server] with [./alerts.md|email alerts] | |
| 12 | + then turning on the forum feature | |
| 13 | + is just a matter of flipping some permission bits. There is | |
| 14 | + no new software to install and configure, and the same logins | |
| 15 | + and passwords work. | |
| 17 | 16 | |
| 18 | 17 | * <b>Malefactor Resistant:</b> Because Fossil accepts forum posts |
| 19 | - only via the web UI, it is inherently [./antibot.wiki | protected | |
| 20 | - against bots]. | |
| 18 | + only via the web UI, it is more resistent to spam. Passers-by | |
| 19 | + can post to the forum anonymously (subject to moderation), without | |
| 20 | + the hassle of a sign-up process. | |
| 21 | 21 | |
| 22 | 22 | * <b>Distributed and Tamper-Proof:</b> Posts are stored in the Fossil |
| 23 | - repository using the same [./fileformat.wiki | block chain technology] | |
| 23 | + repository using the same [./fileformat.wiki | DAG/Merkle-tree design] | |
| 24 | 24 | that Fossil uses to store your check-ins, wiki documents, etc. |
| 25 | - Posts sync to cloned repositories in a tamper-proof fashion. | |
| 26 | - | |
| 27 | - * <b>Space Efficient:</b> Because of Fossil's [./delta_format.wiki | | |
| 28 | - delta compression technology], discussions add little to the size | |
| 29 | - of a cloned repository. Ten years of the SQLite project's | |
| 30 | - discussions — averaging about 2 dozen posts per day — compress down | |
| 31 | - to [https://fossil-scm.org/forum/forumpost/9b6f3f36bdb | just | |
| 32 | - 35 MB of space] in a Fossil forum repository. | |
| 33 | - | |
| 34 | - * <b>Built-in Full-Text Search:</b> Fossil forums use | |
| 35 | - [https://sqlite.org/fts3.html | SQLite's powerful FTS4 engine] to | |
| 36 | - handle searches. If your project currently uses a mailing list for | |
| 37 | - discussions, this means you are no longer reliant upon third-party | |
| 38 | - mailing list archive services to provide a useful search engine for | |
| 39 | - your discussions. If you are running a private Fossil repository, | |
| 40 | - you may not even have the <em>option</em> of delegating this useful | |
| 41 | - service to a third-party; Fossil provides this service out of the | |
| 42 | - box. | |
| 43 | - | |
| 44 | - * <b>One Result Per Matching Post:</b> When you search the forum | |
| 45 | - archives via the Fossil web interface, you get only one result for | |
| 46 | - each matching post. When you search for project information via a | |
| 47 | - standard web search engine, you might get a result from the project | |
| 48 | - site's own mail archive plus one from Nabble, one from Gmane, one | |
| 49 | - from The Mail Archive... | |
| 50 | - | |
| 51 | - * <b>Search Off-Line:</b> Because Fossil is a [./concepts.wiki | | |
| 52 | - distributed version control system], project members can search | |
| 53 | - your forum archive while disconnected from the network where the | |
| 54 | - central Fossil instance runs. Your past discussions are potentially | |
| 55 | - just as valuable as a wiki document or checkin comment: there is no | |
| 56 | - good reason why you should have to wait to get back on the Internet | |
| 57 | - or back to the office before you can search for past posts. | |
| 58 | - | |
| 59 | - * <b>Contribute Off-Line:</b> Fossil forum posts work like any other | |
| 60 | - insertion into the repository, so a user can create new threads and | |
| 61 | - reply to existing ones while off-line, then sync their | |
| 62 | - contributions to the server they cloned from when back on-line. | |
| 63 | - Yes, you can post to the forum from inside a tent, miles from the | |
| 64 | - nearest WiFi router or cellular data tower. | |
| 65 | - | |
| 66 | - * <b>Interlink with Other Fossil-Managed Artifacts:</b> Because forum | |
| 67 | - posts are normal Fossil artifacts, you can interlink them with | |
| 68 | - other Fossil artifacts using short internal links: link to forum | |
| 69 | - threads from a [./tickets.wiki | ticket], link to a wiki document | |
| 70 | - from a forum post, etc. | |
| 71 | - | |
| 72 | - * <b>Durable Links:</b> Once you create a valid internal artifact | |
| 73 | - link in Fossil, it <em>remains</em> valid, durably. With | |
| 74 | - third-party forum software and mailing list search engines, your | |
| 75 | - links are only valid until the third-party component changes its | |
| 76 | - URL scheme or disappears from the web. | |
| 77 | - | |
| 78 | - * <b>Role-Based Access Control:</b> The forum uses the same | |
| 79 | - [./caps/ | capability-based access control | |
| 80 | - system] that Fossil uses to control all other repository accesses. | |
| 81 | - The Fossil forum feature simply adds [./caps/ref.html#2 | several new fine-grained | |
| 82 | - capabilities] to the existing system. | |
| 83 | - | |
| 84 | - * <b>Enduring, Open File Format:</b> Since Fossil has an | |
| 85 | - [./fileformat.wiki | open and well-documented file format], your | |
| 86 | - discussion archives are truly that: <em>archives</em>. You are no | |
| 87 | - longer dependent on the lifetime and business model of a | |
| 88 | - third-party piece of software or service. Should you choose to stop | |
| 89 | - using Fossil, you can easily extract your discussion traffic for | |
| 90 | - transfer to another system. | |
| 91 | - | |
| 92 | - * <b>Lightweight Markup:</b> Posts can be marked up using Fossil's | |
| 93 | - existing [/md_rules | Markdown] and [/wiki_rules | Wiki] markup | |
| 94 | - processors. No longer must you choose between two bad options: to | |
| 95 | - restrict posts to plain text only or to allow wild-west | |
| 96 | - HTML-formatted MIME email. Fossil's lightweight markup language | |
| 97 | - formatting features give you a middle path, providing your users | |
| 98 | - enough formatting power to communicate complex ideas well without | |
| 99 | - providing so much power as to risk | |
| 100 | - [https://wonko.com/post/html-escaping | security problems]. | |
| 101 | - | |
| 102 | - * <b>Easy Email Alerts:</b> You can configure Fossil to | |
| 103 | - [./alerts.md | send email alerts]. Forum post emails include the | |
| 104 | - complete message content for the benefit of those that prefer to | |
| 105 | - visit the forum only when they need to post something. Alerts are | |
| 106 | - optional, and each user gets the choice of immediate or daily | |
| 107 | - digest delivery. | |
| 108 | - | |
| 25 | + Forum posts sync to cloned repositories. | |
| 26 | + | |
| 27 | + * <b>Editable:</b> Forum posts can be amended after they are sent, | |
| 28 | + to fix typos or provide updates. The original posts are preserved | |
| 29 | + as part of the historical record, but only the amended posts are | |
| 30 | + displayed by default. | |
| 31 | + | |
| 32 | + * <b>Built-in Full-Text Search:</b> Forum posts can be included in | |
| 33 | + the index used by the built-in Fossil search logic. | |
| 34 | + | |
| 35 | + * <b>Off-Line Access:</b> Because forum posts are synced along with | |
| 36 | + all other artifacts, you can search the forum, or add new posts | |
| 37 | + to the forum, while off-line. | |
| 38 | + | |
| 39 | + * <b>Automatically Cross-Referenced To Other Fossil Artifacts:</b> Because forum | |
| 40 | + posts are normal Fossil artifacts, you can link from them to | |
| 41 | + other Fossil artifacts (check-ins, wiki, tickets) and from those other | |
| 42 | + artifacts to forum posts. The reverse links are recognized and | |
| 43 | + displayed automatically on the receiver. | |
| 44 | + | |
| 45 | + * <b>Consistent Display:</b> Forum posts can be in Markdown, | |
| 46 | + Fossil Wiki, or plain text. Whichever format is used, the result is | |
| 47 | + displayed consistently across all platforms, including mobile. | |
| 48 | + | |
| 49 | +<h2>Example Installations</h2> | |
| 50 | + | |
| 51 | +Both the [forum:/forum|Fossil project itself] and the | |
| 52 | +[https://sqlite.org/forum/forum|SQLite project] use the Fossil forum in place | |
| 53 | +of mailing lists. The forum has worked well on both projects. The ability | |
| 54 | +to post anonymously provides a low-resistance path for people to report | |
| 55 | +problems, resulting in more problems being reported and fixed. | |
| 56 | +The ability to moderate and amend forum posts means that the | |
| 57 | +forums contain better information. And backups and archives | |
| 58 | +are as easy as running "clone". | |
| 59 | + | |
| 60 | +Both Fossil and SQLite keep their forums as separate repositories. | |
| 61 | +But there is no requirement to do this. A forum can be coresident in | |
| 62 | +the same repository with the source code. | |
| 109 | 63 | |
| 110 | 64 | <h2 id="setup">Setting up a Fossil Forum</h2> |
| 111 | 65 | |
| 112 | 66 | <h3 id="caps">Capabilities</h3> |
| 113 | 67 | |
| 114 | 68 |
| --- www/forum.wiki | |
| +++ www/forum.wiki | |
| @@ -1,113 +1,67 @@ | |
| 1 | <title>Fossil Forums</title> |
| 2 | |
| 3 | <h2>Introduction</h2> |
| 4 | |
| 5 | As of Fossil 2.7, Fossil includes a built-in discussion forum feature. |
| 6 | |
| 7 | Any project complex enough to benefit from being managed by Fossil and |
| 8 | which has more than one user can probably also benefit from having a |
| 9 | discussion forum. Even if your project has a discussion forum already, |
| 10 | there are many benefits to using Fossil's built-in forum feature, some |
| 11 | of which you cannot get by using third-party alternatives: |
| 12 | |
| 13 | * <b>Easy to Administer:</b> Third-party discussion forum and mailing |
| 14 | list software tends to be difficult to install, set up, and |
| 15 | administer. The Fossil forum feature aims to be as close to |
| 16 | zero-configuration as is practical. |
| 17 | |
| 18 | * <b>Malefactor Resistant:</b> Because Fossil accepts forum posts |
| 19 | only via the web UI, it is inherently [./antibot.wiki | protected |
| 20 | against bots]. |
| 21 | |
| 22 | * <b>Distributed and Tamper-Proof:</b> Posts are stored in the Fossil |
| 23 | repository using the same [./fileformat.wiki | block chain technology] |
| 24 | that Fossil uses to store your check-ins, wiki documents, etc. |
| 25 | Posts sync to cloned repositories in a tamper-proof fashion. |
| 26 | |
| 27 | * <b>Space Efficient:</b> Because of Fossil's [./delta_format.wiki | |
| 28 | delta compression technology], discussions add little to the size |
| 29 | of a cloned repository. Ten years of the SQLite project's |
| 30 | discussions — averaging about 2 dozen posts per day — compress down |
| 31 | to [https://fossil-scm.org/forum/forumpost/9b6f3f36bdb | just |
| 32 | 35 MB of space] in a Fossil forum repository. |
| 33 | |
| 34 | * <b>Built-in Full-Text Search:</b> Fossil forums use |
| 35 | [https://sqlite.org/fts3.html | SQLite's powerful FTS4 engine] to |
| 36 | handle searches. If your project currently uses a mailing list for |
| 37 | discussions, this means you are no longer reliant upon third-party |
| 38 | mailing list archive services to provide a useful search engine for |
| 39 | your discussions. If you are running a private Fossil repository, |
| 40 | you may not even have the <em>option</em> of delegating this useful |
| 41 | service to a third-party; Fossil provides this service out of the |
| 42 | box. |
| 43 | |
| 44 | * <b>One Result Per Matching Post:</b> When you search the forum |
| 45 | archives via the Fossil web interface, you get only one result for |
| 46 | each matching post. When you search for project information via a |
| 47 | standard web search engine, you might get a result from the project |
| 48 | site's own mail archive plus one from Nabble, one from Gmane, one |
| 49 | from The Mail Archive... |
| 50 | |
| 51 | * <b>Search Off-Line:</b> Because Fossil is a [./concepts.wiki | |
| 52 | distributed version control system], project members can search |
| 53 | your forum archive while disconnected from the network where the |
| 54 | central Fossil instance runs. Your past discussions are potentially |
| 55 | just as valuable as a wiki document or checkin comment: there is no |
| 56 | good reason why you should have to wait to get back on the Internet |
| 57 | or back to the office before you can search for past posts. |
| 58 | |
| 59 | * <b>Contribute Off-Line:</b> Fossil forum posts work like any other |
| 60 | insertion into the repository, so a user can create new threads and |
| 61 | reply to existing ones while off-line, then sync their |
| 62 | contributions to the server they cloned from when back on-line. |
| 63 | Yes, you can post to the forum from inside a tent, miles from the |
| 64 | nearest WiFi router or cellular data tower. |
| 65 | |
| 66 | * <b>Interlink with Other Fossil-Managed Artifacts:</b> Because forum |
| 67 | posts are normal Fossil artifacts, you can interlink them with |
| 68 | other Fossil artifacts using short internal links: link to forum |
| 69 | threads from a [./tickets.wiki | ticket], link to a wiki document |
| 70 | from a forum post, etc. |
| 71 | |
| 72 | * <b>Durable Links:</b> Once you create a valid internal artifact |
| 73 | link in Fossil, it <em>remains</em> valid, durably. With |
| 74 | third-party forum software and mailing list search engines, your |
| 75 | links are only valid until the third-party component changes its |
| 76 | URL scheme or disappears from the web. |
| 77 | |
| 78 | * <b>Role-Based Access Control:</b> The forum uses the same |
| 79 | [./caps/ | capability-based access control |
| 80 | system] that Fossil uses to control all other repository accesses. |
| 81 | The Fossil forum feature simply adds [./caps/ref.html#2 | several new fine-grained |
| 82 | capabilities] to the existing system. |
| 83 | |
| 84 | * <b>Enduring, Open File Format:</b> Since Fossil has an |
| 85 | [./fileformat.wiki | open and well-documented file format], your |
| 86 | discussion archives are truly that: <em>archives</em>. You are no |
| 87 | longer dependent on the lifetime and business model of a |
| 88 | third-party piece of software or service. Should you choose to stop |
| 89 | using Fossil, you can easily extract your discussion traffic for |
| 90 | transfer to another system. |
| 91 | |
| 92 | * <b>Lightweight Markup:</b> Posts can be marked up using Fossil's |
| 93 | existing [/md_rules | Markdown] and [/wiki_rules | Wiki] markup |
| 94 | processors. No longer must you choose between two bad options: to |
| 95 | restrict posts to plain text only or to allow wild-west |
| 96 | HTML-formatted MIME email. Fossil's lightweight markup language |
| 97 | formatting features give you a middle path, providing your users |
| 98 | enough formatting power to communicate complex ideas well without |
| 99 | providing so much power as to risk |
| 100 | [https://wonko.com/post/html-escaping | security problems]. |
| 101 | |
| 102 | * <b>Easy Email Alerts:</b> You can configure Fossil to |
| 103 | [./alerts.md | send email alerts]. Forum post emails include the |
| 104 | complete message content for the benefit of those that prefer to |
| 105 | visit the forum only when they need to post something. Alerts are |
| 106 | optional, and each user gets the choice of immediate or daily |
| 107 | digest delivery. |
| 108 | |
| 109 | |
| 110 | <h2 id="setup">Setting up a Fossil Forum</h2> |
| 111 | |
| 112 | <h3 id="caps">Capabilities</h3> |
| 113 | |
| 114 |
| --- www/forum.wiki | |
| +++ www/forum.wiki | |
| @@ -1,113 +1,67 @@ | |
| 1 | <title>Fossil Forums</title> |
| 2 | |
| 3 | <h2>Introduction</h2> |
| 4 | |
| 5 | Fossil includes a built-in discussion forum, designed to substitute |
| 6 | for a mailing list. Email notification is available to receive posts, |
| 7 | but the web-based UI must be used to enter new posts. Advantages of |
| 8 | the forum include: |
| 9 | |
| 10 | * <b>Easy to Administer:</b> If you have already set up a |
| 11 | [./server/|Fossil server] with [./alerts.md|email alerts] |
| 12 | then turning on the forum feature |
| 13 | is just a matter of flipping some permission bits. There is |
| 14 | no new software to install and configure, and the same logins |
| 15 | and passwords work. |
| 16 | |
| 17 | * <b>Malefactor Resistant:</b> Because Fossil accepts forum posts |
| 18 | only via the web UI, it is more resistent to spam. Passers-by |
| 19 | can post to the forum anonymously (subject to moderation), without |
| 20 | the hassle of a sign-up process. |
| 21 | |
| 22 | * <b>Distributed and Tamper-Proof:</b> Posts are stored in the Fossil |
| 23 | repository using the same [./fileformat.wiki | DAG/Merkle-tree design] |
| 24 | that Fossil uses to store your check-ins, wiki documents, etc. |
| 25 | Forum posts sync to cloned repositories. |
| 26 | |
| 27 | * <b>Editable:</b> Forum posts can be amended after they are sent, |
| 28 | to fix typos or provide updates. The original posts are preserved |
| 29 | as part of the historical record, but only the amended posts are |
| 30 | displayed by default. |
| 31 | |
| 32 | * <b>Built-in Full-Text Search:</b> Forum posts can be included in |
| 33 | the index used by the built-in Fossil search logic. |
| 34 | |
| 35 | * <b>Off-Line Access:</b> Because forum posts are synced along with |
| 36 | all other artifacts, you can search the forum, or add new posts |
| 37 | to the forum, while off-line. |
| 38 | |
| 39 | * <b>Automatically Cross-Referenced To Other Fossil Artifacts:</b> Because forum |
| 40 | posts are normal Fossil artifacts, you can link from them to |
| 41 | other Fossil artifacts (check-ins, wiki, tickets) and from those other |
| 42 | artifacts to forum posts. The reverse links are recognized and |
| 43 | displayed automatically on the receiver. |
| 44 | |
| 45 | * <b>Consistent Display:</b> Forum posts can be in Markdown, |
| 46 | Fossil Wiki, or plain text. Whichever format is used, the result is |
| 47 | displayed consistently across all platforms, including mobile. |
| 48 | |
| 49 | <h2>Example Installations</h2> |
| 50 | |
| 51 | Both the [forum:/forum|Fossil project itself] and the |
| 52 | [https://sqlite.org/forum/forum|SQLite project] use the Fossil forum in place |
| 53 | of mailing lists. The forum has worked well on both projects. The ability |
| 54 | to post anonymously provides a low-resistance path for people to report |
| 55 | problems, resulting in more problems being reported and fixed. |
| 56 | The ability to moderate and amend forum posts means that the |
| 57 | forums contain better information. And backups and archives |
| 58 | are as easy as running "clone". |
| 59 | |
| 60 | Both Fossil and SQLite keep their forums as separate repositories. |
| 61 | But there is no requirement to do this. A forum can be coresident in |
| 62 | the same repository with the source code. |
| 63 | |
| 64 | <h2 id="setup">Setting up a Fossil Forum</h2> |
| 65 | |
| 66 | <h3 id="caps">Capabilities</h3> |
| 67 | |
| 68 |