FEDERATION.md: Write basic description of comments

FEDERATION.md

@@ -389,6 +389,88 @@ Rotate 1 key per hour. Especially if that key is Ed25519.
 
 #### (3) Comments
 
+Comments are `Note` objects, published using the `Create` activity.
+Requirements, suggestions and details:
+
+- The AS2 `context` property must be specified, and must be a single value, and
+  refers to the discussion topic, which is a ticket or a merge request or a
+  patch or something else.
+- The AS2 `inReplyTo` property must be provided, and must be a single value,
+  and either specifies the same value as `context` (which means it's a
+  top-level comment under the topic), or specifies another comment, to which it
+  replies.
+- When receiving a comment with context C and inReplyTo some existing comment
+  message M, verify that the context of M is C too
+- Some objects that are discussion topics, such as tickets, have a `followers`
+  collection, which should include all the previous commenters on the topic (if
+  you comment on a ticket, you probably want to start following it to be
+  notified on new comments, although this isn't required, so that people can
+  opt in and opt out of notifications) as well as anyone who sent a Follow
+  activity even without commenting, as well as the topic author (e.g. ticket
+  author), and this `followers` collection can be used for comment audience.
+- Some objects similarly have a `team` collection (a new proposed ForgeFed
+  property). The `team` collection would include people who manage the object.
+  While `followers` is usually opt-in, `team` is usually opt-out: For example,
+  in a project managed by 3 people, the default could be that all 3 of them get
+  notified on every new comment on every new ticket, but once a ticket is
+  assigned to one of them, the others can opt out of notifications to reduce
+  the noise in their personal inboxes. But how `team` works is
+  behind-the-scenes for comments: Just consider it to be a collection of team
+  members managing the objects and who want to be notified on new comments.
+- Some objects that are discussion topics are actors, or are managed by an
+  actor (for example tickets may exist under projects, and projects are
+  actors), and when you deliver the comment to them, they store and display it
+  in the appropriate discussion page
+- Normally, the audience of a new comment would include:
+  * The discussion topic (if it's an actor) or the actor that manages it (e.g.
+    the project to which the ticket belongs, on which you're commenting)
+  * The topic's followers collection
+  * The topic's team collection
+  * Specific individuals/groups you want to mention or bring the discussion to
+    their attention
+- This setup with a followers collection means that clients don't need to do
+  any digging and querying to figure out who the commenters and team members
+  are, and it allows people to opt out of notifications if they previously
+  commented on some topic but don't want to be in the discussion anymore. This
+  makes it very easy for clients to correctly address comments.
+
+`GET /luke/outbox/A0O8l`
+
+```json
+{
+    "@context": "https://www.w3.org/ns/activitystreams",
+    "id": "https://federated.coop/luke/outbox/A0O8l",
+    "type": "Create"
+    "to": [
+        "https://federated.coop/luke/text-adventure",
+        "https://federated.coop/luke/text-adventure/issues/113/followers",
+        "https://federated.coop/luke/text-adventure/issues/113/team"
+    ],
+    "actor": "https://federated.coop/luke",
+    "object": {
+        "id": "https://federated.coop/luke/comments/L0dRp",
+        "type": "Note",
+        "attributedTo": "https://federated.coop/luke",
+        "context": "https://federated.coop/luke/text-adventure/issues/113",
+        "published": "2019-05-26T11:56:50.024267645Z",
+        "to": [
+            "https://federated.coop/luke/text-adventure",
+            "https://federated.coop/luke/text-adventure/issues/113/followers",
+            "https://federated.coop/luke/text-adventure/issues/113/team"
+        ],
+        "content": "That's such a wonderful idea!",
+        "inReplyTo": "https://poetry.space/aviva/comments/xN82v"
+    }
+}
+```
+
+TODO:
+
+- `replies` and how the C2S object nesting depth proposal
+- Use `nonActors` in the example?
+- Content format? HTML? Markdown source? Tags? Referenced ticktes?
+- Visibility and privacy?
+
 #### (4) Tickets
 
 #### (5) Patches