Fossil

Fossil Forums
Login
☰Home Timeline Docs Forum Download

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:

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:

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:

How Moderation Works

In this section, we're going to call all of the following a "forum update:"

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!
This page was generated in about 0.06s by Fossil 2.24 [8be0372c10] 2024-04-23 13:25:26