Improve specification.

3 files changed, 116 insertions, 18 deletions

diff --git a/.gitignore b/.gitignore
index 0acc030..69e9c58 100644
--- a/.gitignore
+++ b/.gitignore
@@ -2,7 +2,6 @@
 !.gitignore
 !COPYING
 !README.md
-!specification.md
 
 !doc
 doc/*
@@ -17,6 +16,9 @@ python/*
 !python/forgefed_wsgi.py
 !python/run-dev-server
 
+!specification/
+!specification/*
+
 !vocabulary/
 !vocabulary/*
 !vocabulary/COMMENT.md
diff --git a/specification.md b/specification/forgefed-vocabulary.md
index 9b0f273..403c6f8 100644
--- a/specification.md
+++ b/specification/forgefed-vocabulary.md
@@ -1,4 +1,4 @@
-# ForgeFed Specification - DRAFT
+# ForgeFed Vocabulary - DRAFT
 
 **Editors:**
 
@@ -25,10 +25,12 @@ and provides additional vocabulary for federation of version control services.
 1. [Introduction](#Introduction)
 2. [Types](#Types)
 3. [Properties](#Properties)
-4. [Client to Server Interactions](#Client to Server Interactions)
 
 ## Introduction
 
+The ForgeFed Vocabulary describes a set of types and properties to be used by
+platforms that support the ForgeFed protocol.
+
 ## Types
 
 Base URI: `https://peers.community/ns/repo-fed-vocab#`
@@ -39,7 +41,9 @@ Base URI: `https://peers.community/ns/repo-fed-vocab#`
 
 **URI:** `https://www.w3.org/ns/activitystreams#Follow`
 
-**Notes:** used by a user who wants to follow a repository
+**Notes:** used by a user who wants to follow a repository.
+This activity doesn't define a new type (the `Follow` Activity is defined in
+ActivityPub) but it's here for reference.
 
 **Example:**
 
@@ -48,19 +52,20 @@ Base URI: `https://peers.community/ns/repo-fed-vocab#`
         "summary": "Alice followed Bob",
         "type": "Follow",
         "actor": "https://localhost/alice",
-        "object": "https://remotehost/bob"
+        "object": "https://remotehost/bob/repository"
     }
 
 #### Push
 
 **URI:** `https://peers.community/ns/repo-fed-vocab#Push`
 
-**Notes:**
+**Notes:** Indicates that new content has been pushed to the repository. The
+Activity's object MUST contain a list of Commits.
 
 **Example:**
 
     {
-        "@context": "https://www.w3.org/ns/activitystreams",
+        "@context": "https://peers.community/ns/repo-fed-vocab",
         "type": "Push",
         "actor": "https://localhost/alice/repo2",
         "object": [
@@ -75,13 +80,27 @@ Base URI: `https://peers.community/ns/repo-fed-vocab#`
 
 ### Actor Types
 
+#### Repository
+
+**URI:** `https://peers.community/ns/repo-fed-vocab#Repository`
+
+**Notes:** Represents a single repository.
+
+**Example:**
+
+    {
+        "@context": "https://peers.community/ns/repo-fed-vocab#",
+        "type": "Repository",
+        "name": "Homeworks-2019"
+    }
+
 ### Object Types
 
 #### Commit
 
 **URI:** `https://peers.community/ns/repo-fed-vocab#Commit`
 
-**Notes:** 
+**Notes:** Represents a single Commit in a Repository.
 
 **Example:**
 
@@ -97,7 +116,8 @@ Base URI: `https://peers.community/ns/repo-fed-vocab#`
 
 **URI:** `https://peers.community/ns/repo-fed-vocab#Ticket`
 
-**Notes:** 
+**Notes:** Represents a single ticket (aka "issue") for a Repository. Tickets
+are used to track ideas, enhancements, tasks, or bugs.
 
 **Example:**
 
@@ -114,13 +134,4 @@ Base URI: `https://peers.community/ns/repo-fed-vocab#`
 
 ## Properties
 
-## Client to Server Interactions
-
-### Follow Activity
-
-The `Follow` activity is used to subscribe to the activities of a repository.
-
-### Push Activity
 
-The `Push` activity is used to notify followers of new code that has been
-pushed to a repository.
diff --git a/specification/forgefed.md b/specification/forgefed.md
new file mode 100644
index 0000000..07aa4a8
--- /dev/null
+++ b/specification/forgefed.md
@@ -0,0 +1,85 @@
+# ForgeFed - DRAFT
+
+**Editors:**
+
+- deesix
+- fr33domlover
+- zPlus
+- ... add other editors
+
+**Repository:**
+
+- [NotABug](https://notabug.org/peers/forgefed)
+
+**Copyright:**
+
+2019 ...
+
+## Abstract
+
+This document describes the ForgeFed protocol. ForgeFed is an extension of the
+[ActivityPub](https://www.w3.org/TR/activitypub/) protocol for delivering
+notifications and content for federation of version control systems.
+The purpose of this specification is to describe a protocol that can be integrated
+into source code management for enabling collaboration across different
+platforms.
+
+## Table of Contents
+1. [Overview](#Overview)
+2. [Conformance](#Conformance)
+3. [Objects](#Objects)
+4. [Actors](#Actors)
+5. [Client to Server Interactions](#Client to Server Interactions)
+6. [Server to Server Interactions](#Server to Server Interactions)
+7. [Acknowledgements](#Acknowledgements)
+
+## 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
+
+The key words MAY, MUST, MUST NOT, SHOULD, and SHOULD NOT are to be interpreted
+as described in [RFC2119].
+
+## Objects
+
+Objects are the core concept around which both ActivityPub and ForgeFed are built.
+Examples of Objects are Note, Ticket, or Image.
+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
+
+A ForgeFed implementation MUST provide an Actor of type `Repository` for every
+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
+
+    TODO: how are these different than AP?
+
+## 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
+
+The `Push` activity is used to notify followers of new code that has been
+pushed to a repository.