Fossil  Fossil Forums

Introduction

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:

  • Easy to Administer: 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.
  • Malefactor Resistant: Because Fossil accepts forum posts only via the web UI, it is inherently protected against bots.
  • Distributed and Tamper-Proof: Posts are stored in the Fossil repository using the same block chain technology that Fossil uses to store your check-ins, wiki documents, etc. Posts sync to cloned repositories in a tamper-proof fashion.
  • Space Efficient: Because of Fossil's 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 just 35 MB of space in a Fossil forum repository.
  • Built-in Full-Text Search: Fossil forums use 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 option of delegating this useful service to a third-party; Fossil provides this service out of the box.
  • One Result Per Matching Post: 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...
  • Search Off-Line: Because Fossil is a 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.
  • Contribute Off-Line: 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.
  • Interlink with Other Fossil-Managed Artifacts: 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 ticket, link to a wiki document from a forum post, etc.
  • Durable Links: Once you create a valid internal artifact link in Fossil, it remains 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.
  • Role-Based Access Control: The forum uses the same 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.
  • Enduring, Open File Format: Since Fossil has an open and well-documented file format, your discussion archives are truly that: archives. 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.
  • Lightweight Markup: Posts can be marked up using Fossil's existing Markdown and 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 security problems.
  • Easy Email Alerts: You can configure Fossil to send email alerts. Forum post emails include the complete message content for the benefit of those that prefer to visit the forum only when they need to post something. Alerts are optional, and each user gets the choice of immediate or daily digest delivery.

Setting up a Fossil Forum

Capabilities

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:

  • Read Forum (2): The user may read forum posts.
  • Write Forum (3): The user may create new forum threads, reply to existing threads, and edit their own posts. New posts are held for moderation, and they are marked to prevent them from being included in clone and sync operations.
  • Moderate Forum (5): User gets buttons on posts which allow them to either reject or approve posts held for moderation. User also gets access to a page (/modreq) showing the list of pending moderation tasks.
  • Supervise Forum (6): User can grant or revoke WriteTrusted capability for other users. (Currently unimplemented.)
  • Email Alerts (7): User can sign themselves up for email alerts, a.k.a. notifications.

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 the anonymous category the Read Forum (2) and Write Forum (3) capabilities: this allows people to post without creating an account simply by solving a simple CAPTCHA.

For a private repository, you probably won't want to give the anonymous user any forum access, but you may wish to give the Read Forum capability (2) to users in the reader category.

For either type of repository, you are likely to want to give at least the WriteTrusted capability (4) to users in the developer category. If you did not give the Read Forum capability (2) to anonymous above, you should give developer that capability here if you choose to give it capability 3 or 4.

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 Email Alerts capability (7) 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 nobody user category if you want anyone to sign up without any restrictions. Give it to anonymous instead if you want the user to solve a simple CAPTCHA before signing up. Or, give it to reader or developer 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 Moderate Forum capability (5) to an uncommonly highly-trusted user.

Skin Setup

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:

  1. 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.
  2. 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.

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:

  if {[anycap 23456] || [anoncap 2] || [anoncap 3]} {
    menulink /forum Forum
  }

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 /forum.

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:

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

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:

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

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:

  div.forumPosts a:visited {
    color: #6A7F94;
  }

This changes the clicked-hyperlink color for the forum post links on the main /forum 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 /forum 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 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.)

One of the underlying assumptions of the forum feature is that you will want to be able to search the forum archives, so the /forum 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.

Single Sign-On

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 → Login-Group. This allows one Fossil repository to recognize users authorized on a different Fossil repository.

Email Alerts (a.k.a. Notifications)

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 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.)

Accessing the Forum

There are many paths to a repository's Fossil forum:

  • If you're using the default Fossil skin as shipped with Fossil 2.7 or one updated to include the changes since 2.6 or prior, there is a Forum button in the navbar which appears for users with any of the forum-related user capabilities: 2 through 6 inclusive for those with repository logins, or caps 2 and 3 for users without a user account but who have solved the Anonymous user CAPTCHA.

    This button will not appear in the default skin for such users if their browser window is not greater than 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.

  • 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.
  • 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 edit their skin to include these links.
  • 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 user capabilities listed above.
  • That same link also appears on the repository's /sitemap page, since it provides the content for the hamburger menu's panel.

How Moderation Works

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 Write Forum capability (3) 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:

  1. Fossil saves the update artifact's ID in its private table, preventing Fossil from sending such artifacts to any of the repository's clones. (This is the same mechanism behind private branches.)
  2. Fossil also adds a reference to that artifact in the modreq 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.

When a moderator approves an update, Fossil deletes these table entries, making the update semi-permanent. This changes how Fossil renders the HTML for that update. It also means the artifact will now sync to clones, if the sync is done by a user with Check-Out capability (o).

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.

When a user with WriteTrusted Forum capability (4) updates the forum, it happens in the same way except that Fossil skips the private and modreq 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.

Using the Moderation Feature

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:

  1. Add the Moderate Forum capability (5) to any of your users who should have this ability. You don't need to do this for any user with Setup (s) or Admin (a) capability; it's already included.
  2. 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 Write Forum capability (3), any other user with the Moderate Forum capability (5) will see a conditional link appear at the top of the main forum page: "Moderation Requests". Clicking this takes the moderator to the /modreq 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.
  3. 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!