[wip] documentation

docs/forge.org

@@ -507,14 +507,80 @@ available from the ~magit-pull~ transient (on ~F~).
 - Key: f N (forge-pull-notifications) ::
 - Key: N f n ::
 
-  This command uses a forge's API to fetch all notifications from that
-  forge including, but not limited to, the notifications for the current
-  repository.
-
-  Fetching all notifications fetches associated topics even if you
-  have not started fetching *all* topics for the respective repositories
-  (using ~forge-pull~), but it does not cause the topics to be listed in
-  the status buffer of such "uninitialized" repositories.
+  This command uses a Github's API to fetch all notifications from
+  that forge, including, but not limited to, the notifications for the
+  current repository.  Other forges are currently not supported.
+
+  Unfortunately Github's notification API is so bad that Forge cannot
+  fully work around its defects.  As a consequence users have to know
+  about the following defects and adjust their workflow accordingly.
+
+  A notification can be read/unread, done/pending and marked/unmarked.
+  Unfortunately the API only exposes the first of these booleans, and
+  for now Forge doesn't try to fake the third.  However, whether or no
+  you done with a notification, is a very important distinction, that
+  we just cannot do without.
+
+  Forge sets the done/pending boolean based on the value of the
+  read/unread boolean, which obviously is completely wrong, but also
+  the best we can do.  It works like this:
+
+  Note that there only ever is one notification about any given issue
+  or pull-request.  Even if someone comments on an ancient issue that
+  was resolved years ago, the notification that you receive about that
+  is technically the same notification (object).
+
+  1. If the API response says that the notification is "unread" then
+     Forge considers the notification "pending" as well.
+
+     That matches the behavior in the web interface: there too, every
+     notification that is "unread" is also always "pending".
+
+  2. Otherwise, if the API response says that the notification has
+     already been "read", then Forge's behavior depends on whether the
+     notification about the topic in question has been fetched before.
+
+     If the same notification has been fetched before, then the value
+     of the ~done~ slot is always left untouched.
+
+     If the notification was just fetched for the first time (but you
+     have already "read" it using the web interface without manually
+     marking it as "unread" again, and the API response therefore says
+     that it is "read"), then Forge marks the notification as "done".
+
+  Unless you never look at notifications using the web interface, or
+  you always mark every notification as "unread" after reading it
+  using the web interface, you will often end up with notifications
+  that are falsely considerd "done" by Forge.
+
+  When you notice this is the case, list all (locally known as)
+  "unread" notifications, using ~n l n~. (At least this is the default
+  behavior of ~forge-list-notifications~, you can configure it to list a
+  different set of notifications).  Also visit
+  https://github.com/notifications in browser.  The same notifications
+  should be listed in both places.
+
+  (Forge currently only support issues and pull-requests, but not
+  discussions, comments on commits, and code reviews.  I recently
+  started working on support for those, but until I am done with that,
+  you will have to ignore all notifications that are not about issues
+  or pull-requests.)
+
+  In the web interface mark all notifications that are missing from
+  the local list as unread.  Then invoke this command with a prefix
+  argument to force the last three hundred or so notifications to be
+  fetched again.  After doing that these notifications are "pending"
+  and "unread" both in the web interface and locally.
+
+  Synchronizing in the other direction also only works partially.  If
+  you locally visit the topic corresponding to a previously "unread"
+  notification, then it is marked as "read", locally as well as on
+  Github.
+
+  However, if you locally mark a notification as "unread", "done" or
+  "pending", then that does not update the corresponding boolean on
+  Github.  Once more the reason is that Github's API is abysmal when
+  it comes to notifications.
 
 Note how pulling data from a forge's API works the same way as pulling
 Git data does; you do it explicitly when you want to see the work done