This is a proposal that aims to add an initial content notification system to BookStack. The below may be updated and developed further based upon feedback.

Note: This has been designed with the intent of being an initial implementation meeting 80% of the common needs, while being a base that does not hinder future potential to be built upon. It is not intended to meet every single use-case & potential requirement.

Proposal

• Notifications will be sent on the three following activities:
  • Page creation
  • Page update
    • Specifically content updates, whenever the main "Save" button is used in the editor.
    • Updated for this event will only be sent if not already last updated by the same user in the last 10 minutes. This is to "debounce" multiple rapid updates.
  • Page comment creation
• Notifications will be email-based.
  • Page create/update notifications will contain the page name and link, and creator/updater name.
  • Page update notifications will mention the debounce behaviour/text (in a user friendly way) to make it clear that a notification may not be received for every near-future update.
  • Page comment notifications will contain commenter name and comment plaintext.
• Users will have three notification preference checkboxes to control:
  • Notify upon changes to pages I own.
  • Notify upon comments on pages I own.
  • Notify upon replies to my comments.
    • A "reply" is a direct child comment using that's specifically created using a built-in reply functionality.
• None of the user notification preferences will be checked by default.
• A new "Can receive & manage notifications" role permission will be added.
  • If a user lacks this permission from any of their assigned roles, all notification management options will be hidden and they will not be sent notifications. Any of their previously set notification/watch preferences will still remain.
  • Only the default "Admin" role will receive this permission by default.
• Books, chapters and pages will have item-level "Watch" notification option available.
  • The user can select only one of these (think sliding scale or radio button).
  • The options are:
    • Default: No specific settings upon user-level preferences.
    • Ignore: Ignores any notifications, including those from user-level preferences.
    • New Pages: Notify on any new page. Does not interfere/affect user-level preferences at all.
      • This will only be shown for chapters/books, not pages.
    • All page updates: Notify upon page creations and page update events.
    • All page updates and comments: Notify upon page creations, page updates and any comment creation.
  • Options set for books and chapters will cascade and apply to all pages below.
    • There will be some level of indication on the "Watch" notification option if a (non-default) parent item "Watch" option is already set.
    • If "Watch" options are set at multiple levels for a page, the lowest (most specific) option will be used.

Out of scope

Here are a couple of things not specifically stated in the above, but may be important to note:

Shelves. They will have no added support for this within this implementation, due to their more complex relationship and optional existence. I'd prefer for an initial implementation to be implemented first so any desired usage with shelves can be risen and discussed based upon actual need and experience of notifications in the system, so we can best decide how/if they fit into such a system.

Other notification options. Only email-based notifications will be supported. The system will be built with potential other notification avenues in mind, but this implementation is focused solely on email.

Other notification events. Only the page-level events will emit notifications. The intent of this system is for normal users in their task of creating, collaboration and discovery. It's hard to see wide appeal for other event types outside of the role of auditing/administration, which I view as a separate goal that already has options available (webhooks, audit log, theme system etc..).

Infrastructure level considerations

This will have a performance impact on most systems where enabled, but we already have the queue system in place and guidance for queues in the docs due to Webhooks, but email notifications are likely to be more commonly used. We'll have to make sure our guidance is visible and accessible when it comes to emails and/or performance. It may be a good idea to review/update our docs and, where reasonable, provide easier use and deployment of a worker. Perhaps a task for the new System CLI? (Limited to systemd machines to keep scope reasonable).

Feedback

Feel free to comment below with any feedback. I'm particularly interested to hear if there's anything logically unsound, or if there's anything that we may hinder future ideas/development/growth for notifications, or if there's anything believed to potentially negatively impact existing BookStack use on release of such an implementation.

If you read this and are happy with the implementation, that would be good to hear too, just as positive confirmation that this all makes sense and is considered acceptable to proceed. Even just a thumbs-up reaction (found at the bottom of this comment box) would be good for this.

If there's not much to further to think about or discuss here, I may proceed with this and start implementation from the 17th with an aim for end-of-july release, otherwise this can be pushed into a wider/later release cycle.