Skip to content

Latest commit

 

History

History
77 lines (53 loc) · 3.08 KB

api_compatibility_policy.md

File metadata and controls

77 lines (53 loc) · 3.08 KB
Raw

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 two groups:

  • [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.

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:

  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

TODO(bobcatfish): This policy really should include the entire API.

The API is considered to consist of:

  • The spec if the CRDs
  • The order that PipelineResources declared within a Task are applied in

Getting to beta

This document (visible to members of the mailing list) describes our plan to get to beta.

Backwards compatible changes first

At this point, 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.

Approving API changes

API changes must be approved by OWNERS. The policy is slightly different for additive changes vs. backwards incompatible changes.

Additive 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 made in a backwards compatible manner first, and the changes must be approved by more than half of the project OWNERS (i.e. 50% + 1).