diff options
Diffstat (limited to 'www/forum.wiki')
| -rw-r--r-- | www/forum.wiki | 614 |
1 files changed, 614 insertions, 0 deletions
diff --git a/www/forum.wiki b/www/forum.wiki new file mode 100644 index 0000000..2489fac --- /dev/null +++ b/www/forum.wiki @@ -0,0 +1,614 @@ +<title>Fossil Forums</title> + +<h2>Introduction</h2> + +Fossil includes a built-in discussion forum, designed to substitute +for a mailing list. Email notification is available to receive posts, +but the web-based UI must be used to enter new posts. Advantages of +the forum include: + + * <b>Easy to Administer:</b> If you have already set up a + [./server/|Fossil server] with [./alerts.md|email alerts] + then turning on the forum feature + is just a matter of flipping some permission bits. There is + no new software to install and configure, and the same logins + and passwords work. + + * <b>Consistent Display:</b> Forum posts can be in [/md_rules|Markdown], + [/wiki_rules|Fossil Wiki], or plain text. Whichever format is used, the result is + displayed consistently across all platforms and operating systems and + between mobile devices and desktops. + + * <b>Editable:</b> Forum posts can be amended after they are sent, + to fix typos or provide updates. The original posts are preserved + as part of the historical record, but only the amended posts are + displayed by default. + + * <b>Built-in Full-Text Search:</b> Forum posts can be included in + the index used by the built-in Fossil search logic. + + * <b>Off-Line Access:</b> Because forum posts are synced along with + all other artifacts, you can search the forum, or add new posts, or + edit existing posts, all while off-line. + + * <b>Automatically Cross-Referenced To Other Fossil Artifacts:</b> Because forum + posts are normal Fossil artifacts, you can link from them to + other Fossil artifacts (check-ins, wiki, tickets) and from those other + artifacts to forum posts. The reverse links are recognized and + displayed automatically on the receiver. + + * <b>Malefactor Resistant:</b> Because Fossil accepts forum posts + only via the web UI, it is more resistent to spam. Passers-by + can post to the forum anonymously (subject to moderation), without + the hassle of a sign-up process. + + * <b>Distributed and Tamper-Proof:</b> Posts are stored in the Fossil + repository using the same [./fileformat.wiki | DAG/Merkle-tree design] + that Fossil uses to store your check-ins, wiki documents, etc. + Forum posts sync to cloned repositories. + +<h2>Example Installations</h2> + +Both the [forum:/forum|Fossil project itself] and the +[https://sqlite.org/forum/forum|SQLite project] use the Fossil forum in place +of mailing lists. The forum has worked well on both projects. The ability +to post anonymously provides a low-resistance path for people to report +problems, resulting in more problems being reported and fixed. +The ability to moderate and amend forum posts means that the +forums contain better information. And backups and archives +are as easy as running "clone". + +Both Fossil and SQLite keep their forums as separate repositories. +But there is no requirement to do this. A forum can be coresident in +the same repository with the source code. + +<h2 id="setup">Setting up a Fossil Forum</h2> + +<h3 id="caps">Capabilities</h3> + +By default, no Fossil user has permission to use the forums except for +users with Setup and Admin capabilities, which get these as part of the +large package of other capabilities they get. + +For public Fossil repositories that wish to accept new users without +involving a human, go into Admin → Access and enable the "Allow +users to register themselves" setting. You may also wish to give users +in [./caps/#ucat | the <tt>anonymous</tt> user category] the +<b>[./caps/ref.html#2 | RdForum]</b> and +<b>[./caps/ref.html#3 | WrForum]</b> +capabilities: this allows people to post without creating an account +simply by solving [./antibot.wiki | a simple CAPTCHA]. + +For a private repository, you probably won't want to give the +<tt>anonymous</tt> user any forum access, but you may wish to give the +<b>RdForum</b> capability to users in the <tt>reader</tt> category. + +For either type of repository, you are likely to want to give at least +the <b>[./caps/ref.html#4 | WrTForum]</b> capability to users in the <tt>developer</tt> +category. If you did not give the <b>RdForum</b> capability to +<tt>anonymous</tt> above, you should give <tt>developer</tt> that +capability here if you choose to give it <b>WrForum</b> or +<b>WrTForum</b> capability. + +If you want to use the email alert feature, by default only those +users in the Setup and Admin user categories can make use of it. Grant +the <b>[./caps/ref.html#7 | EmailAlert]</b> capability to give others access to this feature. +Alternately, you can handle alert signups outside of Fossil, with +a Setup or Admin users manually signing users up via Admin → +Notification. You'll want to grant this capability to the +<tt>nobody</tt> user category if you want anyone to sign up without any +restrictions. Give it to <tt>anonymous</tt> instead if you want the +user to solve a simple CAPTCHA before signing up. Or, give it to +<tt>reader</tt> or <tt>developer</tt> if you want only users with Fossil +logins to have this ability. (That's assuming you give one or both of +these capabilities to every user on your Fossil repository.) + +By following this advice, you should not need to tediously add +capabilities to individual accounts except in atypical cases, such as +to grant the <b>[./caps/ref.html#5 | ModForum]</b> capability to an uncommonly +highly-trusted user. + + +<h3 id="skin">Skin Setup</h3> + +If you create a new Fossil repository with version 2.7 or newer, its +default skin is already set up correctly for typical forum +configurations. + +If you have an existing repository, you have two choices if you want its +skin to be upgraded to support forums: + +<ol> + <li>Go into Admin → Skins and switch from your current skin to + one of the stock skins. If you were on a stock skin, just switch away + from your current one to the actual stock skin, since they will be + different after the upgrade.</li> + + <li>If you have local customization that you do not want to throw + away, you can use the diff feature of Fossil's skin editor to show how + the skins differ.</li> +</ol> + +The remainder of this section summarizes the differences you're expected +to see when taking option #2. + +The first thing is that you'll need to add something like the following +to the Header part of the skin to create the navbar link: + +<verbatim> +if {[anycap 23456] || [anoncap 2] || [anoncap 3]} { + menulink /forum Forum +} +</verbatim> + +These rules say that any logged-in user with any [./caps/ref.html#2 | +forum-related capability] or an anonymous user <b>RdForum</b> or +<b>WrForum</b> capability will see the "Forum" navbar +link, which just takes you to <tt>/forum</tt>. + +The exact code you need here varies depending on which skin you're +using. Follow the style you see for the other navbar links. + +The new forum feature also brings many new CSS styles to the table. If +you're using the stock skin or something sufficiently close, the changes +may work with your existing skin as-is. Otherwise, you might need to +adjust some things, such as the background color used for the selected +forum post: + +<verbatim> +div.forumSel { + background-color: rgba(0, 0, 0, 0.05); +} +</verbatim> + +That overrides the default — a hard-coded light cyan — with a 95% +transparent black overlay instead, which simply darkens your skin's +normal background color underneath the selected post. That should work +with almost any background color except for very dark background colors. +For dark skins, an inverse of the above trick will work better: + +<verbatim> +div.forumSel { + background-color: rgba(255, 255, 255, 0.05); +} +</verbatim> + +That overlays the background with 5% white to lighten it slightly. + +Another new forum-related CSS style you might want to reflect into your +existing skin is: + +<verbatim> +div.forumPosts a:visited { + color: #6A7F94; +} +</verbatim> + +This changes the clicked-hyperlink color for the forum post links on the +main <tt>/forum</tt> page only, which allows your browser's history +mechanism to show which threads a user has read and which not. The link +color will change back to the normal link color — indicating "unread" — +when a reply is added to an existing thread because that changes where +the link from the <tt>/forum</tt> page points, taking you to the newest +post in the thread. + +The color given above is suitable for the stock skin. + +Beware that when changing this example, there are some +[https://hacks.mozilla.org/2010/03/privacy-related-changes-coming-to-css-vistited/ +| stringent restrictions] in modern browsers to prevent snoopy web sites +from brute-forcing your browsing history. (See the link for the method, +which explains the restrictions.) + + +<h3 id="search">Enable Forum Search</h3> + +One of the underlying assumptions of the forum feature is that you will +want to be able to search the forum archives, so the <tt>/forum</tt> +page always includes a search box. Since that depends on search being +enabled on the Fossil repository, Fossil warns that search is disabled +until you go into Admin → Search and enable the "Search Forum" +setting. + +You may want to enable some of the other Fossil search features while +you're in there. All of this does come at some CPU and I/O cost, which +is why it's disabled by default. + + +<h3 id="sso">Single Sign-On</h3> + +If you choose to host your discussion forums within the same repository +as your project's other Fossil-managed content, you inherently have a +single sign-on system. Contrast third-party mailing list and forum +software where you either end up with two separate user tables and +permission sets, or you must go to significant effort to integrate the +two login systems. + +You may instead choose to host your forums in a Fossil repository +separate from your project's main Fossil repository. A good reason to do +this is that you have a public project where very few of those +participating in the forum have special capability bits for project +assets managed by Fossil, so you wish to segregate the two user sets. + +Yet, what of the users who will have logins on both repositories? Some +users will be trusted with access to the project's main Fossil +repository, and these users will probably also participate in the +project's Fossil-hosted forum. Fossil has a feature to solve this +problem: [./caps/login-groups.md | login groups]. + + +<h3 id="alerts">Email Alerts (a.k.a. Notifications)</h3> + +Internet email service has become rather complicated since its initial +simple and insecure implementation decades ago. Fossil's role in all of +this is rather small at the moment, but the details of the integration +are complex enough to justify [./alerts.md | a separate document]. + +(The other reason that document is separate is that Fossil's email +alerts system also gets used by features of Fossil other than the +forum.) + + +<h2 id="access">Accessing the Forum</h2> + +There are many paths to a repository's Fossil forum: + +<ul> + <li> + If you're using the default Fossil skin as shipped with Fossil + 2.7+ or one [#skin | updated] to support it, there + is a Forum button in the navbar which appears for users able to + access the forum. With the default skin, that button will only + appear if the user's browser window is at least + 1200 pixels wide. The + Fossil admin can adjust this limit in the skin's CSS section, down + near the bottom in the definition of the `wideonly` style. + </li> + + <li>The other stock skins have this button in them as of 2.7 as well, + without the screen width restriction, since the navbar in those skins + wraps on narrow screens more gracefully than the default skin + does.</li> + + <li>Users who set up their Fossil repository under prior versions and + who now have local skin changes they don't want to overwrite by + reverting to the stock 2.7 version of the skin they chose to start + with can easily [#skin | edit their skin] to include these links.</li> + + <li>A "Forum" link appears in the drop-down panel when you click the + default skin's hamburger menu (☰) while logged in as any user + with one or more of the [#caps | user capabilities listed above].</li> + + <li>That same link also appears on the repository's <tt>/sitemap</tt> + page, since it provides the content for the hamburger menu's + panel.</li> +</ul> + +The forum uses JavaScript to allow for a more comfortable editing +experience than is possible with static HTML. If one takes issue with, +or has issues with, the JavaScript-based forum editing and response +features, there are several ways around them: (1) Clients with JS +disabled should see the legacy (pre-mid-2026) input forms and +buttons. (2) Adding <code>?nojs</code> to any <code>/forumpost</code> +URL will disable plugging-in of the JS UI elements. (3) When forum +posts are visited via <code>/info</code> instead of +<code>/forumpost</code>, the JS-based UI elements do not plug +themselves in, leaving the legacy UI intact. + + +<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>WrForum</b> capability +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 [./shunning.wiki | semi-permanent]. This changes how Fossil renders the +HTML for that update. It also means the artifact will now sync to +users with <b>[./caps/ref.html#g | Clone]</b> capability. + +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 user with <b>WrTForum</b> capability +updates the forum, it happens in the same way except that Fossil skips +the <tt>private</tt> and <tt>modreq</tt> table insertions. + +When a moderator rejects an update, that artifact is unceremoniously +removed from the tip of the block chain. This is safe because Fossil +prevents replies to a reply or post awaiting moderator approval, so +referential integrity cannot be harmed. Rejecting an edit is even +safer, since the original post remains behind, so that replies continue +to refer to that original post. + + +<h2 id="mod-user">Using the Moderation Feature</h2> + +Having described all of the work that Fossil performs under the hood 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>[./caps/ref.html#5 | ModForum]</b> capability to any of + your users who should have this ability. You don't need to do this + for any user with <b>[./caps/ref.html#s | Setup]</b> or + <b>[./caps/ref.html#a | Admin]</b> capability; it's + [/artifact/b16221ffb736caa2?ln=1246-1257 | already included].</li> + + <li>When someone updates the forum, an entry will appear in the + timeline if the type filter is set to "Forum" or "Any Type". If that + user has only the <b>WrForum</b> capability, any + other user with the <b>ModForum</b> capability + will see a conditional link appear at the top of the main forum + page: "Moderation Requests". Clicking this takes the moderator to + the <tt>/modreq</tt> page. A moderator may wish to keep the main + forum page open in a browser tab, reloading it occasionally to see + when the "Moderation Requests" link reappears.</li> + + <li>A moderator viewing an update pending moderation sees two + buttons at the bottom, "Approve" and "Reject" in place of the + "Delete" button that the post's creator sees. Beware that both + actions are durable and have no undo. Be careful!</li> +</ol> + +<h2 id="close-post">Closing Forum Posts</h2> + +As of version 2.23 the forum interface supports the notion of +"closing" posts. By default, only users with the [./caps/index.md|'s' +and 'a' capabilities] may close or re-open posts, or reply to closed +posts. If the [/help/forum-close-policy|forum-close-policy +configuration option] is enabled then users with +[./caps/index.md|forum-moderator permissions] may also perform those +actions. + +Closing a post has the following implications: + + * Only authorized users may edit or respond to such posts, recursively + through all responses of that post. + * Only authorized users may re-open a closed post. + +A forum thread may be closed at any given point in the conversation, +not just the starting point of the thread, and affects that specific +post and all existing responses to it. + +Note that closing a post is effectively an "advisory lock" and may be +bypassed. Any user, admin or otherwise, who can push changes to a +repository may bypass closure of a post by setting the appropriate +artifact tags on a local copy and pushing those changes to a remote +copy of the forum. + +The option to close a post, permissions permitting, appears as a +"Close" button on the currently-selected post. If the selected post is +alread closed, a "Re-open" button will be shown instead. In order to +re-open a post, <em>the closed post itself</em> must be +selected. Selecting a response to that post, which is implicitly +closed by the closure of its parent, will <em>not</em> offer a re-open +option. + +Though forum users are permitted to delete their own posts, they are +not permitted, without appropriate permissions, to close their own +posts. This is intentional, as closing one's own post can be used to +antagonize other forum users. For example, by posting something +trollish or highly controversial in nature and closing the post to +further responses. + +<h2 id="status">Setting Post Statuses</h2> + +As of version 2.29 forum posts may be tagged with a status. The +setting <tt>forum-statuses</tt> controls whether this feature is is +enabled. If it is not set, is not valid JSON5, or has only a single +entry, then status are not shown in the forum. + +<tt>forum-statuses</tt> is a JSON5-format array of objects in the +following format: + +<verbatim> +[ + {label:"Open", value:"open"}, + {label:"Resolved", value:"resolved"} + ... +]</verbatim> + +The list defines the legal statuses for forum posts and syncs with +other project-level settings. All "label" and "value" members must be +unique within the scope of that list. + +The "value" values must be legal for use as HTML "dataset" members so +that they can be used for with CSS selectors to apply per-status +styling. + +If the list is valid JSON5 and has two or more entries then the forum +behavior changes in the following ways: + + * Each TR element of the main <tt>/forum</tt> view table gets a + <tt>data-status="X"</tt> member, where "X" is the value part from + the associated status. This can be used to style the statuses + in the site skin using CSS selectors such as<br> + <tt>body.cpage-forum div.forumPosts tr[data-status="open"]</tt><br> + Because there is no default status list, no predefined styles + are applied. + * The forum list shows the "label" value of the current status and + a selection list of available filters. It elides the status column + when filtering on a specific status. + * The root of each thread, when selected, gets a new UI control for + displaying or editing the status, depending on permissions. + * A drop-down selection list is added to the <tt>/forum</tt> page + for filtering based on the status. + +A list with only a single entry is treated as empty, the justification +being that if there is only one option then the UI does not need to be +cluttered with it. + +This setting is applied via a <tt>status</tt> tag on the first version +of a legal post. That tag may be set to any value from the "values" +members of the <tt>forum-statuses</tt> list. + +Status tag rules: + + * <tt>status</tt> is only observed on the root of each thread. The UI + does nothing with that tag on responses. + * The first list entry is considered to be the default status. Any post + which has no <tt>status</tt> tag, or has a <tt>status</tt> tag value + which is not in that list, is assumed for most purposes to have the + value of the first entry in the list. + * The tag is applied only to the first version of any given post. The + UI ensures that the tag is applied to the proper post, even when + rendering a newer version. + +Caveat: a "closed" status is not recommended because it's easy to confuse with +the <a href='#close-post'>"closed" tag feature</a>, which behaves considerably +differently and predates that "status" tag support by about three years. The +"closed" semantics cannot be trivially consolidated with those of "status" +but we reserve the right to do so at some point. + +<h2 id="attachments">Attachments</h2> + +As of version 2.29 users with the [./caps/index.md|'B' capability] may +attach files to forum posts. Files may not be attached until a forum +post is saved for the first time, after which an "Attach" button will +appear in the post when it is selected. Attached files undergo +moderation exactly like forum posts do. When a moderator accepts a +pending-moderation posts, all files attached to it which are also +pending approval are also approved. Similarly, when a moderator +rejects a pending-moderation post, all files attached to it which are +also pending approval are rejected. + +Developer notes regarding the save-before-attach limitation: + + * We cannot add the attachment form to the current post editor + because (A) the Preview option would upload the files each time + (B) we cannot pre-populate file selection elements so could not + restore them when rendering the preview's response. + * To work around that we need to reimplement the forum editor + using AJAX-friendly APIs. That would allow us to render a preview + without reloading the page, to attach multiple files at once, + to support pasting a screenshot as an attachment, and to submit both + a new post and its attachments at the same time. + * We have AJAX-capable preview code in /wiki and /fileedit. + * We have paste-screenshot code in /chat but integrating it here will + require adding a "paste" button to the attachment UI. + +Developer notes regarding automatic acceptance/rejection of +attachments: + + * There is a race condition here where an admin may approve + attachments they have not yet seen: user creates posts, admin gets + notified, admin reads post, user attaches a file at that time, + admin approves post. + +TBD is whether to accept that case or to remove automatic approval of +attached files. + +<h2 id="drafts">Draft Edits</h2> + +The forum uses, if available, JavaScript's <code>localStorage</code> +or <code>sessionStorage</code> to store local drafts of new +posts, replies, and edits to existing posts. Each time an editor +input field loses focus, the draft is saved. When viewing a forum +thread, the Edit and Reply buttons get clearly marked if they +have an associated local draft. + +Local drafts for replies and responses (but not new posts) are +automatically purged at semi-random intervals. Every Nth visit to a +forum page has a small chance to run the cleanup, and drafts older +than 10 days old are purged. + +If neither <code>localStorage</code> nor <code>sessionStorage</code> +are available, it uses a transient storage object which is recreated +on each page-load, so it cannot store drafts outside of a single +thread at a time. + +Beware: Each draft is keyed to the post it is editing or replied to, +which means that editing or replying to the same post from different +tabs will cause collisions. The editor to most recently lose the focus +will save the draft, overwriting the other. + +In browsers which support Web Locks, attempts to edit resp. reply to a +post which is already being edited resp. replied to in another tab +will show an error for the second and subsequent tabs. The first tab +to use the edit/reply buttons will hold a separate Web Lock for each +and forbid edit/reply access to the post in other tabs until the +locking tab is closed. + + +<h2 id="padding">Curious Extra Page Padding</h2> + +Users may notice that the forum pages get a bunch of padding added to +the bottom of the page when an editor widget is opened. This is not a +bug, but a workaround to help avoid the UI jumping around when +rendering a preview wildly resizes the widget. The effect is +especially helpful when working on posts while the bottom footer of +the page is in the viewport, as the footer is a hard boundary against +scrolling. With the extra padding, the editor widget's top edge shifts +around less when the preview is shown and hidden. + +<h2 id="fork">Forked Edits</h2> + +It is possible to "fork" forum messages, in the same way that any +given check-in may cause a fork. This can happen when a message is +edited concurrently from two or more browser tabs or via two or more +fossil instances which subsequently sync with each other. + +When a forum post is forked, the UI currently behaves as it does for +concurrent wiki page edits, showing only the most recent +edit. Currently (2026-06) the UI is incapable of showing the older +forked copies but (A) the data are still part of the SCM history and +(B) there are plans to improve the UI to show such forks. + +For trivia's sake, here's a query which finds posts which have +forks: + +<pre><verbatim> +SELECT bp.rid AS parentRid, bp.uuid parentUuid, count(f.fprev) forkCount +FROM blob b, blob bp, forumpost f +WHERE b.rid=f.fpid +AND f.fprev=bp.rid +GROUP BY f.fprev +HAVING forkCount>1; +</verbatim></pre> + +And here's one which lists forked posts: + +<pre><verbatim> +WITH multiparent(mpid) AS ( + SELECT fprev FROM forumpost f + GROUP BY fprev + HAVING count(fprev)>1 +) +SELECT datetime(fmtime), forumpost.* +FROM forumpost, multiparent +WHERE fprev=mpid +ORDER BY mpid, fpid, fmtime; +</verbatim></pre> + +The telling part is the <code>fprev</code> column: those with matching +values forked from the post referred to by <code>fprev</code>. |