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 Side-by-Side Diffs Ignore Whitespace Patch

Changes to www/forum.wiki.

   354    354   regular Fossil user up for email alerts. (Alternate path: click the user
   355    355   name or login/logout link in the upper right corner, depending on the
   356    356   skin you're using, then go to "Email Alerts".) You will need "Forum
   357    357   Posts" checked at the least for the testing steps below.
   358    358   
   359    359   If you use the same user name and email address as you used for your
   360    360   normal user login, Fossil will simply tie your alert preferences to your
   361         -login, and it will be considered already-verified. Otherwise, Fossil
   362         -will create an alert-only record, and you will have to verify the email
   363         -address before Fossil will send notifications to it.
          361  +login record, and the email address in your user's Contact Info field
          362  +will be considered already-verified. Otherwise, Fossil will create an
          363  +alert-only record, and you will have to verify the email address before
          364  +Fossil will send notifications to it.
   364    365   
   365    366   This shows a key aspect of the way Fossil's email alerts system works,
   366    367   by the way: a user can be signed up for email alerts without having a
   367    368   full-fledged Fossil user account. Only when both user names are the same
   368    369   are the two records tied together under the hood.
   369    370   
   370    371   
   371    372   <h4 id="alert-test">Test the Email Subsystem</h4>
   372    373   
   373    374   If you'd rather not create an inane "testing" post in your Fossil
   374         -instance just to force out an email alert, we can test the email
          375  +instance just to force out an email alert, you can test the email
   375    376   subsystem separately from the rest of the Fossil email alerts system
   376    377   with the following command:
   377    378   
   378    379   <verbatim>
   379    380       $ fossil alerts test-message you@example.com --body README.md --subject Test
   380    381   </verbatim>
   381    382   
................................................................................
   461    462   </verbatim>
   462    463   
   463    464   This only does the same thing as the final command above, rather than
   464    465   send you an ale, as you might be hoping. Sorry.
   465    466   
   466    467   
   467    468   <h2 id="moderation">How Moderation Works</h2>
          469  +
          470  +In this section, we're going to call all of the following a "forum
          471  +update:"
          472  +
          473  +  *  create a new post
          474  +  *  reply to an existing post
          475  +  *  edit a post or reply
   468    476   
   469    477   When a person with the normal <b>Write Forum</b> capability (<tt>3</tt>)
   470         -either:
   471         -
   472         -  *  creates a new post, or
   473         -  *  replies to an existing post, or
   474         -  *  edits a post/reply
   475         -  
   476         -...the new content is saved into Fossil's block chain, but two special
   477         -things happen to it:
          478  +updates the forum, Fossil saves the update in its block chain, but this
          479  +update is impermanent because of two other table updates made at the
          480  +same time:
   478    481   
   479    482   <ol>
   480         -    <li>The artifact's ID is saved to the <tt>private</tt> table,
   481         -    preventing Fossil from sending such artifacts to any of the
          483  +    <li>Fossil saves the update artifact's ID in its <tt>private</tt>
          484  +    table, preventing Fossil from sending such artifacts to any of the
   482    485       repository's clones.  (This is the same mechanism behind
   483    486       [./private.wiki | private branches].)</li>
   484    487   
   485         -    <li>A reference to that artifact is saved in the <tt>modreq</tt>
   486         -    table, which backs the moderation feature.  This is what causes
   487         -    Fossil to leave out the Reply button when rendering that post's HTML
   488         -    in the forum's web interface.</li>
          488  +    <li>Fossil also adds a reference to that artifact in the
          489  +    <tt>modreq</tt> table, which backs the moderation feature.  This is
          490  +    what causes Fossil to leave out the Reply button when rendering that
          491  +    post's HTML in the forum's web interface.</li>
   489    492   </ol>
   490    493   
   491         -When a moderator approves a post, Fossil deletes these references in the
   492         -<tt>private</tt> and <tt>modreq</tt> tables so that the contribution is
   493         -effectively written semi-permanently into the Fossil block chain. The
   494         -artifact will now sync to clones, if the clone is done by a user with
   495         -<b>Check-Out</b> capability (<tt>o</tt>).
          494  +When a moderator approves an update, Fossil deletes these table entries,
          495  +making the update semi-permanent. This changes how Fossil renders the
          496  +HTML for that update. It also means the artifact will now sync to
          497  +clones, if the sync is done by a user with <b>Check-Out</b> capability
          498  +(<tt>o</tt>).
   496    499   
   497    500   When a forum user edits a moderator-approved artifact, what actually
   498    501   happens under the hood is that Fossil writes another artifact to the
   499    502   repository which refers to the original version as its parent, causing
   500    503   Fossil UI to present the new version instead of the original. The
   501    504   original version remains in the repository, just as with historical
   502    505   checkins. The parent must remain in the repository for referential
   503    506   integrity purposes.
   504    507   
   505         -When you "Delete" such content through Fossil UI, it's actually an edit
   506         -with blank content.  The only way to truly delete such artifacts is
   507         -through [./shunning.wiki | shunning].
          508  +When you "Delete" a moderator-approved post or reply through Fossil UI,
          509  +it's actually an edit with blank replacement content. The only way to
          510  +truly delete such artifacts is through [./shunning.wiki | shunning].
   508    511   
   509    512   When a post is made by a user with <b>WriteTrusted Forum</b> capability
   510    513   (<tt>4</tt>), it is posted in the same way, just with the
   511    514   <tt>private</tt> and <tt>modreq</tt> table insertions skipped.
   512    515   
   513         -When a moderator rejects a post, reply, or edit, that artifact is
   514         -unceremoniously removed from the tip of the block chain. This is safe
   515         -since such a post cannot have any replies, so there will be no other
   516         -artifacts referring to it.
          516  +When a moderator rejects an update, that artifact is unceremoniously
          517  +removed from the tip of the block chain. This is safe because Fossil
          518  +prevents the creation of any replies to posts and replies that require
          519  +moderator approval, so there will be no other artifacts referring to it.
          520  +Rejecting an edit is even safer, since the original post remains behind,
          521  +maintaining referential integrity.
   517    522   
   518    523   
   519    524   <h2 id="mod-user">Using the Moderation Feature</h2>
   520    525   
   521         -All of the above is work performed under the hood by Fossil on behalf of
   522         -its users. There is little work left for the administrators and
   523         -moderators of the repository:
          526  +Having described all of the work that Fossil performs under the hood by
          527  +Fossil on behalf of its users, we can now give the short list of work
          528  +left for the repository's administrators and moderators:
   524    529   
   525    530   <ol>
   526    531       <li>Add the <b>Moderate Forum</b> (<tt>5</tt>) capability to any of
   527    532       your users who should have this ability. You don't need to do this
   528    533       for any user with Setup (<tt>s</tt>) or Admin (<tt>a</tt>)
   529    534       capability; it's
   530    535       [http://fossil-scm.org/index.html/artifact/b16221ffb736caa2?ln=1246-1257