From 2ab8571056176f29ee241808ff7cf4e391538567 Mon Sep 17 00:00:00 2001 From: Lee Bernick Date: Thu, 20 Apr 2023 09:38:49 -0400 Subject: [PATCH] Add developer guidance for API changes to CustomRuns CustomRun is different from other Tekton APIs because its API is implemented by custom run controllers, rather than in-tree controllers. Therefore, adding new fields to this API should be done with extra caution. This commit adds guidance for Tekton devs on whether a new field should go in the CustomRun API or left to custom run controllers to support as part of the custom spec or custom status, based on whether a feature is applicable to all CustomRuns or just a feature of some of them. --- api_compatibility_policy.md | 2 +- docs/developers/{deprecations.md => api-changes.md} | 11 ++++++++++- 2 files changed, 11 insertions(+), 2 deletions(-) rename docs/developers/{deprecations.md => api-changes.md} (90%) diff --git a/api_compatibility_policy.md b/api_compatibility_policy.md index 5c5741d169a..f77dc800923 100644 --- a/api_compatibility_policy.md +++ b/api_compatibility_policy.md @@ -155,4 +155,4 @@ but a change that renames the Go struct type for that field is allowed. ## Notes for Developers Are you a Tekton contributor looking to make a backwards incompatible change? -Read more on additional considerations at [deprecations.md](./docs/developers/deprecations.md). \ No newline at end of file +Read more on additional considerations at [api-changes.md](./docs/developers/api-changes.md#deprecations). \ No newline at end of file diff --git a/docs/developers/deprecations.md b/docs/developers/api-changes.md similarity index 90% rename from docs/developers/deprecations.md rename to docs/developers/api-changes.md index 70ce83166b0..58fe6ce038d 100644 --- a/docs/developers/deprecations.md +++ b/docs/developers/api-changes.md @@ -1,8 +1,17 @@ -# Deprecations +# API Changes ✋ Before reading this, please read the [API Compatibility Policy](../../api_compatibility_policy.md) +## CustomRuns + +Before adding an optional field to the spec or status of `CustomRun`, +consider whether it could be part of the custom spec or custom status instead. +New fields should be added to the spec or status of the `CustomRun` API only if they +make sense for all custom run controllers to support. + +## Deprecations + The following are things developers should keep in mind for deprecations. These tips may not apply in every case, so use your best judgement! If you're not sure how these affect your deprecation or timeline, ask the maintainers.