Explain current federation status in FEDERATION.md new file

FEDERATION.md

@@ -0,0 +1,81 @@
+ForgeFed/ActivityPub Federation in Vervis
+=========================================
+
+At the time of writing, here's the current status of federation implemented in
+Vervis.
+
+Summary:
+
+* To post a comment on a local ticket (same server), log in and browse
+  to the ticket's page and use the ticket reply form, the regular way it's been
+  on Vervis.
+* To post a comment on a remote ticket (other server), log in and browse to the
+  /publish page, fill the form and the comment will be delivered to the right
+  place
+
+For more details, read below.
+
+## Federation triggered by regular UI
+
+* Ticket comments are federated. If you submit a ticket comment, local and
+  remote users who previously commented on the same ticket will get your
+  comment delivered to their inboxes. The user who created the ticket's project
+  will have it delivered to them too.
+* If you comment on a ticket, you automatically become a ticket follower, and
+  all future comments on the ticket will be delivered to your inbox.
+* User outboxes exist in the database, but their web pages aren't implemented,
+  returning an error
+* If you create a project, all comments on all tickets of the project will be
+  delivered to your inbox.
+* There are no notifications in the UI, so if you want to see your inbox,
+  you'll need to browse to it. See below.
+
+The ticket comment UI allows to see tickets and comments, and if you're logged
+in, you can post new comments. If you wish to post a comment on a ticket hosted
+on another server, not the one on which your account is hosted, see the
+dedicated federation pages listed below.
+
+## GET endpoints
+
+`GET /publish`
+
+A page where you can write and publish a ticket comment, either on a local
+ticket (i.e. a ticket on a project hosted on the same server as your account)
+or on a remote ticket (i.e. a ticket on a project hosted on some other server).
+
+`GET /inbox`
+
+A test page that displays received activities and the result of their
+processing.
+
+`GET /s/joe/inbox`
+
+A page that displays your personal inbox. It should list all ticket comments on
+projects you've created and and ticket comments on tickets you previously
+commented on.
+
+## POST endpoints
+
+`POST /s/joe/outbox`
+
+Personal endpoint for publishing ticket comments. When you submit the form in
+the /publish page, this is where it is sent. In the future you'll be able to
+see the content of your outbox, and other people will be able to see the public
+items in your outbox.
+
+You can access this endpoint without using the /publish page, but Vervis
+doesn't have OAuth2 support yet, so you'll need to log in first and grab the
+cookie, and send it along with the request.
+
+`POST /s/joe/inbox`
+
+Personal endpoint to which other servers deliver ticket comments for you to
+see. These are comments on tickets on which you previously commented, and thus
+automatically became a follower of thosr tickets.
+
+`POST /s/joe/p/proj/inbox`
+
+Per-project inbox, to which projects receive ticket comments from other
+servers. If someone on another server publishes a comment on your project, then
+your project will receive the comment at this endpoint and the comment will be
+displayed when you visit the ticket page.

README.md

@@ -193,7 +193,7 @@ hasn't been updated in a long time, actually, but soon I'll get to it.
       [/] View
         [/] History
         [/] Files
-    [ ] Federation
+    [~] Federation
 
 ## Reliability requirements
 
@@ -213,6 +213,10 @@ about some bug or missing feature causing loss of data or access.
     [ ] Clear policy and guidelines for DB schema changes
     [ ] Running instance has data backups
 
+## Federation
+
+See `FEDERATION.md`.
+
 ## Installation
 
 See `INSTALL.md`.

vervis.cabal

@@ -21,6 +21,7 @@ build-type:          Simple
 extra-source-files:  AUTHORS
                      CHANGELOG.md
                      COPYING
+                     FEDERATION.md
                      INSTALL.md
                      README.md
 cabal-version:       >=1.10