<title>Fossil Forums</title>
<h2>Introduction</h2>
Fossil includes a built-in discussion forum, designed to substitute
for a mailing list. Email notification is available to receive posts,
but the web-based UI must be used to enter new posts. Advantages of
the forum include:
* <b>Easy to Administer:</b> If you have already set up a
[./server/|Fossil server] with [./alerts.md|email alerts]
then turning on the forum feature
is just a matter of flipping some permission bits. There is
no new software to install and configure, and the same logins
and passwords work.
* <b>Consistent Display:</b> Forum posts can be in [/md_rules|Markdown],
[/wiki_rules|Fossil Wiki], or plain text. Whichever format is used, the result is
displayed consistently across all platforms and operating systems and
between mobile devices and desktops.
* <b>Editable:</b> Forum posts can be amended after they are sent,
to fix typos or provide updates. The original posts are preserved
as part of the historical record, but only the amended posts are
displayed by default.
* <b>Built-in Full-Text Search:</b> Forum posts can be included in
the index used by the built-in Fossil search logic.
* <b>Off-Line Access:</b> Because forum posts are synced along with
all other artifacts, you can search the forum, or add new posts, or
edit existing posts, all while off-line.
* <b>Automatically Cross-Referenced To Other Fossil Artifacts:</b> Because forum
posts are normal Fossil artifacts, you can link from them to
other Fossil artifacts (check-ins, wiki, tickets) and from those other
artifacts to forum posts. The reverse links are recognized and
displayed automatically on the receiver.
* <b>Malefactor Resistant:</b> Because Fossil accepts forum posts
only via the web UI, it is more resistent to spam. Passers-by
can post to the forum anonymously (subject to moderation), without
the hassle of a sign-up process.
* <b>Distributed and Tamper-Proof:</b> Posts are stored in the Fossil
repository using the same [./fileformat.wiki | DAG/Merkle-tree design]
that Fossil uses to store your check-ins, wiki documents, etc.
Forum posts sync to cloned repositories.
<h2>Example Installations</h2>
Both the [forum:/forum|Fossil project itself] and the
[https://sqlite.org/forum/forum|SQLite project] use the Fossil forum in place
of mailing lists. The forum has worked well on both projects. The ability
to post anonymously provides a low-resistance path for people to report
problems, resulting in more problems being reported and fixed.
The ability to moderate and amend forum posts means that the
forums contain better information. And backups and archives
are as easy as running "clone".
Both Fossil and SQLite keep their forums as separate repositories.
But there is no requirement to do this. A forum can be coresident in
the same repository with the source code.
<h2 id="setup">Setting up a Fossil Forum</h2>
<h3 id="caps">Capabilities</h3>
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 users
in [./caps/#ucat | the <tt>anonymous</tt> user category] the
<b>[./caps/ref.html#2 | RdForum]</b> and
<b>[./caps/ref.html#3 | WrForum]</b>
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
<b>RdForum</b> capability to users in the <tt>reader</tt> category.
For either type of repository, you are likely to want to give at least
the <b>[./caps/ref.html#4 | WrTForum]</b> capability to users in the <tt>developer</tt>
category. If you did not give the <b>RdForum</b> capability to
<tt>anonymous</tt> above, you should give <tt>developer</tt> that
capability here if you choose to give it <b>WrForum</b> or
<b>WrTForum</b> capability.
If you want to use the email alert feature, by default only those
users in the Setup and Admin user categories can make use of it. Grant
the <b>[./caps/ref.html#7 | EmailAlert]</b> capability to give others access to this feature.
Alternately, you can handle alert signups outside of Fossil, with
a Setup or Admin users manually signing users up via Admin →
Notification. You'll want to grant this capability to the
<tt>nobody</tt> user category if you want anyone to sign up without any
restrictions. Give it to <tt>anonymous</tt> instead if you want the
user to solve a simple CAPTCHA before signing up. Or, give it to
<tt>reader</tt> or <tt>developer</tt> if you want only users with Fossil
logins to have this ability. (That's assuming you give one or both of
these capabilities to every user on your Fossil repository.)
By following this advice, you should not need to tediously add
capabilities to individual accounts except in atypical cases, such as
to grant the <b>[./caps/ref.html#5 | ModForum]</b> capability to an uncommonly
highly-trusted user.
<h3 id="skin">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.
If you have an existing repository, you have two choices if you want its
skin to be upgraded to support forums:
<ol>
<li>Go into Admin → Skins and switch from your current skin to
one of the stock skins. If you were on a stock skin, just switch away
from your current one to the actual stock skin, since they will be
different after the upgrade.</li>
<li>If you have local customization that you do not want to throw
away, you can use the diff feature of Fossil's skin editor to show how
the skins differ.</li>
</ol>
The remainder of this section summarizes the differences you're expected
to see when taking option #2.
The first thing is that you'll need to add something like the following
to the Header part of the skin 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 [./caps/ref.html#2 |
forum-related capability] or an anonymous user <b>RdForum</b> or
<b>WrForum</b> capability 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.
Another new forum-related CSS style you might want to reflect into your
existing skin is:
<verbatim>
div.forumPosts a:visited {
color: #6A7F94;
}
</verbatim>
This changes the clicked-hyperlink color for the forum post links on the
main <tt>/forum</tt> page only, which allows your browser's history
mechanism to show which threads a user has read and which not. The link
color will change back to the normal link color — indicating "unread" —
when a reply is added to an existing thread because that changes where
the link from the <tt>/forum</tt> page points, taking you to the newest
post in the thread.
The color given above is suitable for the stock skin.
Beware that when changing this example, there are some
[https://hacks.mozilla.org/2010/03/privacy-related-changes-coming-to-css-vistited/
| stringent restrictions] in modern browsers to prevent snoopy web sites
from brute-forcing your browsing history. (See the link for the method,
which explains the restrictions.)
<h3 id="search">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 → 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 id="sso">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: [./caps/login-groups.md | login groups].
<h3 id="alerts">Email Alerts (a.k.a. Notifications)</h3>
Internet email service has become rather complicated since its initial
simple and insecure implementation decades ago. Fossil's role in all of
this is rather small at the moment, but the details of the integration
are complex enough to justify [./alerts.md | a separate document].
(The other reason that document is separate is that Fossil's email
alerts system also gets used by features of Fossil other than the
forum.)
<h2 id="access">Accessing the Forum</h2>
There are many paths to a repository's Fossil forum:
<ul>
<li>
If you're using the default Fossil skin as shipped with Fossil
2.7+ or one [#skin | updated] to support it, there
is a Forum button in the navbar which appears for users able to
access the forum. With the default skin, that button will only
appear if the user's browser window is at least
1200 pixels wide. The
Fossil admin can adjust this limit in the skin's CSS section, down
near the bottom in the definition of the `wideonly` style.
</li>
<li>The other stock skins have this button in them as of 2.7 as well,
without the screen width restriction, since the navbar in those skins
wraps on narrow screens more gracefully than the default skin
does.</li>
<li>Users who set up their Fossil repository under prior versions and
who now have local skin changes they don't want to overwrite by
reverting to the stock 2.7 version of the skin they chose to start
with can easily [#skin | edit their skin] to include these links.</li>
<li>A "Forum" link appears in the drop-down panel when you click the
default skin's hamburger menu (☰) while logged in as any user
with one or more of the [#caps | user capabilities listed above].</li>
<li>That same link also appears on the repository's <tt>/sitemap</tt>
page, since it provides the content for the hamburger menu's
panel.</li>
</ul>
The forum uses JavaScript to allow for a more comfortable editing
experience than is possible with static HTML. If one takes issue with,
or has issues with, the JavaScript-based forum editing and response
features, there are several ways around them: (1) Clients with JS
disabled should see the legacy (pre-mid-2026) input forms and
buttons. (2) Adding <code>?nojs</code> to any <code>/forumpost</code>
URL will disable plugging-in of the JS UI elements. (3) When forum
posts are visited via <code>/info</code> instead of
<code>/forumpost</code>, the JS-based UI elements do not plug
themselves in, leaving the legacy UI intact.
<h2 id="moderation">How Moderation Works</h2>
In this section, we're going to call all of the following a "forum
update:"
* create a new post
* reply to an existing post
* edit a post or reply
When a person with the normal <b>WrForum</b> capability
updates the forum, Fossil saves the update in its block chain, but this
update is impermanent because of two other table updates made at the
same time:
<ol>
<li>Fossil saves the update artifact's ID in its <tt>private</tt>
table, preventing Fossil from sending such artifacts to any of the
repository's clones. (This is the same mechanism behind
[./private.wiki | private branches].)</li>
<li>Fossil also adds a reference to that artifact in the
<tt>modreq</tt> table, which backs the moderation feature. This is
what causes Fossil to leave out the Reply button when rendering that
post's HTML in the forum's web interface.</li>
</ol>
When a moderator approves an update, Fossil deletes these table entries,
making the update [./shunning.wiki | semi-permanent]. This changes how Fossil renders the
HTML for that update. It also means the artifact will now sync to
users with <b>[./caps/ref.html#g | Clone]</b> capability.
When a forum user edits a moderator-approved artifact, what actually
happens under the hood is that Fossil writes another artifact to the
repository which refers to the original version as its parent, causing
Fossil UI to present the new version instead of the original. The
original version remains in the repository, just as with historical
checkins. The parent must remain in the repository for referential
integrity purposes.
When you "Delete" a moderator-approved post or reply through Fossil UI,
it's actually an edit with blank replacement content. The only way to
truly delete such artifacts is through [./shunning.wiki | shunning].
When a user with <b>WrTForum</b> capability
updates the forum, it happens in the same way except that Fossil skips
the <tt>private</tt> and <tt>modreq</tt> table insertions.
When a moderator rejects an update, that artifact is unceremoniously
removed from the tip of the block chain. This is safe because Fossil
prevents replies to a reply or post awaiting moderator approval, so
referential integrity cannot be harmed. Rejecting an edit is even
safer, since the original post remains behind, so that replies continue
to refer to that original post.
<h2 id="mod-user">Using the Moderation Feature</h2>
Having described all of the work that Fossil performs under the hood on
behalf of its users, we can now give the short list of work left for the
repository's administrators and moderators:
<ol>
<li>Add the <b>[./caps/ref.html#5 | ModForum]</b> capability to any of
your users who should have this ability. You don't need to do this
for any user with <b>[./caps/ref.html#s | Setup]</b> or
<b>[./caps/ref.html#a | Admin]</b> capability; it's
[/artifact/b16221ffb736caa2?ln=1246-1257 | already included].</li>
<li>When someone updates the forum, an entry will appear in the
timeline if the type filter is set to "Forum" or "Any Type". If that
user has only the <b>WrForum</b> capability, any
other user with the <b>ModForum</b> capability
will see a conditional link appear at the top of the main forum
page: "Moderation Requests". Clicking this takes the moderator to
the <tt>/modreq</tt> page. A moderator may wish to keep the main
forum page open in a browser tab, reloading it occasionally to see
when the "Moderation Requests" link reappears.</li>
<li>A moderator viewing an update pending moderation sees two
buttons at the bottom, "Approve" and "Reject" in place of the
"Delete" button that the post's creator sees. Beware that both
actions are durable and have no undo. Be careful!</li>
</ol>
<h2 id="close-post">Closing Forum Posts</h2>
As of version 2.23 the forum interface supports the notion of
"closing" posts. By default, only users with the [./caps/index.md|'s'
and 'a' capabilities] may close or re-open posts, or reply to closed
posts. If the [/help/forum-close-policy|forum-close-policy
configuration option] is enabled then users with
[./caps/index.md|forum-moderator permissions] may also perform those
actions.
Closing a post has the following implications:
* Only authorized users may edit or respond to such posts, recursively
through all responses of that post.
* Only authorized users may re-open a closed post.
A forum thread may be closed at any given point in the conversation,
not just the starting point of the thread, and affects that specific
post and all existing responses to it.
Note that closing a post is effectively an "advisory lock" and may be
bypassed. Any user, admin or otherwise, who can push changes to a
repository may bypass closure of a post by setting the appropriate
artifact tags on a local copy and pushing those changes to a remote
copy of the forum.
The option to close a post, permissions permitting, appears as a
"Close" button on the currently-selected post. If the selected post is
alread closed, a "Re-open" button will be shown instead. In order to
re-open a post, <em>the closed post itself</em> must be
selected. Selecting a response to that post, which is implicitly
closed by the closure of its parent, will <em>not</em> offer a re-open
option.
Though forum users are permitted to delete their own posts, they are
not permitted, without appropriate permissions, to close their own
posts. This is intentional, as closing one's own post can be used to
antagonize other forum users. For example, by posting something
trollish or highly controversial in nature and closing the post to
further responses.
<h2 id="status">Setting Post Statuses</h2>
As of version 2.29 forum posts may be tagged with a status. The
setting <tt>forum-statuses</tt> controls whether this feature is is
enabled. If it is not set, is not valid JSON5, or has only a single
entry, then status are not shown in the forum.
<tt>forum-statuses</tt> is a JSON5-format array of objects in the
following format:
<verbatim>
[
{label:"Open", value:"open"},
{label:"Resolved", value:"resolved"}
...
]</verbatim>
The list defines the legal statuses for forum posts and syncs with
other project-level settings. All "label" and "value" members must be
unique within the scope of that list.
The "value" values must be legal for use as HTML "dataset" members so
that they can be used for with CSS selectors to apply per-status
styling.
If the list is valid JSON5 and has two or more entries then the forum
behavior changes in the following ways:
* Each TR element of the main <tt>/forum</tt> view table gets a
<tt>data-status="X"</tt> member, where "X" is the value part from
the associated status. This can be used to style the statuses
in the site skin using CSS selectors such as<br>
<tt>body.cpage-forum div.forumPosts tr[data-status="open"]</tt><br>
Because there is no default status list, no predefined styles
are applied.
* The forum list shows the "label" value of the current status and
a selection list of available filters. It elides the status column
when filtering on a specific status.
* The root of each thread, when selected, gets a new UI control for
displaying or editing the status, depending on permissions.
* A drop-down selection list is added to the <tt>/forum</tt> page
for filtering based on the status.
A list with only a single entry is treated as empty, the justification
being that if there is only one option then the UI does not need to be
cluttered with it.
This setting is applied via a <tt>status</tt> tag on the first version
of a legal post. That tag may be set to any value from the "values"
members of the <tt>forum-statuses</tt> list.
Status tag rules:
* <tt>status</tt> is only observed on the root of each thread. The UI
does nothing with that tag on responses.
* The first list entry is considered to be the default status. Any post
which has no <tt>status</tt> tag, or has a <tt>status</tt> tag value
which is not in that list, is assumed for most purposes to have the
value of the first entry in the list.
* The tag is applied only to the first version of any given post. The
UI ensures that the tag is applied to the proper post, even when
rendering a newer version.
Caveat: a "closed" status is not recommended because it's easy to confuse with
the <a href='#close-post'>"closed" tag feature</a>, which behaves considerably
differently and predates that "status" tag support by about three years. The
"closed" semantics cannot be trivially consolidated with those of "status"
but we reserve the right to do so at some point.
<h2 id="attachments">Attachments</h2>
As of version 2.29 users with the [./caps/index.md|'B' capability] may
attach files to forum posts. Files may not be attached until a forum
post is saved for the first time, after which an "Attach" button will
appear in the post when it is selected. Attached files undergo
moderation exactly like forum posts do. When a moderator accepts a
pending-moderation posts, all files attached to it which are also
pending approval are also approved. Similarly, when a moderator
rejects a pending-moderation post, all files attached to it which are
also pending approval are rejected.
Developer notes regarding the save-before-attach limitation:
* We cannot add the attachment form to the current post editor
because (A) the Preview option would upload the files each time
(B) we cannot pre-populate file selection elements so could not
restore them when rendering the preview's response.
* To work around that we need to reimplement the forum editor
using AJAX-friendly APIs. That would allow us to render a preview
without reloading the page, to attach multiple files at once,
to support pasting a screenshot as an attachment, and to submit both
a new post and its attachments at the same time.
* We have AJAX-capable preview code in /wiki and /fileedit.
* We have paste-screenshot code in /chat but integrating it here will
require adding a "paste" button to the attachment UI.
Developer notes regarding automatic acceptance/rejection of
attachments:
* There is a race condition here where an admin may approve
attachments they have not yet seen: user creates posts, admin gets
notified, admin reads post, user attaches a file at that time,
admin approves post.
TBD is whether to accept that case or to remove automatic approval of
attached files.
<h2 id="drafts">Draft Edits</h2>
The forum uses, if available, JavaScript's <code>localStorage</code>
or <code>sessionStorage</code> to store local drafts of new
posts, replies, and edits to existing posts. Each time an editor
input field loses focus, the draft is saved. When viewing a forum
thread, the Edit and Reply buttons get clearly marked if they
have an associated local draft.
Local drafts for replies and responses (but not new posts) are
automatically purged at semi-random intervals. Every Nth visit to a
forum page has a small chance to run the cleanup, and drafts older
than 10 days old are purged.
If neither <code>localStorage</code> nor <code>sessionStorage</code>
are available, it uses a transient storage object which is recreated
on each page-load, so it cannot store drafts outside of a single
thread at a time.
Beware: Each draft is keyed to the post it is editing or replied to,
which means that editing or replying to the same post from different
tabs will cause collisions. The editor to most recently lose the focus
will save the draft, overwriting the other.
In browsers which support Web Locks, attempts to edit resp. reply to a
post which is already being edited resp. replied to in another tab
will show an error for the second and subsequent tabs. The first tab
to use the edit/reply buttons will hold a separate Web Lock for each
and forbid edit/reply access to the post in other tabs until the
locking tab is closed.
<h2 id="padding">Curious Extra Page Padding</h2>
Users may notice that the forum pages get a bunch of padding added to
the bottom of the page when an editor widget is opened. This is not a
bug, but a workaround to help avoid the UI jumping around when
rendering a preview wildly resizes the widget. The effect is
especially helpful when working on posts while the bottom footer of
the page is in the viewport, as the footer is a hard boundary against
scrolling. With the extra padding, the editor widget's top edge shifts
around less when the preview is shown and hidden.
<h2 id="fork">Forked Edits</h2>
It is possible to "fork" forum messages, in the same way that any
given check-in may cause a fork. This can happen when a message is
edited concurrently from two or more browser tabs or via two or more
fossil instances which subsequently sync with each other.
When a forum post is forked, the UI currently behaves as it does for
concurrent wiki page edits, showing only the most recent
edit. Currently (2026-06) the UI is incapable of showing the older
forked copies but (A) the data are still part of the SCM history and
(B) there are plans to improve the UI to show such forks.
For trivia's sake, here's a query which finds posts which have
forks:
<pre><verbatim>
SELECT bp.rid AS parentRid, bp.uuid parentUuid, count(f.fprev) forkCount
FROM blob b, blob bp, forumpost f
WHERE b.rid=f.fpid
AND f.fprev=bp.rid
GROUP BY f.fprev
HAVING forkCount>1;
</verbatim></pre>
And here's one which lists forked posts:
<pre><verbatim>
WITH multiparent(mpid) AS (
SELECT fprev FROM forumpost f
GROUP BY fprev
HAVING count(fprev)>1
)
SELECT datetime(fmtime), forumpost.*
FROM forumpost, multiparent
WHERE fprev=mpid
ORDER BY mpid, fpid, fmtime;
</verbatim></pre>
The telling part is the <code>fprev</code> column: those with matching
values forked from the post referred to by <code>fprev</code>.