Fossil SCM
Assorted improvements to the forum.wiki document, mainly to the new moderation material.
Commit
c1be550832200e5e900d9f2b927bc480a6ba6a18fa9e8ccef1cf14a32de31e17
Parent
812dd52c7d5e305…
1 file changed
+38
-33
+38
-33
| --- www/forum.wiki | ||
| +++ www/forum.wiki | ||
| @@ -356,13 +356,14 @@ | ||
| 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,11 +370,11 @@ | ||
| 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 [email protected] --body README.md --subject Test |
| @@ -463,66 +464,70 @@ | ||
| 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 |
| --- www/forum.wiki | |
| +++ www/forum.wiki | |
| @@ -356,13 +356,14 @@ | |
| 356 | skin you're using, then go to "Email Alerts".) You will need "Forum |
| 357 | Posts" checked at the least for the testing steps below. |
| 358 | |
| 359 | If you use the same user name and email address as you used for your |
| 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. |
| 364 | |
| 365 | This shows a key aspect of the way Fossil's email alerts system works, |
| 366 | by the way: a user can be signed up for email alerts without having a |
| 367 | full-fledged Fossil user account. Only when both user names are the same |
| 368 | are the two records tied together under the hood. |
| @@ -369,11 +370,11 @@ | |
| 369 | |
| 370 | |
| 371 | <h4 id="alert-test">Test the Email Subsystem</h4> |
| 372 | |
| 373 | 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 | subsystem separately from the rest of the Fossil email alerts system |
| 376 | with the following command: |
| 377 | |
| 378 | <verbatim> |
| 379 | $ fossil alerts test-message [email protected] --body README.md --subject Test |
| @@ -463,66 +464,70 @@ | |
| 463 | This only does the same thing as the final command above, rather than |
| 464 | send you an ale, as you might be hoping. Sorry. |
| 465 | |
| 466 | |
| 467 | <h2 id="moderation">How Moderation Works</h2> |
| 468 | |
| 469 | 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 | |
| 479 | <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 |
| 482 | repository's clones. (This is the same mechanism behind |
| 483 | [./private.wiki | private branches].)</li> |
| 484 | |
| 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> |
| 489 | </ol> |
| 490 | |
| 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>). |
| 496 | |
| 497 | When a forum user edits a moderator-approved artifact, what actually |
| 498 | happens under the hood is that Fossil writes another artifact to the |
| 499 | repository which refers to the original version as its parent, causing |
| 500 | Fossil UI to present the new version instead of the original. The |
| 501 | original version remains in the repository, just as with historical |
| 502 | checkins. The parent must remain in the repository for referential |
| 503 | integrity purposes. |
| 504 | |
| 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 | |
| 509 | When a post is made by a user with <b>WriteTrusted Forum</b> capability |
| 510 | (<tt>4</tt>), it is posted in the same way, just with the |
| 511 | <tt>private</tt> and <tt>modreq</tt> table insertions skipped. |
| 512 | |
| 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. |
| 517 | |
| 518 | |
| 519 | <h2 id="mod-user">Using the Moderation Feature</h2> |
| 520 | |
| 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: |
| 524 | |
| 525 | <ol> |
| 526 | <li>Add the <b>Moderate Forum</b> (<tt>5</tt>) capability to any of |
| 527 | your users who should have this ability. You don't need to do this |
| 528 | for any user with Setup (<tt>s</tt>) or Admin (<tt>a</tt>) |
| 529 |
| --- www/forum.wiki | |
| +++ www/forum.wiki | |
| @@ -356,13 +356,14 @@ | |
| 356 | skin you're using, then go to "Email Alerts".) You will need "Forum |
| 357 | Posts" checked at the least for the testing steps below. |
| 358 | |
| 359 | If you use the same user name and email address as you used for your |
| 360 | normal user login, Fossil will simply tie your alert preferences to your |
| 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. |
| 365 | |
| 366 | This shows a key aspect of the way Fossil's email alerts system works, |
| 367 | by the way: a user can be signed up for email alerts without having a |
| 368 | full-fledged Fossil user account. Only when both user names are the same |
| 369 | are the two records tied together under the hood. |
| @@ -369,11 +370,11 @@ | |
| 370 | |
| 371 | |
| 372 | <h4 id="alert-test">Test the Email Subsystem</h4> |
| 373 | |
| 374 | If you'd rather not create an inane "testing" post in your Fossil |
| 375 | instance just to force out an email alert, you can test the email |
| 376 | subsystem separately from the rest of the Fossil email alerts system |
| 377 | with the following command: |
| 378 | |
| 379 | <verbatim> |
| 380 | $ fossil alerts test-message [email protected] --body README.md --subject Test |
| @@ -463,66 +464,70 @@ | |
| 464 | This only does the same thing as the final command above, rather than |
| 465 | send you an ale, as you might be hoping. Sorry. |
| 466 | |
| 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 |
| 476 | |
| 477 | When a person with the normal <b>Write Forum</b> capability (<tt>3</tt>) |
| 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: |
| 481 | |
| 482 | <ol> |
| 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 |
| 485 | repository's clones. (This is the same mechanism behind |
| 486 | [./private.wiki | private branches].)</li> |
| 487 | |
| 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> |
| 492 | </ol> |
| 493 | |
| 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>). |
| 499 | |
| 500 | When a forum user edits a moderator-approved artifact, what actually |
| 501 | happens under the hood is that Fossil writes another artifact to the |
| 502 | repository which refers to the original version as its parent, causing |
| 503 | Fossil UI to present the new version instead of the original. The |
| 504 | original version remains in the repository, just as with historical |
| 505 | checkins. The parent must remain in the repository for referential |
| 506 | integrity purposes. |
| 507 | |
| 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]. |
| 511 | |
| 512 | When a post is made by a user with <b>WriteTrusted Forum</b> capability |
| 513 | (<tt>4</tt>), it is posted in the same way, just with the |
| 514 | <tt>private</tt> and <tt>modreq</tt> table insertions skipped. |
| 515 | |
| 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. |
| 522 | |
| 523 | |
| 524 | <h2 id="mod-user">Using the Moderation Feature</h2> |
| 525 | |
| 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: |
| 529 | |
| 530 | <ol> |
| 531 | <li>Add the <b>Moderate Forum</b> (<tt>5</tt>) capability to any of |
| 532 | your users who should have this ability. You don't need to do this |
| 533 | for any user with Setup (<tt>s</tt>) or Admin (<tt>a</tt>) |
| 534 |