From 6e11b60f35fc9508ba0f8b9e567c65f12759476b Mon Sep 17 00:00:00 2001 From: Christie Wilson Date: Thu, 8 Aug 2019 10:53:30 -0700 Subject: [PATCH] =?UTF-8?q?Document=20API=20change=20policy=20=F0=9F=91=A9?= =?UTF-8?q?=20=E2=9A=96=EF=B8=8F?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This commit adds docs about the policy the current governing board has been discussing around how to handle API changes and make sure they are reviewed by the ppl that should review them. We can adjust this policy as needed, e.g. if we start running into situations where not enough owners can review within a reasonable amount of time. Also added links to the doc where we are working on our plan to get to Beta and updated our docs about this. Fixes #906 --- .github/pull_request_template.md | 10 ++++++ CONTRIBUTING.md | 1 + api_compatibility_policy.md | 56 +++++++++++++------------------- 3 files changed, 34 insertions(+), 33 deletions(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index bb1deaef392..7292a1fa1e3 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -21,6 +21,16 @@ Double check this list of stuff that's easy to miss: - If you are adding [a new binary/image to the `cmd` dir](../cmd), please update [the release Task](../tekton/publish.yaml) and [TaskRun](../tekton/publish-run.yaml) to build and release this image +## Reviewer Notes + +If [API changes](https://github.com/tektoncd/pipeline/blob/master/api_compatibility_policy.md) +are included, [additive changes](https://github.com/tektoncd/pipeline/blob/master/api_compatibility_policy.md#additive-changes) +must be approved by at least two [OWNERS](https://github.com/tektoncd/pipeline/blob/master/OWNERS) +and [backwards incompatible changes](https://github.com/tektoncd/pipeline/blob/master/api_compatibility_policy.md#backwards-incompatible-changes) +must be approved by [more than 50% of the OWNERS](https://github.com/tektoncd/pipeline/blob/master/OWNERS), +and they must first be added +[in a backwards compatible way](https://github.com/tektoncd/pipeline/blob/master/api_compatibility_policy.md#backwards-compatible-changes-first). + # Release Notes ``` diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 20ed83b77a1..10ca872a87e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -24,6 +24,7 @@ on: [reviews](https://github.com/tektoncd/community/blob/master/process.md#reviews) and [becoming an OWNER](https://github.com/tektoncd/community/blob/master/process.md#owners) +- [Making API changes](api_compatibility_policy.md#approving-api-changes) You can find details on our automation infrastructure in [the plumbing repo](https://github.com/tektoncd/plumbing). diff --git a/api_compatibility_policy.md b/api_compatibility_policy.md index 3ab9a35f3f6..18a5097838d 100644 --- a/api_compatibility_policy.md +++ b/api_compatibility_policy.md @@ -40,48 +40,38 @@ The API is considered to consist of: - The spec if the CRDs - The order that `PipelineResources` declared within a `Task` are applied in -## `TaskRun`, `Task`, and `ClusterTask` +### Getting to beta -The CRD types -[`Task`](https://github.com/tektoncd/pipeline/blob/master/docs/tasks.md), -[`ClusterTask`](https://github.com/tektoncd/pipeline/blob/master/docs/tasks.md#clustertask), -and -[`TaskRun`](https://github.com/tektoncd/pipeline/blob/master/docs/taskruns.md) -should be considered `alpha`, however these types are more stable than -`Pipeline`, `PipelineRun`, and `PipelineResource`. +[This document](https://docs.google.com/document/d/1H8I2Rk4kLdQaR4mV0A71Qbk-1FxXFrmvisEAjLKT6H0/edit#) +(visible to members of [the mailing list](https://github.com/tektoncd/community/blob/master/contact.md#mailing-list)) +describes our plan to get to beta. -### Possibly `beta` in 0.3 +#### Backwards compatible changes first -The status of these types will be revisited ~2 releases (i.e. 0.3) and see if -they can be promoted to `beta`. - -Once these types are promoted to `beta`, any backwards incompatible changes must +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. -There are two reasons for this: +## Approving API changes + +API changes must be approved by [OWNERS](OWNERS). The policy is slightly different +for [additive changes](#additive-changes) vs. +[backwards incompatible changes](#backwards-incompatible-changes). + +### Additive changes -- `Task` and `TaskRun` are considered upgraded versions of [Build](https://github.com/knative/docs/blob/master/docs/build/builds.md#source) and [BuildTemplate](https://github.com/knative/docs/blob/master/docs/build/build-templates.md), 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 +Additive changes are changes that add to the API and do not cause problems for users +of previous versions of the API. -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. +These changes must be approved by at least 2 [OWNERS](OWNERS). -## `PipelineRun`, `Pipeline` and `PipelineResource` +### Backwards incompatible changes -The CRD types -[`Pipeline`](https://github.com/tektoncd/pipeline/blob/master/docs/pipelines.md), -[`PipelineRun`](https://github.com/tektoncd/pipeline/blob/master/docs/pipelines.md) -and -[`PipelineResource`](https://github.com/tektoncd/pipeline/blob/master/docs/resources.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. +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. -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`. +These changes must be make [in a backwards compatible manner first](#backwards-compatible-changes-first), +and they must be improved by [more than half of the project OWNERS](OWNERS) +(i.e. 50% + 1). \ No newline at end of file