Fossil

Check-in [c1be5508]
Login

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Assorted improvements to the forum.wiki document, mainly to the new moderation material.
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA3-256:c1be550832200e5e900d9f2b927bc480a6ba6a18fa9e8ccef1cf14a32de31e17
User & Date: wyoung 2018-08-13 00:31:45
Context
2018-08-13
00:59
More forum.wiki tweaks check-in: 26424763 user: wyoung tags: trunk
00:31
Assorted improvements to the forum.wiki document, mainly to the new moderation material. check-in: c1be5508 user: wyoung tags: trunk
2018-08-12
23:24
Added the "How Moderation Works" section to www/forum.wiki, and improved the newly-renamed "Using the Moderation Feature" section as a result. check-in: 812dd52c user: wyoung tags: trunk
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to www/forum.wiki.

354
355
356
357
358
359
360

361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
...
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477


478
479
480

481
482
483
484
485
486
487
488
489
490
491
492
493
494
495

496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516


517
518
519
520
521
522
523
524
525
526
527
528
529
530
regular Fossil user up for email alerts. (Alternate path: click the user
name or login/logout link in the upper right corner, depending on the
skin you're using, then go to "Email Alerts".) You will need "Forum
Posts" checked at the least for the testing steps below.

If you use the same user name and email address as you used for your
normal user login, Fossil will simply tie your alert preferences to your

login, and it will be considered already-verified. Otherwise, Fossil
will create an alert-only record, and you will have to verify the email
address before Fossil will send notifications to it.

This shows a key aspect of the way Fossil's email alerts system works,
by the way: a user can be signed up for email alerts without having a
full-fledged Fossil user account. Only when both user names are the same
are the two records tied together under the hood.


<h4 id="alert-test">Test the Email Subsystem</h4>

If you'd rather not create an inane "testing" post in your Fossil
instance just to force out an email alert, we can test the email
subsystem separately from the rest of the Fossil email alerts system
with the following command:

<verbatim>
    $ fossil alerts test-message you@example.com --body README.md --subject Test
</verbatim>

................................................................................
</verbatim>

This only does the same thing as the final command above, rather than
send you an ale, as you might be hoping. Sorry.


<h2 id="moderation">How Moderation Works</h2>

When a person with the normal <b>Write Forum</b> capability (<tt>3</tt>)
either:

  *  creates a new post, or
  *  replies to an existing post, or
  *  edits a post/reply
  
...the new content is saved into Fossil's block chain, but two special
things happen to it:



<ol>
    <li>The artifact's ID is saved to the <tt>private</tt> table,

    preventing Fossil from sending such artifacts to any of the
    repository's clones.  (This is the same mechanism behind
    [./private.wiki | private branches].)</li>

    <li>A reference to that artifact is saved in the <tt>modreq</tt>
    table, which backs the moderation feature.  This is what causes
    Fossil to leave out the Reply button when rendering that post's HTML
    in the forum's web interface.</li>
</ol>

When a moderator approves a post, Fossil deletes these references in the
<tt>private</tt> and <tt>modreq</tt> tables so that the contribution is
effectively written semi-permanently into the Fossil block chain. The
artifact will now sync to clones, if the clone is done by a user with
<b>Check-Out</b> capability (<tt>o</tt>).


When a forum user edits a moderator-approved artifact, what actually
happens under the hood is that Fossil writes another artifact to the
repository which refers to the original version as its parent, causing
Fossil UI to present the new version instead of the original. The
original version remains in the repository, just as with historical
checkins. The parent must remain in the repository for referential
integrity purposes.

When you "Delete" such content through Fossil UI, it's actually an edit
with blank content.  The only way to truly delete such artifacts is
through [./shunning.wiki | shunning].

When a post is made by a user with <b>WriteTrusted Forum</b> capability
(<tt>4</tt>), it is posted in the same way, just with the
<tt>private</tt> and <tt>modreq</tt> table insertions skipped.

When a moderator rejects a post, reply, or edit, that artifact is
unceremoniously removed from the tip of the block chain. This is safe
since such a post cannot have any replies, so there will be no other
artifacts referring to it.




<h2 id="mod-user">Using the Moderation Feature</h2>

All of the above is work performed under the hood by Fossil on behalf of
its users. There is little work left for the administrators and
moderators of the repository:

