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:
BuildTemplate] - from https://github.com/knative/build
ClusterTask] - "more stable"
PipelineResource] - "less stable"
The use of
GA in this document is meant to correspond
the kubernetes API deprecation policies.
What does compatibility mean here?
This policy is about changes to the APIs of the CRDs, 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 this process may become less painful).
The current process would look something like:
- Backup the instances
- Delete the instances
- Deploy the new type definitions
- Update the backups with the new spec
- 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).
Support will continue for the
Build type for the foreseeable future,
particularly to support embedding of Build resources within
beta in 0.3
The status of these types will be revisited ~2 releases (i.e. 0.3) and see if
they can be promoted to
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:
TaskRunare considered upgraded versions of
Build, meaning that the APIs benefit from a significant amount of user feedback and iteration
- Going forward users should use
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
The CRD types
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