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

@@ -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).
+Read more on additional considerations at [api-changes.md](./docs/developers/api-changes.md#deprecations).

docs/developers/deprecations.md → 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.