Adding docs/spec shell (v2).

docs/spec/README.md

@@ -0,0 +1,30 @@
+# 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),
+[`feeds.knative.dev`](/pkg/apis/feeds/v1alpha1) and
+[`flows.knative.dev`](/pkg/apis/flows/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),
+[feeds](/pkg/apis/feeds/v1alpha1) or [flows](/pkg/apis/feeds/v1alpha1) and [the
+e2e test](/test/e2e).**
+
+Docs in this directory:
+
+* [Motivation and goals](motivation.md)
+* [Resource type overview](overview.md)
+<!-- TODO(n3wscott): * [Knative Eventing API spec](spec.md) -->
+<!-- TODO(n3wscott): * [Error conditions and reporting](errors.md) -->
+<!-- TODO(n3wscott): * [Sample API usage](normative_examples.md) -->
+
+<!-- TODO(evankanderson):
+`This may be the right place, but it seems like it would be useful to include a
+section on either "Known issues" with the API and/or patterns that we've agreed
+upon. In particular, the use of containers/images for extension of Buses and
+Sources is probably worth highlighting somewhere.`
+
+The Parameters/ParametersFrom pattern for passing args to the images is
+probably also worth documenting.
+-->

docs/spec/images/overview-reference.dot

@@ -0,0 +1,33 @@
+// 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 [dir=back];
+    color=white; 
+    {rank = same; Source; EventType;}
+  }
+
+  subgraph cluster_C {
+    Feed;
+    Channel
+    Subscription;
+    label = "Flow";
+  }
+  EventType -> Feed [dir=back];
+  Feed -> Channel;
+
+  Subscription -> Service;
+  Channel -> Subscription [dir=back];
+
+  Bus -> Channel [dir=back];
+
+  {rank = max; Service;}
+}

docs/spec/motivation.md

@@ -0,0 +1,35 @@
+# Motivation
+
+The goal of Knative Eventing is to define common, composable primitives to
+enable late-binding event sources and event consumers.
+
+<!-- TODO(n3wscott): [Why late-binding] -->
+
+Knative Eventing has following principles:
+
+1. Services are loosely coupled during development and deployed independently
+  on a variety of platforms (Kubernetes, VMs, SaaS or FaaS).
+
+1. A producer can generate events before a consumer is listening, and a
+  consumer can express an interest in an event or class of events that is not
+  yet being produced.
+
+1. Services can be connected to create new applications
+    * without modifying producer or consumer.
+    * with the ability to select a specific subset of events from a particular
+      producer
+
+These primitives 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 API 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,70 @@
+# Resource Groups
+
+Knative Eventing API is grouped into _Channels_, _Feeds_ and _Flows_:
+
+* _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_ abstract the path of an event from a source takes to reach an event
+  consumer.
+
+Typically, _Feeds_ perform out-of-cluster provisioning, while _Channels_ are
+within-cluster management of event delivery. _Flows_ is a higher order wrapper
+used to connect event producers directly with event consumers leveraging 
+_Feeds_ and _Channels_.
+
+# Resource Types
+
+The primary resources in the Knative Eventing _Feeds_ API are EventSource,
+EventType and Feed:
+
+* **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.
+
+An example _Feeds_ setup: GitHub would be the _EventSource_, a Pull Request
+notification would be the _EventType_ and the _Feed_ describes the _org/repo_,
+credentials, the specific _EventType_ and the consumer of the _Feed_ events.
+
+
+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 from a _Channel_ to be
+  delivered to an HTTP endpoint.
+
+An example _Channels_ setup: A _Channel_ has declared it is implemented by a
+PubSubBusImpl. The PubSubBusImpl _Bus_ accepts input from an event producer
+that is pushing events to the _Channel_. The _Bus_ also watches for
+_Subscription_(s) on the _Channel_ and delivers the events accepted to the
+consumer.
+
+
+The _Flows_ API implements a single resource, Flow:
+
+* **Flow**, is an abstraction of the connection between an event producer to
+  the event consumer leveraging _Feed_s and _Channels_.
+
+
+An example _Flows_ setup: The _Flow_ describes the same properties as the _Feed_
+except the target could be a _Service.serving.knative.dev_ and the _Flow_ will
+create the _Channel_, _Feed_, and _Subscription_ for the event to flow from
+event producer (GitHub) to event consumer (MyService).
+
+
+![Object Model](images/overview-reference.png)
+
+See the [Knative Eventing Docs
+Architecture](https://github.com/knative/docs/blob/master/eventing/README.md#architecture)
+for more details.
+
+