From 4f49b16079b27d7ce633619e4cddfdf2bffbc952 Mon Sep 17 00:00:00 2001 From: cashmere Date: Fri, 4 Sep 2026 09:05:24 +0200 Subject: initial commit --- www/forum.wiki | 614 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 614 insertions(+) create mode 100644 www/forum.wiki (limited to 'www/forum.wiki') 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 @@ +Fossil Forums + +

Introduction

+ +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: + + * Easy to Administer: 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. + + * Consistent Display: 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. + + * Editable: 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. + + * Built-in Full-Text Search: Forum posts can be included in + the index used by the built-in Fossil search logic. + + * Off-Line Access: 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. + + * Automatically Cross-Referenced To Other Fossil Artifacts: 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. + + * Malefactor Resistant: 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. + + * Distributed and Tamper-Proof: 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. + +

Example Installations

+ +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. + +

Setting up a Fossil Forum

+ +

Capabilities

+ +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 anonymous user category] the +[./caps/ref.html#2 | RdForum] and +[./caps/ref.html#3 | WrForum] +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 +anonymous user any forum access, but you may wish to give the +RdForum capability to users in the reader category. + +For either type of repository, you are likely to want to give at least +the [./caps/ref.html#4 | WrTForum] capability to users in the developer +category. If you did not give the RdForum capability to +anonymous above, you should give developer that +capability here if you choose to give it WrForum or +WrTForum 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 [./caps/ref.html#7 | EmailAlert] 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 +nobody user category if you want anyone to sign up without any +restrictions. Give it to anonymous instead if you want the +user to solve a simple CAPTCHA before signing up. Or, give it to +reader or developer 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 [./caps/ref.html#5 | ModForum] capability to an uncommonly +highly-trusted user. + + +

Skin Setup

+ +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: + +
    +
  1. 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.
    2. + +
  2. 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.
    3. +
+ +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: + + +if {[anycap 23456] || [anoncap 2] || [anoncap 3]} { + menulink /forum Forum +} + + +These rules say that any logged-in user with any [./caps/ref.html#2 | +forum-related capability] or an anonymous user RdForum or +WrForum capability will see the "Forum" navbar +link, which just takes you to /forum. + +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: + + +div.forumSel { + background-color: rgba(0, 0, 0, 0.05); +} + + +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: + + +div.forumSel { + background-color: rgba(255, 255, 255, 0.05); +} + + +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: + + +div.forumPosts a:visited { + color: #6A7F94; +} + + +This changes the clicked-hyperlink color for the forum post links on the +main /forum 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 /forum 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.) + + + + +One of the underlying assumptions of the forum feature is that you will +want to be able to search the forum archives, so the /forum +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. + + +

Single Sign-On

+ +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]. + + +

Email Alerts (a.k.a. Notifications)

+ +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.) + + +

Accessing the Forum

+ +There are many paths to a repository's Fossil forum: + + + +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 ?nojs to any /forumpost +URL will disable plugging-in of the JS UI elements. (3) When forum +posts are visited via /info instead of +/forumpost, the JS-based UI elements do not plug +themselves in, leaving the legacy UI intact. + + +

How Moderation Works

+ +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 WrForum 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: + +
    +
  1. Fossil saves the update artifact's ID in its private + table, preventing Fossil from sending such artifacts to any of the + repository's clones. (This is the same mechanism behind + [./private.wiki | private branches].)
    2. + +
  2. Fossil also adds a reference to that artifact in the + modreq 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.
    3. +
+ +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 [./caps/ref.html#g | Clone] 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 WrTForum capability +updates the forum, it happens in the same way except that Fossil skips +the private and modreq 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. + + +

Using the Moderation Feature

+ +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: + +
    +
  1. Add the [./caps/ref.html#5 | ModForum] capability to any of + your users who should have this ability. You don't need to do this + for any user with [./caps/ref.html#s | Setup] or + [./caps/ref.html#a | Admin] capability; it's + [/artifact/b16221ffb736caa2?ln=1246-1257 | already included].
    2. + +
  2. 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 WrForum capability, any + other user with the ModForum capability + will see a conditional link appear at the top of the main forum + page: "Moderation Requests". Clicking this takes the moderator to + the /modreq 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.
    3. + +
  3. 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!
    4. +
+ +

Closing Forum Posts

+ +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, the closed post itself must be +selected. Selecting a response to that post, which is implicitly +closed by the closure of its parent, will not 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. + +

Setting Post Statuses

+ +As of version 2.29 forum posts may be tagged with a status. The +setting forum-statuses 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. + +forum-statuses is a JSON5-format array of objects in the +following format: + + +[ + {label:"Open", value:"open"}, + {label:"Resolved", value:"resolved"} + ... +] + +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 /forum view table gets a + data-status="X" 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
+ body.cpage-forum div.forumPosts tr[data-status="open"]
+ 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 /forum 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 status tag on the first version +of a legal post. That tag may be set to any value from the "values" +members of the forum-statuses list. + +Status tag rules: + + * status 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 status tag, or has a status 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 "closed" tag feature, 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. + +

Attachments

+ +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. + +

Draft Edits

+ +The forum uses, if available, JavaScript's localStorage +or sessionStorage 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 localStorage nor sessionStorage +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. + + +

Curious Extra Page Padding

+ +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. + +

Forked Edits

+ +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: + +

+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;
+
+ +And here's one which lists forked posts: + +

+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;
+
+ +The telling part is the fprev column: those with matching +values forked from the post referred to by fprev. -- cgit v1.3.1