Add docs re. keeping spec/implementation/conformance tests in sync (#781)

Created a README in docs/spec to list the docs in the dir and
indicate that changes to these docs should be kept in syn with
both the implementation and teh conformance tests. Folks who
are changing the API should also be responsible for updating
the docs and making sure their changes are covered by the
conformance tests.

In #780 we will look at checking this in PRs so we don't have to hope
folks will see the docs.

Fixes #592.

spec/README.md

@@ -0,0 +1,17 @@
+# Elafros API spec
+
+This directory contains the specification of the Elafros API, which is implemented in
+[`pkg/apis/ela/v1alpha1`](/pkg/apis/ela/v1alpha1) and verified via [the
+conformance tests](/test/conformance).
+
+**Updates to this spec should include a corresponding change to [the
+API implementation](/pkg/apis/ela/v1alpha1) and [the conformance
+tests](/test/conformance).** ([#780](https://github.com/elafros/elafros/issues/780))
+
+Docs in this directory:
+
+* [Motivation and goals](motivation.md)
+* [Resource type overview](overview.md)
+* [Elafros API spec](spec.md)
+* [Error conditions and reporting](errors.md)
+* [Sample API usage](normative_examples.md)

spec/motivation.md

@@ -1,3 +1,5 @@
+# Motivation
+
 The goal of the Elafros project is to provide a common toolkit and API
 framework for serverless workloads.
 

spec/spec.md

@@ -1,3 +1,8 @@
+# Elafros API spec
+
+This file contains the [resource paths](#resource-paths) and [yaml
+schemas](#resource-yaml-definitions) that make up the Elafros API.
+
 ## Resource Paths
 
 Resource paths in the Elafros API have the following standard k8s form:
@@ -29,13 +34,13 @@ prod.my-service.default.mydomain.com
 ```
 
 
-# Resource YAML Definitions
+## Resource YAML Definitions
 
 YAMLs for the Elafros API resources are described below, describing the
 basic k8s structure: metadata, spec and status, along with comments on
 specific fields.
 
-## Route
+### Route
 
 For a high-level description of Routes,
 [see the overview](overview.md#route).
@@ -92,7 +97,7 @@ status:
 ```
 
 
-## Configuration
+### Configuration
 
 For a high-level description of Configurations,
 [see the overview](overview.md#configuration).
@@ -196,7 +201,7 @@ status:
 ```
 
 
-## Revision
+### Revision
 
 For a high-level description of Revisions,
 [see the overview](overview.md#revision).