|
1
|
<title>Fossil Forums</title> |
|
2
|
|
|
3
|
<h2>Introduction</h2> |
|
4
|
|
|
5
|
Fossil includes a built-in discussion forum, designed to substitute |
|
6
|
for a mailing list. Email notification is available to receive posts, |
|
7
|
but the web-based UI must be used to enter new posts. Advantages of |
|
8
|
the forum include: |
|
9
|
|
|
10
|
* <b>Easy to Administer:</b> If you have already set up a |
|
11
|
[./server/|Fossil server] with [./alerts.md|email alerts] |
|
12
|
then turning on the forum feature |
|
13
|
is just a matter of flipping some permission bits. There is |
|
14
|
no new software to install and configure, and the same logins |
|
15
|
and passwords work. |
|
16
|
|
|
17
|
* <b>Consistent Display:</b> Forum posts can be in [/md_rules|Markdown], |
|
18
|
[/wiki_rules|Fossil Wiki], or plain text. Whichever format is used, the result is |
|
19
|
displayed consistently across all platforms and operating systems and |
|
20
|
between mobile devices and desktops. |
|
21
|
|
|
22
|
* <b>Editable:</b> Forum posts can be amended after they are sent, |
|
23
|
to fix typos or provide updates. The original posts are preserved |
|
24
|
as part of the historical record, but only the amended posts are |
|
25
|
displayed by default. |
|
26
|
|
|
27
|
* <b>Built-in Full-Text Search:</b> Forum posts can be included in |
|
28
|
the index used by the built-in Fossil search logic. |
|
29
|
|
|
30
|
* <b>Off-Line Access:</b> Because forum posts are synced along with |
|
31
|
all other artifacts, you can search the forum, or add new posts, or |
|
32
|
edit existing posts, all while off-line. |
|
33
|
|
|
34
|
* <b>Automatically Cross-Referenced To Other Fossil Artifacts:</b> Because forum |
|
35
|
posts are normal Fossil artifacts, you can link from them to |
|
36
|
other Fossil artifacts (check-ins, wiki, tickets) and from those other |
|
37
|
artifacts to forum posts. The reverse links are recognized and |
|
38
|
displayed automatically on the receiver. |
|
39
|
|
|
40
|
* <b>Malefactor Resistant:</b> Because Fossil accepts forum posts |
|
41
|
only via the web UI, it is more resistent to spam. Passers-by |
|
42
|
can post to the forum anonymously (subject to moderation), without |
|
43
|
the hassle of a sign-up process. |
|
44
|
|
|
45
|
* <b>Distributed and Tamper-Proof:</b> Posts are stored in the Fossil |
|
46
|
repository using the same [./fileformat.wiki | DAG/Merkle-tree design] |
|
47
|
that Fossil uses to store your check-ins, wiki documents, etc. |
|
48
|
Forum posts sync to cloned repositories. |
|
49
|
|
|
50
|
<h2>Example Installations</h2> |
|
51
|
|
|
52
|
Both the [forum:/forum|Fossil project itself] and the |
|
53
|
[https://sqlite.org/forum/forum|SQLite project] use the Fossil forum in place |
|
54
|
of mailing lists. The forum has worked well on both projects. The ability |
|
55
|
to post anonymously provides a low-resistance path for people to report |
|
56
|
problems, resulting in more problems being reported and fixed. |
|
57
|
The ability to moderate and amend forum posts means that the |
|
58
|
forums contain better information. And backups and archives |
|
59
|
are as easy as running "clone". |
|
60
|
|
|
61
|
Both Fossil and SQLite keep their forums as separate repositories. |
|
62
|
But there is no requirement to do this. A forum can be coresident in |
|
63
|
the same repository with the source code. |
|
64
|
|
|
65
|
<h2 id="setup">Setting up a Fossil Forum</h2> |
|
66
|
|
|
67
|
<h3 id="caps">Capabilities</h3> |
|
68
|
|
|
69
|
By default, no Fossil user has permission to use the forums except for |
|
70
|
users with Setup and Admin capabilities, which get these as part of the |
|
71
|
large package of other capabilities they get. |
|
72
|
|
|
73
|
For public Fossil repositories that wish to accept new users without |
|
74
|
involving a human, go into Admin → Access and enable the "Allow |
|
75
|
users to register themselves" setting. You may also wish to give users |
|
76
|
in [./caps/#ucat | the <tt>anonymous</tt> user category] the |
|
77
|
<b>[./caps/ref.html#2 | RdForum]</b> and |
|
78
|
<b>[./caps/ref.html#3 | WrForum]</b> |
|
79
|
capabilities: this allows people to post without creating an account |
|
80
|
simply by solving [./antibot.wiki | a simple CAPTCHA]. |
|
81
|
|
|
82
|
For a private repository, you probably won't want to give the |
|
83
|
<tt>anonymous</tt> user any forum access, but you may wish to give the |
|
84
|
<b>RdForum</b> capability to users in the <tt>reader</tt> category. |
|
85
|
|
|
86
|
For either type of repository, you are likely to want to give at least |
|
87
|
the <b>[./caps/ref.html#4 | WrTForum]</b> capability to users in the <tt>developer</tt> |
|
88
|
category. If you did not give the <b>RdForum</b> capability to |
|
89
|
<tt>anonymous</tt> above, you should give <tt>developer</tt> that |
|
90
|
capability here if you choose to give it <b>WrForum</b> or |
|
91
|
<b>WrTForum</b> capability. |
|
92
|
|
|
93
|
If you want to use the email alert feature, by default only those |
|
94
|
users in the Setup and Admin user categories can make use of it. Grant |
|
95
|
the <b>[./caps/ref.html#7 | EmailAlert]</b> capability to give others access to this feature. |
|
96
|
Alternately, you can handle alert signups outside of Fossil, with |
|
97
|
a Setup or Admin users manually signing users up via Admin → |
|
98
|
Notification. You'll want to grant this capability to the |
|
99
|
<tt>nobody</tt> user category if you want anyone to sign up without any |
|
100
|
restrictions. Give it to <tt>anonymous</tt> instead if you want the |
|
101
|
user to solve a simple CAPTCHA before signing up. Or, give it to |
|
102
|
<tt>reader</tt> or <tt>developer</tt> if you want only users with Fossil |
|
103
|
logins to have this ability. (That's assuming you give one or both of |
|
104
|
these capabilities to every user on your Fossil repository.) |
|
105
|
|
|
106
|
By following this advice, you should not need to tediously add |
|
107
|
capabilities to individual accounts except in atypical cases, such as |
|
108
|
to grant the <b>[./caps/ref.html#5 | ModForum]</b> capability to an uncommonly |
|
109
|
highly-trusted user. |
|
110
|
|
|
111
|
|
|
112
|
<h3 id="skin">Skin Setup</h3> |
|
113
|
|
|
114
|
If you create a new Fossil repository with version 2.7 or newer, its |
|
115
|
default skin is already set up correctly for typical forum |
|
116
|
configurations. |
|
117
|
|
|
118
|
If you have an existing repository, you have two choices if you want its |
|
119
|
skin to be upgraded to support forums: |
|
120
|
|
|
121
|
<ol> |
|
122
|
<li>Go into Admin → Skins and switch from your current skin to |
|
123
|
one of the stock skins. If you were on a stock skin, just switch away |
|
124
|
from your current one to the actual stock skin, since they will be |
|
125
|
different after the upgrade.</li> |
|
126
|
|
|
127
|
<li>If you have local customization that you do not want to throw |
|
128
|
away, you can use the diff feature of Fossil's skin editor to show how |
|
129
|
the skins differ.</li> |
|
130
|
</ol> |
|
131
|
|
|
132
|
The remainder of this section summarizes the differences you're expected |
|
133
|
to see when taking option #2. |
|
134
|
|
|
135
|
The first thing is that you'll need to add something like the following |
|
136
|
to the Header part of the skin to create the navbar link: |
|
137
|
|
|
138
|
<verbatim> |
|
139
|
if {[anycap 23456] || [anoncap 2] || [anoncap 3]} { |
|
140
|
menulink /forum Forum |
|
141
|
} |
|
142
|
</verbatim> |
|
143
|
|
|
144
|
These rules say that any logged-in user with any [./caps/ref.html#2 | |
|
145
|
forum-related capability] or an anonymous user <b>RdForum</b> or |
|
146
|
<b>WrForum</b> capability will see the "Forum" navbar |
|
147
|
link, which just takes you to <tt>/forum</tt>. |
|
148
|
|
|
149
|
The exact code you need here varies depending on which skin you're |
|
150
|
using. Follow the style you see for the other navbar links. |
|
151
|
|
|
152
|
The new forum feature also brings many new CSS styles to the table. If |
|
153
|
you're using the stock skin or something sufficiently close, the changes |
|
154
|
may work with your existing skin as-is. Otherwise, you might need to |
|
155
|
adjust some things, such as the background color used for the selected |
|
156
|
forum post: |
|
157
|
|
|
158
|
<verbatim> |
|
159
|
div.forumSel { |
|
160
|
background-color: rgba(0, 0, 0, 0.05); |
|
161
|
} |
|
162
|
</verbatim> |
|
163
|
|
|
164
|
That overrides the default — a hard-coded light cyan — with a 95% |
|
165
|
transparent black overlay instead, which simply darkens your skin's |
|
166
|
normal background color underneath the selected post. That should work |
|
167
|
with almost any background color except for very dark background colors. |
|
168
|
For dark skins, an inverse of the above trick will work better: |
|
169
|
|
|
170
|
<verbatim> |
|
171
|
div.forumSel { |
|
172
|
background-color: rgba(255, 255, 255, 0.05); |
|
173
|
} |
|
174
|
</verbatim> |
|
175
|
|
|
176
|
That overlays the background with 5% white to lighten it slightly. |
|
177
|
|
|
178
|
Another new forum-related CSS style you might want to reflect into your |
|
179
|
existing skin is: |
|
180
|
|
|
181
|
<verbatim> |
|
182
|
div.forumPosts a:visited { |
|
183
|
color: #6A7F94; |
|
184
|
} |
|
185
|
</verbatim> |
|
186
|
|
|
187
|
This changes the clicked-hyperlink color for the forum post links on the |
|
188
|
main <tt>/forum</tt> page only, which allows your browser's history |
|
189
|
mechanism to show which threads a user has read and which not. The link |
|
190
|
color will change back to the normal link color — indicating "unread" — |
|
191
|
when a reply is added to an existing thread because that changes where |
|
192
|
the link from the <tt>/forum</tt> page points, taking you to the newest |
|
193
|
post in the thread. |
|
194
|
|
|
195
|
The color given above is suitable for the stock skin. |
|
196
|
|
|
197
|
Beware that when changing this example, there are some |
|
198
|
[https://hacks.mozilla.org/2010/03/privacy-related-changes-coming-to-css-vistited/ |
|
199
|
| stringent restrictions] in modern browsers to prevent snoopy web sites |
|
200
|
from brute-forcing your browsing history. (See the link for the method, |
|
201
|
which explains the restrictions.) |
|
202
|
|
|
203
|
|
|
204
|
<h3 id="search">Enable Forum Search</h3> |
|
205
|
|
|
206
|
One of the underlying assumptions of the forum feature is that you will |
|
207
|
want to be able to search the forum archives, so the <tt>/forum</tt> |
|
208
|
page always includes a search box. Since that depends on search being |
|
209
|
enabled on the Fossil repository, Fossil warns that search is disabled |
|
210
|
until you go into Admin → Search and enable the "Search Forum" |
|
211
|
setting. |
|
212
|
|
|
213
|
You may want to enable some of the other Fossil search features while |
|
214
|
you're in there. All of this does come at some CPU and I/O cost, which |
|
215
|
is why it's disabled by default. |
|
216
|
|
|
217
|
|
|
218
|
<h3 id="sso">Single Sign-On</h3> |
|
219
|
|
|
220
|
If you choose to host your discussion forums within the same repository |
|
221
|
as your project's other Fossil-managed content, you inherently have a |
|
222
|
single sign-on system. Contrast third-party mailing list and forum |
|
223
|
software where you either end up with two separate user tables and |
|
224
|
permission sets, or you must go to significant effort to integrate the |
|
225
|
two login systems. |
|
226
|
|
|
227
|
You may instead choose to host your forums in a Fossil repository |
|
228
|
separate from your project's main Fossil repository. A good reason to do |
|
229
|
this is that you have a public project where very few of those |
|
230
|
participating in the forum have special capability bits for project |
|
231
|
assets managed by Fossil, so you wish to segregate the two user sets. |
|
232
|
|
|
233
|
Yet, what of the users who will have logins on both repositories? Some |
|
234
|
users will be trusted with access to the project's main Fossil |
|
235
|
repository, and these users will probably also participate in the |
|
236
|
project's Fossil-hosted forum. Fossil has a feature to solve this |
|
237
|
problem: [./caps/login-groups.md | login groups]. |
|
238
|
|
|
239
|
|
|
240
|
<h3 id="alerts">Email Alerts (a.k.a. Notifications)</h3> |
|
241
|
|
|
242
|
Internet email service has become rather complicated since its initial |
|
243
|
simple and insecure implementation decades ago. Fossil's role in all of |
|
244
|
this is rather small at the moment, but the details of the integration |
|
245
|
are complex enough to justify [./alerts.md | a separate document]. |
|
246
|
|
|
247
|
(The other reason that document is separate is that Fossil's email |
|
248
|
alerts system also gets used by features of Fossil other than the |
|
249
|
forum.) |
|
250
|
|
|
251
|
|
|
252
|
<h2 id="access">Accessing the Forum</h2> |
|
253
|
|
|
254
|
There are many paths to a repository's Fossil forum: |
|
255
|
|
|
256
|
<ul> |
|
257
|
<li> |
|
258
|
If you're using the default Fossil skin as shipped with Fossil |
|
259
|
2.7+ or one [#skin | updated] to support it, there |
|
260
|
is a Forum button in the navbar which appears for users able to |
|
261
|
access the forum. With the default skin, that button will only |
|
262
|
appear if the user's browser window is at least |
|
263
|
1200 pixels wide. The |
|
264
|
Fossil admin can adjust this limit in the skin's CSS section, down |
|
265
|
near the bottom in the definition of the `wideonly` style. |
|
266
|
</li> |
|
267
|
|
|
268
|
<li>The other stock skins have this button in them as of 2.7 as well, |
|
269
|
without the screen width restriction, since the navbar in those skins |
|
270
|
wraps on narrow screens more gracefully than the default skin |
|
271
|
does.</li> |
|
272
|
|
|
273
|
<li>Users who set up their Fossil repository under prior versions and |
|
274
|
who now have local skin changes they don't want to overwrite by |
|
275
|
reverting to the stock 2.7 version of the skin they chose to start |
|
276
|
with can easily [#skin | edit their skin] to include these links.</li> |
|
277
|
|
|
278
|
<li>A "Forum" link appears in the drop-down panel when you click the |
|
279
|
default skin's hamburger menu (☰) while logged in as any user |
|
280
|
with one or more of the [#caps | user capabilities listed above].</li> |
|
281
|
|
|
282
|
<li>That same link also appears on the repository's <tt>/sitemap</tt> |
|
283
|
page, since it provides the content for the hamburger menu's |
|
284
|
panel.</li> |
|
285
|
</ul> |
|
286
|
|
|
287
|
|
|
288
|
<h2 id="moderation">How Moderation Works</h2> |
|
289
|
|
|
290
|
In this section, we're going to call all of the following a "forum |
|
291
|
update:" |
|
292
|
|
|
293
|
* create a new post |
|
294
|
* reply to an existing post |
|
295
|
* edit a post or reply |
|
296
|
|
|
297
|
When a person with the normal <b>WrForum</b> capability |
|
298
|
updates the forum, Fossil saves the update in its block chain, but this |
|
299
|
update is impermanent because of two other table updates made at the |
|
300
|
same time: |
|
301
|
|
|
302
|
<ol> |
|
303
|
<li>Fossil saves the update artifact's ID in its <tt>private</tt> |
|
304
|
table, preventing Fossil from sending such artifacts to any of the |
|
305
|
repository's clones. (This is the same mechanism behind |
|
306
|
[./private.wiki | private branches].)</li> |
|
307
|
|
|
308
|
<li>Fossil also adds a reference to that artifact in the |
|
309
|
<tt>modreq</tt> table, which backs the moderation feature. This is |
|
310
|
what causes Fossil to leave out the Reply button when rendering that |
|
311
|
post's HTML in the forum's web interface.</li> |
|
312
|
</ol> |
|
313
|
|
|
314
|
When a moderator approves an update, Fossil deletes these table entries, |
|
315
|
making the update [./shunning.wiki | semi-permanent]. This changes how Fossil renders the |
|
316
|
HTML for that update. It also means the artifact will now sync to |
|
317
|
users with <b>[./caps/ref.html#g | Clone]</b> capability. |
|
318
|
|
|
319
|
When a forum user edits a moderator-approved artifact, what actually |
|
320
|
happens under the hood is that Fossil writes another artifact to the |
|
321
|
repository which refers to the original version as its parent, causing |
|
322
|
Fossil UI to present the new version instead of the original. The |
|
323
|
original version remains in the repository, just as with historical |
|
324
|
checkins. The parent must remain in the repository for referential |
|
325
|
integrity purposes. |
|
326
|
|
|
327
|
When you "Delete" a moderator-approved post or reply through Fossil UI, |
|
328
|
it's actually an edit with blank replacement content. The only way to |
|
329
|
truly delete such artifacts is through [./shunning.wiki | shunning]. |
|
330
|
|
|
331
|
When a user with <b>WrTForum</b> capability |
|
332
|
updates the forum, it happens in the same way except that Fossil skips |
|
333
|
the <tt>private</tt> and <tt>modreq</tt> table insertions. |
|
334
|
|
|
335
|
When a moderator rejects an update, that artifact is unceremoniously |
|
336
|
removed from the tip of the block chain. This is safe because Fossil |
|
337
|
prevents replies to a reply or post awaiting moderator approval, so |
|
338
|
referential integrity cannot be harmed. Rejecting an edit is even |
|
339
|
safer, since the original post remains behind, so that replies continue |
|
340
|
to refer to that original post. |
|
341
|
|
|
342
|
|
|
343
|
<h2 id="mod-user">Using the Moderation Feature</h2> |
|
344
|
|
|
345
|
Having described all of the work that Fossil performs under the hood on |
|
346
|
behalf of its users, we can now give the short list of work left for the |
|
347
|
repository's administrators and moderators: |
|
348
|
|
|
349
|
<ol> |
|
350
|
<li>Add the <b>[./caps/ref.html#5 | ModForum]</b> capability to any of |
|
351
|
your users who should have this ability. You don't need to do this |
|
352
|
for any user with <b>[./caps/ref.html#s | Setup]</b> or |
|
353
|
<b>[./caps/ref.html#a | Admin]</b> capability; it's |
|
354
|
[/artifact/b16221ffb736caa2?ln=1246-1257 | already included].</li> |
|
355
|
|
|
356
|
<li>When someone updates the forum, an entry will appear in the |
|
357
|
timeline if the type filter is set to "Forum" or "Any Type". If that |
|
358
|
user has only the <b>WrForum</b> capability, any |
|
359
|
other user with the <b>ModForum</b> capability |
|
360
|
will see a conditional link appear at the top of the main forum |
|
361
|
page: "Moderation Requests". Clicking this takes the moderator to |
|
362
|
the <tt>/modreq</tt> page. A moderator may wish to keep the main |
|
363
|
forum page open in a browser tab, reloading it occasionally to see |
|
364
|
when the "Moderation Requests" link reappears.</li> |
|
365
|
|
|
366
|
<li>A moderator viewing an update pending moderation sees two |
|
367
|
buttons at the bottom, "Approve" and "Reject" in place of the |
|
368
|
"Delete" button that the post's creator sees. Beware that both |
|
369
|
actions are durable and have no undo. Be careful!</li> |
|
370
|
</ol> |
|
371
|
|
|
372
|
<h2 id="close-post">Closing Forum Posts</h2> |
|
373
|
|
|
374
|
As of version 2.23, the forum interface supports the notion of |
|
375
|
"closing" posts. By default, only users with the [./caps/index.md|'s' |
|
376
|
and 'a' capabilities] may close or re-open posts, or reply to closed |
|
377
|
posts. If the [/help/forum-close-policy|forum-close-policy |
|
378
|
configuration option] is enabled then users with |
|
379
|
[./caps/index.md|forum-moderator permissions] may also perform those |
|
380
|
actions. |
|
381
|
|
|
382
|
Closing a post has the following implications: |
|
383
|
|
|
384
|
* Only authorized users may edit or respond to such posts, recursively |
|
385
|
through all responses of that post. |
|
386
|
* Only authorized users may re-open a closed post. |
|
387
|
|
|
388
|
A forum thread may be closed at any given point in the conversation, |
|
389
|
not just the starting point of the thread, and affects that specific |
|
390
|
post and all existing responses to it. |
|
391
|
|
|
392
|
Note that closing a post is effectively an "advisory lock" and may be |
|
393
|
bypassed. Any user, admin or otherwise, who can push changes to a |
|
394
|
repository may bypass closure of a post by setting the appropriate |
|
395
|
artifact tags on a local copy and pushing those changes to a remote |
|
396
|
copy of the forum. |
|
397
|
|
|
398
|
The option to close a post, permissions permitting, appears as a |
|
399
|
"Close" button on the currently-selected post. If the selected post is |
|
400
|
alread closed, a "Re-open" button will be shown instead. In order to |
|
401
|
re-open a post, <em>the closed post itself</em> must be |
|
402
|
selected. Selecting a response to that post, which is implicitly |
|
403
|
closed by the closure of its parent, will <em>not</em> offer a re-open |
|
404
|
option. |
|
405
|
|
|
406
|
Though forum users are permitted to delete their own posts, they are |
|
407
|
not permitted, without appropriate permissions, to close their own |
|
408
|
posts. This is intentional, as closing one's own post can be used to |
|
409
|
antagonize other forum users. For example, by posting something |
|
410
|
trollish or highly controversial in nature and closing the post to |
|
411
|
further responses. |
|
412
|
|