From 1fa71b6b9c002a158e6b2d4b71988faae15c4532 Mon Sep 17 00:00:00 2001
From: Pere Lev <pere@towards.vision>
Date: Fri, 19 Jul 2024 18:08:44 +0300
Subject: [PATCH] Docs: API.md: Info about the specific inbox activity types

---
 API.md | 83 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 82 insertions(+), 1 deletion(-)

diff --git a/API.md b/API.md
index 9190306..afe44f3 100644
--- a/API.md
+++ b/API.md
@@ -248,9 +248,13 @@ detect whether new items have appeared at the top. The inbox is a (typically
 paged) reverse-chronologically `OrderedCollection` of `Activity` objects, as
 described in the ActivityPub specification.
 
+The ForgeFed specification has a relevant detailed section:
+
+<https://forgefed.org/spec/#s2s>
+
 ## Common properties
 
-These would appear in every actvity:
+These would appear in every activity:
 
 - `id`: ID URI of the activity
 - `type`: One of the ActivityPub or ForgeFed activity types
@@ -277,24 +281,101 @@ These would appear in some activities:
 
 ## Accept
 
+The `actor` has accepted/approved some activity.
+
+Always:
+
+- `object`: URI of the activity being accepted
+
+Sometimes:
+
+- `result`: URI of some new entity created as a result of accepting the
+  `object`
+
 ## Add
 
+The `actor` has requested to add some actor to an authorization-related
+collection. The cases are everything except adding direct collaborators (which
+use an `Invite` activity instead):
+
+- Add a componet to a project
+- Add a component/project to a team
+- Create a parent-child link between a pair of projects/teams
+
+Always:
+
+- `object`: URI of object being added
+- `target`: URI of the collection
+- `instrument`: Maximal role (see `Role` type in ForgeFed spec) of
+  authorizations that will be passed through this newly formed link
+
+To determine the case, grab the `target` collection's owning actor, pointed via
+the collection's `context` field. Now you can example the `target` and `object`
+actor types, as well as which field of the `target` actor specifies the
+collection:
+
+- `components` of a `Project`
+- `context` (i.e. projects) of a component
+- `subteams` of a `Team`
+- `context` (i.e. parents) of a `Team`
+- `subprojects` of a `Project`
+- `context` (i.e. parents) of a `Project`
+- `teams` of a component/`Project`
+- `teamResources` of a `Team`
+
+The `Add` activity is usually just the first step in a sequence of activities
+that create the desired authorization link. The activity sequences are
+described in detail in the specification, e.g. in these sections:
+
+- <https://forgefed.org/spec/#associating-projects-and-components>
+- <https://forgefed.org/spec/#adding-and-removing-children-and-parents-to-projects-and-teams>
+
 ## Apply
 
 ## Create
 
+An actor has published a new object/resource, specified in the `object` field:
+
+- A comment on an issue/PR (`Note`)
+- An issue (`Ticket`)
+- A component (`TicketTracker`, `PatchTracker`, `Repository`)
+- `Team`
+- `Project`
+
 ## Follow
 
+The `actor` has requested to follow the actor/object specified by the `object`
+field.
+
 ## Grant
 
+See <https://forgefed.org/spec/#managing-access>.
+
 ## Invite
 
+<https://forgefed.org/spec/#Invite>
+
+Except `target` specifies the *collection*, not the resource itself. For a
+`Team`, that would be the URI of its `members` collection. For other actor
+types, it would be the URI of the `collaborators` collection.
+
 ## Join
 
+<https://forgefed.org/spec/#Join>
+
+Except `object` specifies the *collection*, not the resource itself. For a
+`Team`, that would be the URI of its `members` collection. For other actor
+types, it would be the URI of the `collaborators` collection.
+
 ## Offer
 
+- <https://forgefed.org/spec/#opening-issue>
+- <https://forgefed.org/spec/#opening-mr>
+
 ## Push
 
+<https://forgefed.org/spec/#pushing>
+
 ## Reject
 
 ## Remove