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.
The use of
GA in this document is meant to correspond
the kubernetes API deprecation policies.
What is the API?
The API is considered to consist of:
- The structure of the CRDs including the
statussections, as well as:
- The ordering of the
- The naming of the
stepcontainers within the
- The labels propagated from
- The ordering of the
- The structure of the directories created in executing containers by Tekton
- The order that
PipelineResourcesdeclared within a
Taskare applied in
- The interfaces of the images that are built as part of Tekton Pipelines, i.e. images in cmd which are used as part of PipelineResources
This policy is about changes to any of the above facets of the API.
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 and/or cause them to change their CRD definitions to account for changes in the above.
Alpha, Beta and GA
Some of our CRDs and features are considered alpha, some are beta, and we are working toward GA.
The following CRDs are considered beta, though features may be introduced that are alpha:
- These features may be dropped at any time, though you will be given at least one release worth of warning.
- These features will not be dropped, though the details may change.
- Any backwards incompatible changes must be introduced in a backwards compatible manner first, with a deprecation warning in the release notes and migration instructions.
- You will be given at least 9 months to migrate before a backward incompatible change is made. This means an older beta API version will continue to be supported in new releases for a period of at least 9 months from the time a newer version is made available.
Approving API changes
Additive changes are changes that add to the API and do not cause problems for users of previous versions of the API.
These changes must be approved by at least 2 OWNERS.
Backwards incompatible changes
Backwards incompatible changes change the API, e.g. by removing fields from a CRD spec. These changes will mean that folks using a previous version of the API will need to adjust their usage in order to use the new version.
These changes must be approved by more than half of the project OWNERS (i.e. 50% + 1).
Tekton Pipelines maintains a list of features that have been deprecated which includes the earliest date each feature will be removed.