Add API compatibility policy

This doc will set out our backward incompatible change policy, so that
contributors have guidance on how to make changes, and so that users
will know what to expect.

In my original proposal, I wanted to make `Task` and `TaskRun` `beta`
immediately, but after some pushback from other contributors, we have
landed on leaving these `alpha` for a while (and having a hackathon to
get more user input!). (Which turned out to be good since we've already
found a couple of backwards incompatible changes we want to make!)

Fixes tektoncd#34

CONTRIBUTING.md

@@ -17,6 +17,7 @@ In this file you'll find info on:
   [code](#coding-standards)
 - [Finding something to work on](#finding-something-to-work-on)
 - [The roadmap](#roadmap)
+- [API compatibility policy](#api-compatibility-policy)
 - [Contacting other contributors](#contact)
 
 _See also
@@ -164,6 +165,11 @@ like to work on it** and we will consider it assigned to you.
 
 The project's roadmap for 2019 is published [here](./roadmap-2019.md).
 
+## API compatibility policy
+
+The API compatibility policy (i.e. the policy for making backwards incompatible API changes)
+can be found [here](api_compatibility_policy.md).
+
 ## Contact
 
 This work is being done by

DEVELOPMENT.md

@@ -182,3 +182,5 @@ If you need to add a new CRD type, you will need to add:
 1. A yaml definition in [config/](./config)
 1. Add the type to the cluster roles in
    [200-clusterrole.yaml](./config/200-clusterrole.yaml)
+
+_See [the API compatibility policy](api_compatibility_policy.md)._

README.md

@@ -30,6 +30,9 @@ Pipelines are **Typed**:
 - [Read about it](/docs/README.md)
 - Look at [some examples](/examples)
 
+_See [our API compatibility policy](api_compatibility_policy.md) for info on
+the stability level of the API._
+
 ## Want to contribute?
 
 We are so excited to have you!

api_compatibility_policy.md

@@ -0,0 +1,85 @@
+# API compatibility policy
+
+This document proposes a policy regarding making API updates to the CRDs in this repo.
+Users should be able to build on the APIs in these projects with a clear idea of what
+they can rely on and what should be considered in progress and therefore likely to change.
+
+For these purposes the CRDs are divided into three groups:
+
+* [`Build` and `BuildTemplate`] - from https://github.com/knative/build
+* [`TaskRun`, `Task`, and `ClusterTask`] - "more stable"
+* [`PipelineRun`, `Pipeline` and `PipelineResource`] - "less stable"
+
+The use of `alpha`, `beta` and `GA` in this document is meant to correspond roughly to
+[the kubernetes API deprecation policies](https://kubernetes.io/docs/reference/using-api/deprecation-policy/#deprecating-a-flag-or-cli).
+
+## What does compatibility mean here?
+
+This policy is about changes to the APIs of the [CRDs](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/),
+aka the spec of the CRD objects themselves.
+
+A backwards incompatible change would be a change that requires a user to update existing
+instances of these CRDs in clusters where they are deployed (after
+[automatic conversion is available](https://kubernetes.io/docs/tasks/access-kubernetes-api/custom-resources/custom-resource-definition-versioning/#webhook-conversion)
+this process may become less painful).
+
+The current process would look something like:
+
+1. Backup the instances
+2. Delete the instances
+3. Deploy the new type definitions
+4. Update the backups with the new spec
+5. Deploy the updated backups
+
+_This policy does not yet cover other functionality which could be considered part of the API,
+but isn’t part of the CRD definition (e.g. a contract re. files expected to be written in
+certain locations by a resulting pod)._
+
+## `Build` and `BuildTemplate`
+
+The CRD types [`Build`](https://github.com/knative/docs/blob/master/build/builds.md) and
+[`BuildTemplate`](https://github.com/knative/docs/blob/master/build/build-templates.md)
+should be considered frozen at beta and only additive changes should be allowed.
+
+Support will continue for the `Build` type for the foreseeable future, particularly to support
+embedding of Build resources within [`knative/serving`](https://github.com/knative/serving) objects.
+
+## `TaskRun`, `Task`, and `ClusterTask`
+
+The CRD types [`Task`](https://github.com/knative/build-pipeline/blob/master/docs/Concepts.md#task),
+[`ClusterTask`](https://github.com/knative/build-pipeline/blob/master/docs/Concepts.md#clustertask),
+and [`TaskRun`](https://github.com/knative/build-pipeline/blob/master/docs/Concepts.md#taskrun)
+should be considered `alpha`, however these types are more stable than `Pipeline`, `PipelineRun`,
+and `PipelineResource`.
+
+### Possibly `beta` in Knative 0.6
+
+The status of these types will be revisited ~2 releases (i.e. Knative 0.6) and see if they can be
+promoted to `beta`.
+
+Once these types are promoted to `beta`, any backwards incompatible changes must be introduced in
+a backwards compatible manner first, with a deprecation warning in the release notes, for at least one
+full release before the backward incompatible change is made.
+
+There are two reasons for this:
+- `Task` and `TaskRun` are considered upgraded versions of `Build`, meaning that the APIs benefit
+  from a significant amount of user feedback and iteration
+- Going forward users should use `TaskRun` and `Task` instead of `Build` and `BuildTemplate`,
+  those users should not expect the API to be changed on them without warning
+
+The exception to this is that `PipelineResource` definitions can be embedded in `TaskRuns`,
+and since the `PipelineResource` definitions are considered less stable, changes to the spec of
+the embedded `PipelineResource` can be introduced between releases.
+
+## `PipelineRun`, `Pipeline` and `PipelineResource`
+
+The CRD types [`Pipeline`](https://github.com/knative/build-pipeline/blob/master/docs/Concepts.md#pipeline),
+[`PipelineRun`](https://github.com/knative/build-pipeline/blob/master/docs/Concepts.md#pipelinerun)
+and [`PipelineResource`](https://github.com/knative/build-pipeline/blob/master/docs/Concepts.md#pipelineresources)
+should be considered `alpha`, i.e. the API should be considered unstable. Backwards incompatible
+changes can be introduced between releases, however they must include a backwards incompatibility
+warning in the release notes.
+
+The reason for this is not yet having enough user feedback to commit to the APIs as
+they currently exist. Once significant user input has been given into the API design, we can
+upgrade these CRDs to `beta`.