<title>Fossil Forums</title>
<h2>Introduction</h2>
As of Fossil 2.7, Fossil includes a built-in discussion forum feature.
Any project complex enough to be managed by Fossil can probably benefit
from having a discussion forum. Even if your project has a discussion
forum already, there are further benefits that stem from using Fossil's
built-in forum feature:
* Third-party discussion forum and mailing list software tends to be
difficult to install, set up, and administer. Fossil Forums aim to
be as close to zero-configuration as is practical.
* Posts are stored in the Fossil repository using the same
[./fileformat.wiki | block chain technology] that Fossil uses to
store your check-ins, wiki documents, etc. Posts sync to cloned
repositories in a tamper-proof fashion.
* Because of Fossil's [./delta_format.wiki | delta compression
technology], discussions add little to the size of a cloned
repository. Ten years of the SQLite project's discussions —
averaging 2 or 3 dozen posts per day — compress down to just
35 MB of space in a Fossil Forums repository.
* Fossil Forums use [https://sqlite.org/fts3.html | SQLite's powerful
FTS4 full-text search engine]. If your project currently uses a
mailing list for discussions, this means you are no longer reliant
upon third-party mailing list archive services to provide a useful
search engine for your discussions.
* Because Fossil is a [./concepts.wiki | distributed version control
system], project members can search your forum archive while
disconnected from the network where the central Fossil instance
runs. Your past discussions are potentially just as valuable as a
wiki document or checkin comment: there is no good reason why you
should have to wait to get back on the Internet or back to the
office before you can search for past posts.
* Because forum posts are normal Fossil artifacts, you can interlink
them with other Fossil artifacts using short internal links: link
to forum threads from a [./tickets.wiki | ticket], link to a wiki
document from a forum post, etc. These links are internal and
managed by Fossil itself, so links never become invalid simply
because your third-party forum software or mailing list search
engine changed its URL scheme.
* The forum uses the same role-based access control mechanism as
Fossil uses for all other accesses.
* Since Fossil has an [./fileformat.wiki | open and well-documented
file format], your discussion archives are truly that:
<em>archives</em>. You are no longer dependent on a third-party
piece of software or service sticking around. Should you choose to
stop using Fossil, you can easily extract your discussion traffic
for transfer to another system.
* Posts can be marked up using Fossil's existing [/md_rules |
Markdown] and [/wiki_rules | Wiki] markup languages. No longer must
you choose to restrict your discussion forums to plain text only
(good for security) or to allow HTML-formatted MIME email (good for
complex discussions). Fossil Forums provide <em>enough</em>
formatting without giving up security.
* Fossil forums integrate with third-party
[https://en.wikipedia.org/wiki/Message_transfer_agent | message transfer agents]
such as Postfix, Exim, and Sendmail. If you've got mail service
configured on the server hosting your Fossil instance, it can send
notifications of new posts to interested forum users, complete with
message content for those that prefer to visit the forum only when
they need to post something.
* Because Fossil accepts forum posts only via the web UI, it is
inherently [./antibot.wiki | protected against bots].
<h2>Setting up a Fossil Forum</h2>
<h3>Permissions</h3>
Fossil forums use the same role-based access control mechanism as
for normal Fossil repository logins.
There are several dedicated forum-related capability bits you can grant
a user:
* <b>Read</b>: The user may read forum posts
* <b>Write</b>: The user may create new forum threads and reply to
existing threads. New posts are held for moderation.
* <b>Write Trusted</b>: Same as <b>Write</b>, but posts are inserted
into the block chain immediately without being held for moderation.
* <b>Moderate</b>: User gets buttons on posts which allow them to
either delete or approve posts held for moderation. User also gets
access to a page (<tt>/modreq</tt>) showing the list of pending
moderation tasks.
* <b>Administer</b>: User can grant <b>Write Trusted</b> capability
to another user, or revoke it. (Currently unimplemented.)
By default, no Fossil user has permission to use the forums except for
users with Setup and Admin capabilities, which get these as part of the
large package of other capabilities they get.
For public Fossil repositories that wish to accept new users without
involving a human, go into Admin → Access and enable the "Allow
users to register themselves" setting. You may also wish to give the
<tt>anonymous</tt> user category the Read Forum (2) and Write Forum (3)
capabilities: this allows people to post without creating an account
simply by solving [./antibot.wiki | a simple CAPTCHA].
For a private repository, you probably won't want to give the
<tt>anonymous</tt> user any forum access, but you may wish to give
capability "2" to the <tt>reader</tt> user category.
For either type of repository, you are likely to want to give at least
the Write Trusted (4) capability to the <tt>developer</tt> user
category. If you did not give forum read capability (2) to
<tt>anonymous</tt> above, you should give <tt>developer</tt> that
capability here, if you choose to give it capability 3 or 4.
By following this advice, you should not need to tediously add
capabilities to individual accounts except in atypical cases, such as
to grant the Moderate Forum capability (5) to an uncommonly
highly-trusted user.
<h3>Skin Setup</h3>
If you create a new Fossil repository with version 2.7 or newer, its
default skin is already set up correctly for typical forum
configurations.
Those upgrading existing repositories will need to edit the Header part
of their existing Fossil skin in Admin → Skins, adding something
like this to create the navbar link:
<verbatim>
if {[anycap 23456] || [anoncap 2] || [anoncap 3]} {
menulink /forum Forum
}
</verbatim>
These rules say that any logged-in user with any forum-related
capability (2-6 inclusive, as of this writing) or an anonymous user with
read or write capability on the forum (2, 3) will see the "Forum" navbar
link, which just takes you to <tt>/forum</tt>.
The exact code you need here varies depending on which skin you're
using. Follow the style you see for the other navbar links.
<h3>Single Sign-On</h3>
If you choose to host your discussion forums within the same repository
as your project's other Fossil-managed content, you inherently have a
single sign-on system. Contrast third-party mailing list and forum
software where you either end up with two separate user tables and
permission sets, or you must go to significant effort to integrate the
two login systems.
You may instead choose to host your forums in a Fossil repository
separate from your project's main Fossil repository. A good reason to do
this is that you have a public project where very few of those
participating in the forum have special capability bits for project
assets managed by Fossil, so you wish to segregate the two user sets.
Yet, what of the users who will have logins on both repositories? Some
users will be trusted with access to the project's main Fossil
repository, and these users will probably also participate in the
project's Fossil-hosted forum.
Fossil has a feature to solve this problem that is probably less well
known than it should be, which has been in the software since April of
2011: Admin → Login-Group, which allows one Fossil repository to
recognize users authorized on another Fossil repository.
<h3>Email Notification</h3>
See [./emaildesign.md | the email notification design document] for now.
More administration-oriented documentation TODO.
<h2>Moderation</h2>
TODO
<h2>Troubleshooting</h2>
TODO