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