Improve vocabulary.

2 files changed, 74 insertions, 40 deletions

diff --git a/specification/forgefed-vocabulary.md b/specification/forgefed-vocabulary.md
index 3cdc84f..214d7a3 100644
--- a/specification/forgefed-vocabulary.md
+++ b/specification/forgefed-vocabulary.md
@@ -15,30 +15,38 @@
 
 2019 ...
 
-## Abstract
+# Abstract
 
 This document describes the ForgeFed vocabulary. It's intended to be an extension
 of the [ActivityPub Vocabulary](https://www.w3.org/TR/activitystreams-vocabulary/)
 and provides additional vocabulary for federation of project management and
 version control system hosting and collaboration platforms.
 
-## Table of Contents
+# Table of Contents
+
 1. [Introduction](#Introduction)
 2. [Types](#Types)
 3. [Properties](#Properties)
 
-## Introduction
+1. Introduction
 
 The ForgeFed Vocabulary describes a set of types and properties to be used by
 platforms that support the ForgeFed protocol.
 
-## Types
+2. Types
+
+The base URI to be used as context for the new ForgeFed types and properties has
+been defined to be `https://forgefed.peers.community/ns#`. Therefore any ForgeFed
+activity MUST use the following `context`
 
-Base URI: `https://forgefed.peers.community/ns`
+    "@context": [
+        "https://www.w3.org/ns/activitystreams",
+        "https://forgefed.peers.community/ns"
+    ]
 
-### Activity Types
+2.1. Activity Types
 
-#### Follow
+2.1.1. Follow
 
 **URI:** `https://www.w3.org/ns/activitystreams#Follow`
 
@@ -53,18 +61,19 @@ ActivityPub) but it's here for reference.
             "https://www.w3.org/ns/activitystreams",
             "https://forgefed.peers.community/ns"
         ],
-        "summary": "Alice followed Bob",
+        "summary": "Alice started following ForgeFed",
         "type": "Follow",
         "actor": "https://localhost/alice",
-        "object": "https://remotehost/bob/repository"
+        "object": "https://remotehost/bob/forgefed"
     }
 
-#### Push
+2.1.2. Push
 
 **URI:** `https://forgefed.peers.community/ns#Push`
 
 **Notes:** Indicates that new content has been pushed to the repository. The
 Activity's object MUST contain a list of Commits.
+A Repository actor can use this Activity to notify followers of new changes.
 
 **Example:**
 
@@ -73,6 +82,7 @@ Activity's object MUST contain a list of Commits.
             "https://www.w3.org/ns/activitystreams",
             "https://forgefed.peers.community/ns"
         ],
+        "summary": "Alice pushed 2 new commits to Repo2."
         "type": "Push",
         "actor": "https://localhost/alice/repo2",
         "object": [
@@ -85,9 +95,34 @@ Activity's object MUST contain a list of Commits.
         ]
     }
 
-### Actor Types
+2.2. Actor Types
+
+2.2.1. Person
+
+**URI:** `https://www.w3.org/ns/activitystreams#Person`
+
+**Notes:** Represents forge user. For this purpose ForgeFed reuses the Person
+type defined by ActivityPub.
+
+**Example:**
+
+    {
+        "@context": [
+            "https://www.w3.org/ns/activitystreams",
+            "https://forgefed.peers.community/ns"
+        ],
+        "type": "Person",
+        "id": "https://localhost/alice",
+        "name": "Alice Smith",
+        "preferredUsername": "alice",
+        "summary": "",
+        "inbox": "",
+        "outbox": "",
+        "followers": "",
+        "following": ""
+    }
 
-#### Repository
+2.2.2. Repository
 
 **URI:** `https://forgefed.peers.community/ns#Repository`
 
@@ -100,13 +135,19 @@ Activity's object MUST contain a list of Commits.
             "https://www.w3.org/ns/activitystreams",
             "https://forgefed.peers.community/ns"
         ],
+        "id": "https://localhost/alice/forgefed",
         "type": "Repository",
-        "name": "Homeworks-2019"
+        "name": "ForgeFed",
+        "summary": "ForgeFed development",
+        "inbox": "",
+        "outbox": "",
+        "followers": "",
+        "following": ""
     }
 
-### Object Types
+2.3. Object Types
 
-#### Commit
+2.3.1. Commit
 
 **URI:** `https://forgefed.peers.community/ns#Commit`
 
@@ -121,7 +162,7 @@ Activity's object MUST contain a list of Commits.
         ],
         "type": "Commit",
         "id": "https://localhost/alice/repo2/commit/2c7323781aec1f7",
-        "author": ""
+        "author": "Alice"
         "message": "Fix #89"
     }
 
@@ -148,6 +189,6 @@ are used to track ideas, enhancements, tasks, or bugs.
         "context": ""
     }
 
-## Properties
+3. Properties
 
 
diff --git a/specification/forgefed.md b/specification/forgefed.md
index 07aa4a8..6d5968d 100644
--- a/specification/forgefed.md
+++ b/specification/forgefed.md
@@ -15,7 +15,7 @@
 
 2019 ...
 
-## Abstract
+# Abstract
 
 This document describes the ForgeFed protocol. ForgeFed is an extension of the
 [ActivityPub](https://www.w3.org/TR/activitypub/) protocol for delivering
@@ -24,7 +24,10 @@ The purpose of this specification is to describe a protocol that can be integrat
 into source code management for enabling collaboration across different
 platforms.
 
-## Table of Contents
+# Status of This Document
+
+# Table of Contents
+
 1. [Overview](#Overview)
 2. [Conformance](#Conformance)
 3. [Objects](#Objects)
@@ -33,18 +36,18 @@ platforms.
 6. [Server to Server Interactions](#Server to Server Interactions)
 7. [Acknowledgements](#Acknowledgements)
 
-## Overview
+1. Overview
 
 ForgeFed is an extension of [ActivityPub](https://www.w3.org/TR/activitypub/)
 and follows the same "actors" model, with a client-to-server protocol and a
 server-to-server protocol.
 
-## Conformance
+2. Conformance
 
 The key words MAY, MUST, MUST NOT, SHOULD, and SHOULD NOT are to be interpreted
 as described in [RFC2119].
 
-## Objects
+3. Objects
 
 Objects are the core concept around which both ActivityPub and ForgeFed are built.
 Examples of Objects are Note, Ticket, or Image.
@@ -52,7 +55,7 @@ Objects are wrapped in Activities, a subtype of Object that describes some form
 of action that may happen, is currently happening, or has already happened.
 Examples of Activities are Create, Delete, or Follow.
 
-## Actors
+4. Actors
 
 A ForgeFed implementation MUST provide an Actor of type `Repository` for every
 repository that should support federation.
@@ -60,26 +63,16 @@ repository that should support federation.
 A ForgeFed implementation SHOULD provide an Actor of type `Person` for every user
 of the platform.
 
-## Client to Server Interactions
+5. Client to Server Interactions
 
-    TODO: how are these different than AP?
+ForgeFed uses Activities for client to server interactions, as described by
+ActivityPub. A client will send objects (eg. a Ticket) wrapped in a Activity
+(eg. Create) to an actor's outbox, and in turn the server will take care of
+delivery.
 
-## Server to Server Interactions
+6. Server to Server Interactions
 
     TODO: how are these different than AP?
 
-## Acknowledgements
-
-
-
-
---- PUT THESE IN THE CORRECT PLACE
-
-### Follow Activity
-
-The `Follow` activity is used to subscribe to the activities of a repository.
-
-### Push Activity
+7. Acknowledgements
 
-The `Push` activity is used to notify followers of new code that has been
-pushed to a repository.