From 284f0be55e1021b71590d8abc178e5a6d21a411b Mon Sep 17 00:00:00 2001 From: Christie Wilson Date: Fri, 1 Feb 2019 17:17:06 -0800 Subject: [PATCH] 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 #34 --- CONTRIBUTING.md | 6 +++ DEVELOPMENT.md | 2 + README.md | 3 ++ api_compatibility_policy.md | 85 +++++++++++++++++++++++++++++++++++++ 4 files changed, 96 insertions(+) create mode 100644 api_compatibility_policy.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9637a4f2e31..4d2da109377 100644 --- a/CONTRIBUTING.md +++ b/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 diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index c5592c1f693..0e96d58a3c9 100644 --- a/DEVELOPMENT.md +++ b/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)._ diff --git a/README.md b/README.md index b471e9e4a61..1cc5bb02cbe 100644 --- a/README.md +++ b/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! diff --git a/api_compatibility_policy.md b/api_compatibility_policy.md new file mode 100644 index 00000000000..a7dbcc31e0f --- /dev/null +++ b/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`.