FEDERATION.md: Write basic description of comments

This commit is contained in:
fr33domlover 2019-05-28 09:43:24 +00:00
parent f904123d91
commit 5907a447c0

View file

@ -389,6 +389,88 @@ Rotate 1 key per hour. Especially if that key is Ed25519.
#### (3) Comments #### (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 #### (4) Tickets
#### (5) Patches #### (5) Patches