Adding docs/spec shell.

docs/spec/README.md

@@ -0,0 +1,18 @@
+# Knative Eventing API spec
+
+This directory contains the specification of the Knative Eventing API, which is
+implemented in [`channels.knative.dev`](/pkg/apis/channels/v1alpha1) and
+[`feeds.knative.dev`](/pkg/apis/feeds/v1alpha1) and verified via [the e2e
+test](/test/e2e).
+
+**Updates to this spec should include a corresponding change to the
+API implementation for [channels](/pkg/apis/channels/v1alpha1) or
+in [feeds](/pkg/apis/feeds/v1alpha1) and [the e2e test](/test/e2e).**
+
+Docs in this directory:
+
+* [Motivation and goals](motivation.md)
+* [Resource type overview](overview.md)
+<!-- * [Knative Eventing API spec](spec.md) -->
+<!-- * [Error conditions and reporting](errors.md) -->
+<!-- * [Sample API usage](normative_examples.md) -->

docs/spec/images/overview-reference.dot

@@ -0,0 +1,32 @@
+// This is the overview graph for object refrences in the control plane.
+//
+// To reproduce the PNG, run the following:
+// $ dot -Tpng overview-reference.dot -o overview-reference.png
+//
+digraph G {
+  ordering = out;
+  rankdir = LR;
+
+  node [shape=rectangle; width=1.25; height=.5; fixedsize=true;]
+
+  subgraph cluster_A {
+    Source -> EventType;
+    color=white; 
+    {rank = same; Source; EventType}
+  }
+
+  subgraph cluster_B {
+    Channel
+    Subscription;
+    label = "Bus";
+    color=black;
+  }
+
+  EventType -> Feed [dir=back];
+  Feed -> Channel;
+
+  Subscription -> Service;
+  Channel -> Subscription [dir=back];
+
+  {rank = max; Service;}
+}

docs/spec/motivation.md

@@ -0,0 +1,17 @@
+# Motivation
+
+Knative Eventing implements the common components for an event delivery
+ecosystem. These common components enable producing and consuming events
+adhering to the [CloudEvents
+Specification](https://github.com/cloudevents/spec), in a decoupled way.
+
+Kubernetes has no primitives related to event processing, yet this is an
+essential component in serverless workloads. Eventing introduces high-level
+primitives for event production and delivery with a focus on push over HTTP. If
+a new event source or type is required of your application, the effort required
+to plumb them into the existing eventing framework will be minimal and will
+integrate with CloudEvents middleware and message consumers.
+
+The Knative Eventing APIs is intended to operate independently, and interop
+well with the [Serving API](https://github.com/knative/serving) and [Build
+API](https://github.com/knative/build).

docs/spec/overview.md

@@ -0,0 +1,78 @@
+# Resource Groups
+
+Knative Eventing API is grouped into _Channels_ and _Feeds_:
+
+* _Channels_ define an abstraction between the eventing infrastructure and the
+  consumption and production of the events.
+
+* _Feeds_ bridge the event source into the eventing framework.
+
+* _Flows_ are the higher order abstractions for eventing that use _Channels_
+  and _Feeds_.
+
+Typically, _Feeds_ perform out-of-cluster provisioning, while _Channels_ are
+within-cluster management of event delivery.
+
+# Resource Types
+
+The primary resources in the Knative Eventing _Feeds_ API are EventSource, EventType and Bind:
+
+* **EventSource**, an archetype of an event producer.
+
+* **EventType**, the schema for an event.
+
+* **Feed**, the association between the output of an event producer to the
+  input of an event consumer.
+
+
+The primary resources in the Knative Eventing _Channels_ API are Channel, Subscription and Bus:
+
+* **Channel**, a named endpoint which accepts and forwards events.
+
+* **Bus**, an implementation of an event delivery mechanism.
+
+* **Subscription**, an expressed interest in events to be delivered to a
+  service.
+
+The primary resources in the Knative Eventing _Flows_ API are Flow:
+
+* **Flow**, the connection between an event producer to the event consumer.
+
+![Object Model](images/overview-reference.png)
+
+## EventSource
+
+A software system which wishes to make changes in state discoverable via
+eventing, without prior knowledge of systems which might consume state changes.
+
+## EventType
+
+TODO
+
+## Feed
+
+A configuration of event transmission from a single Source to a single Action.
+A Feed may contain additional properties of the event transmission such as
+filtering, timeouts, rate limits, and buffering.
+
+## Channel
+
+A named in-cluster Service on a Bus which accepts events delivered from a Feed.
+
+## Bus
+
+A system which routes events from Channels to subscribed Service endpoints. The
+Broker MAY (RFC 2119) provide durable, at-least-once semantics and buffering of
+events between the Source and the Action. Brokers also perform event fan-out
+across multiple actions which are subscribed to the same channel.
+
+
+## Subscription
+
+A control plane construct which allows the Bus to route events received on a
+Channel to the subscribed Service.
+
+# Eventing
+
+TODO an overview of how these objects are created and perhaps the persona
+expected to make each.