Fossil SCM

fossil-scm / www / whyallinone.md
Source Blame History 235 lines
a204e32… drh 1 # Why Add Forum, Wiki, and Web Software To Your DVCS?
a204e32… drh 2
a204e32… drh 3 One notable feature of Fossil is that it bundles
a204e32… drh 4 [bug tracking](./bugtheory.wiki),
a204e32… drh 5 [wiki](./wikitheory.wiki),
a204e32… drh 6 [forum](./forum.wiki),
a204e32… drh 7 [chat](./chat.md), and
a204e32… drh 8 [technotes](./event.wiki)
a204e32… drh 9 with distributed version control to give you an
a204e32… drh 10 all-in-one software project management system.
a204e32… drh 11
a204e32… drh 12 A commenter on [Hacker News](https://news.ycombinator.com/item?id=27437895)
a204e32… drh 13 takes exception to this idea, writing:
a204e32… drh 14
a204e32… drh 15 > *I don't want forum/web software built into my dvcs.*
a204e32… drh 16 > *I don't see how this improves over git.*
a204e32… drh 17
eeb2852… wyoung 18 This commenter may hold whatever opinions he wishes, of course.
2b76ea2… wyoung 19 However, there are many good reasons why bundling other project management
36ea396… stephan 20 features with the DVCS might be useful for a given project:
a204e32… drh 21
1a74c2b… wyoung 22 1. There is a single software package to install and manage for the
a204e32… drh 23 project website.
a204e32… drh 24 The alternative is to select, install, configure, learn about,
6975de4… wyoung 25 manage, and maintain separate DVCS, wiki,
6975de4… wyoung 26 ticketing, forum,
6975de4… wyoung 27 chat, documentation, and whatever other software packages your project needs.
a204e32… drh 28 Less time spent on project administration details means more
a204e32… drh 29 time available to spend on the project itself.
a204e32… drh 30
2b76ea2… wyoung 31 2. Fossil’s autosync feature gives you an implicit backup of the
6975de4… wyoung 32 wiki, tickets, forum, and so forth simply by cloning the
6975de4… wyoung 33 repository to another machine and using that clone regularly.
6975de4… wyoung 34 Since the typical Fossil usage pattern is to stand the repo up on a
6975de4… wyoung 35 central server and have the developers clone that repository down
6975de4… wyoung 36 to their personal machines, if the server falls over, the last
6975de4… wyoung 37 developer to do anything that resulted in an autosync has a
6975de4… wyoung 38 functional and up-to-date backup.
6975de4… wyoung 39
1a74c2b… wyoung 40 There are [limitations to relying on Fossil’s autosync feature for
6975de4… wyoung 41 backup purposes](./backup.md), but that document gives two methods
6975de4… wyoung 42 for more complete backups, both of which are easily automated. The
6975de4… wyoung 43 Fossil project itself is distributed across three data centers in
6975de4… wyoung 44 this manner via cron.
6975de4… wyoung 45
6975de4… wyoung 46 3. Remote workers get more than just the source code:
6975de4… wyoung 47 they get the entire website including versioned documentation,
6975de4… wyoung 48 wiki articles, tickets, forum posts, and so forth. This supports
6975de4… wyoung 49 off-network development when traveling, when riding out Internet
6975de4… wyoung 50 service failures, and when workers must sync with multiple remote
6975de4… wyoung 51 servers, as when working alternately from home and in some central
6975de4… wyoung 52 office.
6975de4… wyoung 53
6975de4… wyoung 54 Feature-competitive Fossil alternatives typically solve this same
6975de4… wyoung 55 problem with centralization, which generally means that only the
6975de4… wyoung 56 DVCS piece still works in these situations where the developer is
6975de4… wyoung 57 unable to contact the central server. Why accept the limitation of
6975de4… wyoung 58 having a distributed clone of the code repo alone?
6975de4… wyoung 59
6975de4… wyoung 60 Centralization doesn’t work for every project. If you enjoy the
6975de4… wyoung 61 benefits of truly distributed (read: non-centralized) version
6975de4… wyoung 62 control, you may also benefit from distributed forums, distributed
6975de4… wyoung 63 ticket tracking, distributed wiki article publishing, and so
6975de4… wyoung 64 forth.
6975de4… wyoung 65
6975de4… wyoung 66 4. Integration of all of these features allows easy hyperlinks between
6975de4… wyoung 67 check-in comments, wiki pages, forum posts, and tickets. More,
6975de4… wyoung 68 because the software sees both sides of the link, referrer and
6975de4… wyoung 69 referent, it can provide automatic back-references.
6975de4… wyoung 70
6975de4… wyoung 71 A common situation in a Fossil project is that:
6975de4… wyoung 72
6975de4… wyoung 73 * a forum post refers to a versioned project document that shows
6975de4… wyoung 74 that the software isn’t behaving as documented;
6975de4… wyoung 75 * a developer triages that forum report as a verified bug, filing
6975de4… wyoung 76 a ticket to prioritize and track the resolution;
6975de4… wyoung 77 * developers chat about the problem, referring to the ticket and
6975de4… wyoung 78 thereby indirectly referring to the forum post, plus perhaps to
6975de4… wyoung 79 other Fossil-managed resources such as a wiki document giving
6975de4… wyoung 80 design principles that guide the proper fix; and finally
6975de4… wyoung 81 * the commit message resolving the ticket includes a reference to
6975de4… wyoung 82 the ticket it resolves.
6975de4… wyoung 83
6975de4… wyoung 84 Since Fossil sees that the commit refers to a ticket, the ticket
6975de4… wyoung 85 page automatically also refers back to the commit, closing the
6975de4… wyoung 86 loop. A latecomer may arrive at the ticket via a web search, and
6975de4… wyoung 87 from that see that it was closed following a commit. They can
6975de4… wyoung 88 follow the link from the initial ticket message to the forum
6975de4… wyoung 89 thread to catch up on the discussion leading to the fix and likely
6975de4… wyoung 90 find a follow-up post from the initial reporting user saying
6975de4… wyoung 91 whether the fix worked for them. If further work was needed, the
6975de4… wyoung 92 latecomer can likely find it from that forum thread.
6975de4… wyoung 93
6975de4… wyoung 94 This works even in a remote off-network clone: the developer can
6975de4… wyoung 95 pull up the project web site via an `http://localhost` link and
6975de4… wyoung 96 follow these links around the loop.
6975de4… wyoung 97
6975de4… wyoung 98 Fossil allows breaking some of these project facilities out into
6975de4… wyoung 99 separate repositories, as when the public forum is kept separate
6975de4… wyoung 100 from the actual software development repository for administration
6975de4… wyoung 101 reasons. By using Fossil’s [interwiki link
6975de4… wyoung 102 feature](./interwiki.md), you can get this same internal linking
6975de4… wyoung 103 from ticket to commit to forum to wiki even across these
6975de4… wyoung 104 administrative boundaries, even with remote off-network clones,
6975de4… wyoung 105 simply by adjusting the interwiki map to match the remote clone’s
6975de4… wyoung 106 network configuration.
6975de4… wyoung 107
ba9e50d… wyoung 108 5. Bundling all of these services gives [single sign-on][SSO] (SSO) for all
6975de4… wyoung 109 aspects of the project. The same username/password works for code,
6975de4… wyoung 110 wiki, forum, tickets, and chat.
6975de4… wyoung 111
6975de4… wyoung 112 If you choose to administratively separate some of these features
6975de4… wyoung 113 by setting up multiple cooperating Fossil repositories, its [login
6975de4… wyoung 114 groups feature](./caps/login-groups.md) allows asymmetric SSO
6975de4… wyoung 115 across these administrative boundaries so that, for example, users
6975de4… wyoung 116 allowed to commit to the code repository also get a forum
6975de4… wyoung 117 repository login, but self-registered forum users don’t
6975de4… wyoung 118 automatically get the ability to commit to the code repo.
6975de4… wyoung 119
ba9e50d… wyoung 120 6. Bundling all of these features reduces the number of external
6975de4… wyoung 121 dependencies for the project.
6975de4… wyoung 122
6975de4… wyoung 123 Take the first two points above: standing up a Fossil repo backup
6975de4… wyoung 124 on a new server may be as simple as copying the backup to the new
6975de4… wyoung 125 server and [configuring its stock HTTP server to point at the
6975de4… wyoung 126 backup repository via CGI](./server/any/cgi.md).
6975de4… wyoung 127
2b76ea2… wyoung 128 Consider: If you had good backups for all of the elements in a
6975de4… wyoung 129 Git + [Jira] + [Discord] + [MediaWiki] + [Sphinx] lash-up, how long
6975de4… wyoung 130 would it take you to stand up a replacement? That lash-up
2b76ea2… wyoung 131 certainly has more features combined than Fossil alone, but are
6975de4… wyoung 132 they worth the administration and hosting costs they impose?
2b76ea2… wyoung 133 Fossil’s feature set suffices for the SQLite project it was
2b76ea2… wyoung 134 created to serve, as well as for many others; is your project
2b76ea2… wyoung 135 sufficiently more complex, such that it *needs* all of those extra
2b76ea2… wyoung 136 features and their concomitant complexity?
6975de4… wyoung 137
6975de4… wyoung 138 Considerations such as these push many into centralized hosting
5e12c62… wyoung 139 services such as GitHub, GitLab, Bitbucket, and so forth, but that
6975de4… wyoung 140 just takes you back to point 3 above.
6975de4… wyoung 141
ba9e50d… wyoung 142 7. Hosting all of these elements within a single service gives a
8949674… wyoung 143 consistent look-and-feel across all aspects of the project.
8949674… wyoung 144
2b76ea2… wyoung 145 Skinning independent software packages’ web interfaces to make
7d50f61… wyoung 146 them appear unified is more work than [skinning] everything once, as
2b76ea2… wyoung 147 in Fossil, and even then, you can’t make independently-developed
2b76ea2… wyoung 148 software look like it was produced by a single entity without
2b76ea2… wyoung 149 resorting to heroic levels of customization. If you use a separate
2b76ea2… wyoung 150 DVCS web front end, chat system, forum manager, documentation
2b76ea2… wyoung 151 system, ticket tracker, and so on, you are likely to be relegated
2b76ea2… wyoung 152 to simply matching colors and fonts; you *might* also get the
2b76ea2… wyoung 153 ability to add a common logo to the header of all of these
2b76ea2… wyoung 154 independent pieces. The pieces won’t look unified, because they
2b76ea2… wyoung 155 weren’t developed that way.
2b76ea2… wyoung 156
216ef76… wyoung 157 The Fossil project’s
216ef76… wyoung 158 skinning system lets you affect all of its elements globally from the
216ef76… wyoung 159 single skin editor.
8949674… wyoung 160
8949674… wyoung 161 Or not: there’s a feature in Fossil that lets skin customizations
8949674… wyoung 162 apply to only *some* Fossil features. The initial impetus behind
8949674… wyoung 163 this feature was that one of our users wanted Markdown to be
8949674… wyoung 164 rendered with different indentation in forum posts than in
2b76ea2… wyoung 165 [embedded documentation][edoc] owing to the inherent differences between
2b76ea2… wyoung 166 the two presentation modalities.
2b76ea2… wyoung 167
2b76ea2… wyoung 168 A user taking advantage of this per-feature CSS capability who
2b76ea2… wyoung 169 wishes to change a UI element common to all Fossil features — say,
2b76ea2… wyoung 170 to change the font for literal code blocks — may still make such a
2b76ea2… wyoung 171 change globally. Opting into this per-feature CSS doesn’t fork all
2b76ea2… wyoung 172 skinning efforts: UI elements not explicitly reskinned on a
2b76ea2… wyoung 173 per-feature basis inherit the global skinning.
2b76ea2… wyoung 174
2b76ea2… wyoung 175 But it goes futher. Fossil has a feature for [project-specific
2b76ea2… wyoung 176 extensions](./serverext.wiki), which backs the [SQLite Release
2b76ea2… wyoung 177 Checklist][srckl], for instance. You wouldn’t know by looking at
2b76ea2… wyoung 178 that page that it’s produced by software that isn’t actually part
2b76ea2… wyoung 179 of Fossil: the extension only delivers the core of the page,
2b76ea2… wyoung 180 and Fossil’s skining wraps it in a way that lets it inherit all of
2b76ea2… wyoung 181 the project-level skinning customizations.
2b76ea2… wyoung 182
ba9e50d… wyoung 183 8. Unifying all of these features within Fossil
8949674… wyoung 184 means we have a single Markdown interpreter common to all
8949674… wyoung 185 elements. If you lash multiple software systems together, even if
8949674… wyoung 186 they can all agree on Markdown as a common document markup
8949674… wyoung 187 language — hardly a given, as shown by the MediaWiki and Sphinx
ba9e50d… wyoung 188 elements in point 6’s example above — they’re likely to render your text
8949674… wyoung 189 using different — possibly even incompatibly-different — Markdown
8949674… wyoung 190 dialects.
8949674… wyoung 191
2b76ea2… wyoung 192 This costs you in mental gear-switching when moving from the code
2b76ea2… wyoung 193 repository to the documentation system to the forums to the ticket
2b76ea2… wyoung 194 tracker.
2b76ea2… wyoung 195
2b76ea2… wyoung 196 More than that, though, a developer might write a forum post that later gets
8949674… wyoung 197 promoted to a wiki article or to an embedded version-controlled
2b76ea2… wyoung 198 project document. A developer on a Fossil-backed project may simply copy-paste the forum post
2b76ea2… wyoung 199 text into the new document and save it, not needing to carefully
8949674… wyoung 200 check that it still renders properly under the second Markdown
8949674… wyoung 201 rendering engine. Similarly, if a user reports a potential bug via
8949674… wyoung 202 the forum, the developer can copy interesting pieces of the
8949674… wyoung 203 Markdown from the post into a ticket comment, again without
8949674… wyoung 204 needing to fiddle with dialect incompatibilities.
6975de4… wyoung 205
ba9e50d… wyoung 206 9. Fossil is [free, open-source software](../COPYRIGHT-BSD2.txt),
6975de4… wyoung 207 through and through. Git-backed lash-ups tend to incorporate
6975de4… wyoung 208 either proprietary add-ons or proprietary hosting systems that
6975de4… wyoung 209 produce vendor lock-in. Fossil gives you the freedom to take your
6975de4… wyoung 210 complete backup (point 2) of the project including its
6975de4… wyoung 211 idiosyncratic customizations and stand it up elsewhere on
6975de4… wyoung 212 commodity hardware and software stacks.
6975de4… wyoung 213
ba9e50d… wyoung 214 All of this having been said, the non-DVCS features of Fossil are
ba9e50d… wyoung 215 optional. Its forum and chat features are disabled by default, and you
ba9e50d… wyoung 216 can disable the ticket-tracking and wiki features with a quick
ba9e50d… wyoung 217 configuration change to its [role-based access control system](./caps/).
ba9e50d… wyoung 218 When you’re ready to turn these additional features on, you can do so
ba9e50d… wyoung 219 with a few mouse clicks.
ba9e50d… wyoung 220
ba9e50d… wyoung 221 Because Fossil is web-native out of the box, if you’ve delegated these
7d50f61… wyoung 222 features to outside systems to flesh out Git’s DVCS-only nature, you are
7d50f61… wyoung 223 free to do the same with Fossil. One of the many things the [skinning]
7d50f61… wyoung 224 facility allows is replacing the built-in links to the wiki, forum,
7d50f61… wyoung 225 ticket system, etc. with links to external systems. How easy those
7d50f61… wyoung 226 systems make it to link back into Fossil is up to their developers.
ba9e50d… wyoung 227
6975de4… wyoung 228 [Discord]: https://discord.com/
2b76ea2… wyoung 229 [edoc]: ./embeddeddoc.wiki
6975de4… wyoung 230 [Jira]: https://www.atlassian.com/software/jira
6975de4… wyoung 231 [MediaWiki]: https://www.mediawiki.org/
7d50f61… wyoung 232 [skinning]: ./customskin.md
6975de4… wyoung 233 [Sphinx]: https://www.sphinx-doc.org/en/master/
6975de4… wyoung 234 [SSO]: https://en.wikipedia.org/wiki/Single_sign-on
6975de4… wyoung 235 [srckl]: https://www.sqlite.org/src/ext/checklist/top/index

Keyboard Shortcuts

Open search /
Next entry (timeline) j
Previous entry (timeline) k
Open focused entry Enter
Show this help ?
Toggle theme Top nav button