Fossil

Artifact [c4323510d7]
Login
Home Timeline Docs Branches Tickets Wiki DownloadMore...
Check-ins Using Download Text

Artifact c4323510d72b06c4cda7f5c12d6074e9028cae4d2d666638553f0faac0aafd72:

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:

Setting up a Fossil Forum

Permissions

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.

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.

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: 

  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.

Enable Forum Search

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 Notification

See the email notification design document for now. More administration-oriented documentation TODO.

Moderation

TODO

Troubleshooting

TODO

This page was generated in about 0.013s by Fossil 2.26 [1205ec86cb] 2025-04-30 16:57:32