<ol>
    <li>Add the <b>Moderate Forum</b> (<tt>5</tt>) capability to any of
    your users who should have this ability. You don't need to do this
    for any user with Setup (<tt>s</tt>) or Admin (<tt>a</tt>)
    capability; it's
    [http://fossil-scm.org/index.html/artifact/b16221ffb736caa2?ln=1246-1257







>
|
|
|










|







 








|
|

|
|
|
|
|
|
>
>


<
>
|



|
|
|
|


|
|
<
|
|
>









|
|
|





|
|
|
|
>
>




|
|
|







354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
...
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482

483
484
485
486
487
488
489
490
491
492
493
494
495

496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
regular Fossil user up for email alerts. (Alternate path: click the user
name or login/logout link in the upper right corner, depending on the
skin you're using, then go to "Email Alerts".) You will need "Forum
Posts" checked at the least for the testing steps below.

If you use the same user name and email address as you used for your
normal user login, Fossil will simply tie your alert preferences to your
login record, and the email address in your user's Contact Info field
will be considered already-verified. Otherwise, Fossil will create an
alert-only record, and you will have to verify the email address before
Fossil will send notifications to it.

This shows a key aspect of the way Fossil's email alerts system works,
by the way: a user can be signed up for email alerts without having a
full-fledged Fossil user account. Only when both user names are the same
are the two records tied together under the hood.


<h4 id="alert-test">Test the Email Subsystem</h4>

If you'd rather not create an inane "testing" post in your Fossil
instance just to force out an email alert, you can test the email
subsystem separately from the rest of the Fossil email alerts system
with the following command:

<verbatim>
    $ fossil alerts test-message you@example.com --body README.md --subject Test
</verbatim>

................................................................................
</verbatim>

This only does the same thing as the final command above, rather than
send you an ale, as you might be hoping. Sorry.


<h2 id="moderation">How Moderation Works</h2>

In this section, we're going to call all of the following a "forum
update:"

  *  create a new post
  *  reply to an existing post
  *  edit a post or reply

When a person with the normal <b>Write Forum</b> capability (<tt>3</tt>)
updates the forum, Fossil saves the update in its block chain, but this
update is impermanent because of two other table updates made at the
same time:

<ol>

    <li>Fossil saves the update artifact's ID in its <tt>private</tt>
    table, preventing Fossil from sending such artifacts to any of the
    repository's clones.  (This is the same mechanism behind
    [./private.wiki | private branches].)</li>

    <li>Fossil also adds a reference to that artifact in the
    <tt>modreq</tt> table, which backs the moderation feature.  This is
    what causes Fossil to leave out the Reply button when rendering that
    post's HTML in the forum's web interface.</li>
</ol>

When a moderator approves an update, Fossil deletes these table entries,
making the update semi-permanent. This changes how Fossil renders the

HTML for that update. It also means the artifact will now sync to
clones, if the sync is done by a user with <b>Check-Out</b> capability
(<tt>o</tt>).

When a forum user edits a moderator-approved artifact, what actually
happens under the hood is that Fossil writes another artifact to the
repository which refers to the original version as its parent, causing
Fossil UI to present the new version instead of the original. The
original version remains in the repository, just as with historical
checkins. The parent must remain in the repository for referential
integrity purposes.

When you "Delete" a moderator-approved post or reply through Fossil UI,
it's actually an edit with blank replacement content. The only way to
truly delete such artifacts is through [./shunning.wiki | shunning].

When a post is made by a user with <b>WriteTrusted Forum</b> capability
(<tt>4</tt>), it is posted in the same way, just with the
<tt>private</tt> and <tt>modreq</tt> table insertions skipped.

When a moderator rejects an update, that artifact is unceremoniously
removed from the tip of the block chain. This is safe because Fossil
prevents the creation of any replies to posts and replies that require
moderator approval, so there will be no other artifacts referring to it.
Rejecting an edit is even safer, since the original post remains behind,
maintaining referential integrity.


<h2 id="mod-user">Using the Moderation Feature</h2>

Having described all of the work that Fossil performs under the hood by
Fossil on behalf of its users, we can now give the short list of work
left for the repository's administrators and moderators:

<ol>
    <li>Add the <b>Moderate Forum</b> (<tt>5</tt>) capability to any of
    your users who should have this ability. You don't need to do this
    for any user with Setup (<tt>s</tt>) or Admin (<tt>a</tt>)
    capability; it's
    [http://fossil-scm.org/index.html/artifact/b16221ffb736caa2?ln=1246-1257