<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 benefit from being managed by Fossil and
which has more than one user can probably also benefit from having a
discussion forum. Even if your project has a discussion forum already,
there are many benefits to using Fossil's built-in forum feature, some
of which you cannot get by using third-party alternatives:

  *  <b>Easy to Administer:</b> Third-party discussion forum and mailing
     list software tends to be difficult to install, set up, and
     administer. The Fossil forum feature aims to be as close to
     zero-configuration as is practical.

  *  <b>Malefactor Resistant:</b> Because Fossil accepts forum posts
     only via the web UI, it is inherently [./antibot.wiki | protected
     against bots].

  *  <b>Distributed and Tamper-Proof:</b> 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.

  *  <b>Space Efficient:</b> 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 about 2 dozen posts per day — compress down
     to [/forumpost/9b6f3f36bdb | just 35&nbsp;MB of space] in a Fossil
     forum repository.

  *  <b>Built-in Full-Text Search:</b> Fossil forums use
     [https://sqlite.org/fts3.html | SQLite's powerful FTS4 engine] to
     handle searches. 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. If you are running a private Fossil repository,
     you may not even have the <em>option</em> of delegating this useful
     service to a third-party; Fossil provides this service out of the
     box.

  *  <b>One Result Per Matching Post:</b> When you search the forum
     archives via the Fossil web interface, you get only one result for
     each matching post. When you search for project information via a
     standard web search engine, you might get a result from the project
     site's own mail archive plus one from Nabble, one from Gmane, one
     from The Mail Archive...

  *  <b>Search Off-Line:</b> 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.

  *  <b>Contribute Off-Line:</b> Fossil forum posts work like any other
     insertion into the repository, so a user can create new threads and
     reply to existing ones while off-line, then sync their
     contributions to the server they cloned from when back on-line.
     Yes, you can post to the forum from inside a tent, miles from the
     nearest wifi router or cellular data tower.

  *  <b>Interlink with Other Fossil-Managed Artifacts:</b> 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.
     
  *  <b>Durable Links:</b> Once you create a valid internal artifact
     link in Fossil, it <em>remains</em> valid, durably. With
     third-party forum software and mailing list search engines, your
     links are only valid until the third-party component changes its
     URL scheme or disappears from the web.

  *  <b>Role-Based Access Control:</b> The forum uses the same
     [https://en.wikipedia.org/wiki/Role-based_access_control | RBAC
     system] that Fossil uses to control all other repository accesses.
     The Fossil forum feature simply adds several new fine-grained
     capability bits to the existing system.

  *  <b>Enduring, Open File Format:</b> 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 the lifetime and business model of a
     third-party piece of software or service. Should you choose to stop
     using Fossil, you can easily extract your discussion traffic for
     transfer to another system.

  *  <b>Lightweight Markup:</b> Posts can be marked up using Fossil's
     existing [/md_rules | Markdown] and [/wiki_rules | Wiki] markup
     processors. No longer must you choose between two bad options: to
     restrict posts to plain text only or to allow wild-west
     HTML-formatted MIME email. Fossil's lightweight markup language
     formatting features give you a middle path, providing your users
     enough formatting power to communicate complex ideas well without
     providing so much power as to risk
     [https://wonko.com/post/html-escaping | security problems].

  *  <b>Easy Notification Emails:</b> It is easy to configure Fossil to
     send email notifications of new posts to interested forum users via
     your Fossil server's existing
     [https://en.wikipedia.org/wiki/Message_transfer_agent | message
     transfer agent] (MTA): Postfix, Exim, Sendmail... Notification
     emails include the complete message content for the benefit of
     those that prefer to visit the forum only when they need to post
     something. Notifications are optional, and each user gets the
     choice of immediate or daily digest delivery.

  *  <b>Talks to Everyone:</b> Because Fossil delegates email handling
     to your existing MTA, it does not need to implement the
     [http://sqlite.1065341.n5.nabble.com/Many-ML-emails-going-to-GMail-s-SPAM-tp98685p98722.html
     | roughly two dozen]
     [https://en.wikipedia.org/wiki/Request_for_Comments | RFCs]
     required in order to properly support SMTP email in this complex
     world we've built.  As well, this design choice means you do not
     need to do duplicate configuration, such as to point Fossil at your
     server's TLS certificate private key in order to support users
     behind mail servers that require STARTTLS encryption.


<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 Forum</b>: The user may read forum posts

  *  <b>Write Forum</b>: The user may create new forum threads and reply
     to existing threads. New posts are held for moderation.

  *  <b>WriteTrusted Forum</b>: Same as <b>Write Forum</b> except that
     posts are inserted into the block chain immediately without being held
     for moderation.

  *  <b>Moderate Forum</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>Supervise Forum</b>: User can grant or revoke
     <b>WriteTrusted</b> capability for other users. (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 &rarr; Access and enable the "Allow
users to register themselves" setting. You may also wish to give users
in the <tt>anonymous</tt> 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 the
Read Forum capability (2) to users in the <tt>reader</tt> category.

For either type of repository, you are likely to want to give at least
the WriteTrusted capability (4) to users in the <tt>developer</tt>
category. If you did not give the Read Forum 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 &rarr; 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.

The new forum feature also brings many new CSS styles to the table. If
you're using the stock skin or something sufficiently close, the changes
may work with your existing skin as-is. Otherwise, you might need to
adjust some things, such as the background color used for the selected
forum post:

<verbatim>
  div.forumSel {
    background-color: rgba(0, 0, 0, 0.05);
  }
</verbatim>

That overrides the default — a hard-coded light cyan — with a 95%
transparent black overlay instead, which simply darkens your skin's
normal background color underneath the selected post. That should work
with almost any background color except for very dark background colors.
For dark skins, an inverse of the above trick will work better:

<verbatim>
  div.forumSel {
    background-color: rgba(255, 255, 255, 0.05);
  }
</verbatim>

That overlays the background with 5% white to lighten it slightly.


<h3>Enable Forum Search</h3>

One of the underlying assumptions of the forum feature is that you will
want to be able to search the forum archives, so the <tt>/forum</tt>
page always includes a search box. Since that depends on search being
enabled on the Fossil repository, Fossil warns that search is disabled
until you go into Admin &rarr; Search and enable the "Search Forum"
setting.

You may want to enable some of the other Fossil search features while
you're in there. All of this does come at some CPU and I/O cost, which
is why it's disabled by default.


<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 which is probably less well known than it should be, and which
has been a feature of Fossil since April of 2011: Admin &rarr;
Login-Group. This allows one Fossil repository to recognize users
authorized on a different 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
