Fossil: Why Add Forum, Wiki, and Web Software To Your DVCS?

Fossil SCM

One notable feature of Fossil is that it bundles bug tracking, wiki, forum, chat, and technotes with distributed version control to give you an all-in-one software project management system.

A commenter on Hacker News takes exception to this idea, writing:

I don't want forum/web software built into my dvcs. I don't see how this improves over git.

This commenter may hold whatever opinions he wishes, of course. However, there are many good reasons why bundling other project management features with the DVCS might be useful for a given project:

  1. There is a single software package to install and manage for the project website. The alternative is to select, install, configure, learn about, manage, and maintain separate DVCS, wiki, ticketing, forum, chat, documentation, and whatever other software packages your project needs. Less time spent on project administration details means more time available to spend on the project itself.

  2. Fossil’s autosync feature gives you an implicit backup of the wiki, tickets, forum, and so forth simply by cloning the repository to another machine and using that clone regularly. Since the typical Fossil usage pattern is to stand the repo up on a central server and have the developers clone that repository down to their personal machines, if the server falls over, the last developer to do anything that resulted in an autosync has a functional and up-to-date backup.

    There are limitations to relying on Fossil’s autosync feature for backup purposes, but that document gives two methods for more complete backups, both of which are easily automated. The Fossil project itself is distributed across three data centers in this manner via cron.

  3. Remote workers get more than just the source code: they get the entire website including versioned documentation, wiki articles, tickets, forum posts, and so forth. This supports off-network development when traveling, when riding out Internet service failures, and when workers must sync with multiple remote servers, as when working alternately from home and in some central office.

    Feature-competitive Fossil alternatives typically solve this same problem with centralization, which generally means that only the DVCS piece still works in these situations where the developer is unable to contact the central server. Why accept the limitation of having a distributed clone of the code repo alone?

    Centralization doesn’t work for every project. If you enjoy the benefits of truly distributed (read: non-centralized) version control, you may also benefit from distributed forums, distributed ticket tracking, distributed wiki article publishing, and so forth.

  4. Integration of all of these features allows easy hyperlinks between check-in comments, wiki pages, forum posts, and tickets. More, because the software sees both sides of the link, referrer and referent, it can provide automatic back-references.

    A common situation in a Fossil project is that:

    • a forum post refers to a versioned project document that shows that the software isn’t behaving as documented;
    • a developer triages that forum report as a verified bug, filing a ticket to prioritize and track the resolution;
    • developers chat about the problem, referring to the ticket and thereby indirectly referring to the forum post, plus perhaps to other Fossil-managed resources such as a wiki document giving design principles that guide the proper fix; and finally
    • the commit message resolving the ticket includes a reference to the ticket it resolves.

    Since Fossil sees that the commit refers to a ticket, the ticket page automatically also refers back to the commit, closing the loop. A latecomer may arrive at the ticket via a web search, and from that see that it was closed following a commit. They can follow the link from the initial ticket message to the forum thread to catch up on the discussion leading to the fix and likely find a follow-up post from the initial reporting user saying whether the fix worked for them. If further work was needed, the latecomer can likely find it from that forum thread.

    This works even in a remote off-network clone: the developer can pull up the project web site via an http://localhost link and follow these links around the loop.

    Fossil allows breaking some of these project facilities out into separate repositories, as when the public forum is kept separate from the actual software development repository for administration reasons. By using Fossil’s interwiki link feature, you can get this same internal linking from ticket to commit to forum to wiki even across these administrative boundaries, even with remote off-network clones, simply by adjusting the interwiki map to match the remote clone’s network configuration.

  5. Bundling all of these services gives single sign-on (SSO) for all aspects of the project. The same username/password works for code, wiki, forum, tickets, and chat.

    If you choose to administratively separate some of these features by setting up multiple cooperating Fossil repositories, its login groups feature allows asymmetric SSO across these administrative boundaries so that, for example, users allowed to commit to the code repository also get a forum repository login, but self-registered forum users don’t automatically get the ability to commit to the code repo.

  6. Bundling all of these features reduces the number of external dependencies for the project.

    Take the first two points above: standing up a Fossil repo backup on a new server may be as simple as copying the backup to the new server and configuring its stock HTTP server to point at the backup repository via CGI.

    Consider: If you had good backups for all of the elements in a Git + Jira + Discord + MediaWiki + Sphinx lash-up, how long would it take you to stand up a replacement? That lash-up certainly has more features combined than Fossil alone, but are they worth the administration and hosting costs they impose? Fossil’s feature set suffices for the SQLite project it was created to serve, as well as for many others; is your project sufficiently more complex, such that it needs all of those extra features and their concomitant complexity?

    Considerations such as these push many into centralized hosting services such as GitHub, GitLab, Bitbucket, and so forth, but that just takes you back to point 3 above.

  7. Hosting all of these elements within a single service gives a consistent look-and-feel across all aspects of the project.

    Skinning independent software packages’ web interfaces to make them appear unified is more work than skinning everything once, as in Fossil, and even then, you can’t make independently-developed software look like it was produced by a single entity without resorting to heroic levels of customization. If you use a separate DVCS web front end, chat system, forum manager, documentation system, ticket tracker, and so on, you are likely to be relegated to simply matching colors and fonts; you might also get the ability to add a common logo to the header of all of these independent pieces. The pieces won’t look unified, because they weren’t developed that way.

    The Fossil project’s skinning system lets you affect all of its elements globally from the single skin editor.

    Or not: there’s a feature in Fossil that lets skin customizations apply to only some Fossil features. The initial impetus behind this feature was that one of our users wanted Markdown to be rendered with different indentation in forum posts than in embedded documentation owing to the inherent differences between the two presentation modalities.

    A user taking advantage of this per-feature CSS capability who wishes to change a UI element common to all Fossil features — say, to change the font for literal code blocks — may still make such a change globally. Opting into this per-feature CSS doesn’t fork all skinning efforts: UI elements not explicitly reskinned on a per-feature basis inherit the global skinning.

    But it goes futher. Fossil has a feature for project-specific extensions, which backs the SQLite Release Checklist, for instance. You wouldn’t know by looking at that page that it’s produced by software that isn’t actually part of Fossil: the extension only delivers the core of the page, and Fossil’s skining wraps it in a way that lets it inherit all of the project-level skinning customizations.

  8. Unifying all of these features within Fossil means we have a single Markdown interpreter common to all elements. If you lash multiple software systems together, even if they can all agree on Markdown as a common document markup language — hardly a given, as shown by the MediaWiki and Sphinx elements in point 6’s example above — they’re likely to render your text using different — possibly even incompatibly-different — Markdown dialects.

    This costs you in mental gear-switching when moving from the code repository to the documentation system to the forums to the ticket tracker.

    More than that, though, a developer might write a forum post that later gets promoted to a wiki article or to an embedded version-controlled project document. A developer on a Fossil-backed project may simply copy-paste the forum post text into the new document and save it, not needing to carefully check that it still renders properly under the second Markdown rendering engine. Similarly, if a user reports a potential bug via the forum, the developer can copy interesting pieces of the Markdown from the post into a ticket comment, again without needing to fiddle with dialect incompatibilities.

  9. Fossil is free, open-source software, through and through. Git-backed lash-ups tend to incorporate either proprietary add-ons or proprietary hosting systems that produce vendor lock-in. Fossil gives you the freedom to take your complete backup (point 2) of the project including its idiosyncratic customizations and stand it up elsewhere on commodity hardware and software stacks.

All of this having been said, the non-DVCS features of Fossil are optional. Its forum and chat features are disabled by default, and you can disable the ticket-tracking and wiki features with a quick configuration change to its role-based access control system. When you’re ready to turn these additional features on, you can do so with a few mouse clicks.

Because Fossil is web-native out of the box, if you’ve delegated these features to outside systems to flesh out Git’s DVCS-only nature, Fossil can link out to these systems, and they back into Fossil, letting you use Fossil in the same DVCS-only mode.