Clarify the API compatibility policy and improve the deprecations table.

In discussion around tektoncd#2697, we realized the existing API compatiblity
policy is a little unclear, leading to confusion.
We discussed and clarified the intentions of this policy in tektoncd#2790.
This change adds an example to the policy, and tweaks the deprecations
table to make a bit more sense.

Fixes tektoncd#2790

api_compatibility_policy.md

@@ -55,7 +55,9 @@ and we are following [the Kubernetes deprecation policy](https://kubernetes.io/d
     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.
+    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
 

docs/deprecations.md

@@ -18,7 +18,7 @@ being deprecated.
 
 ## Deprecation Table
 
-| Feature Being Deprecated | Deprecation Announcement | [API Compatibility Policy](https://github.com/tektoncd/pipeline/tree/master/api_compatibility_policy.md) | Earliest Date of Removal |
+| Feature Being Deprecated | Deprecation Announcement | [API Compatibility Policy](https://github.com/tektoncd/pipeline/tree/master/api_compatibility_policy.md) | Earliest Date or Release of Removal |
 | ------------------------ | ------------------------ | -------------------------------------------------------------------------------------------------------- | ------------------------ |
 | [`tekton.dev/task` label on ClusterTasks](https://github.com/tektoncd/pipeline/issues/2533) | [v0.12.0](https://github.com/tektoncd/pipeline/releases/tag/v0.12.0) | Beta | January 30 2021 |
 | [Step `$HOME` env var defaults to `/tekton/home`](https://github.com/tektoncd/pipeline/issues/2013) | [v0.11.0-rc1](https://github.com/tektoncd/pipeline/releases/tag/v0.11.0-rc1) | Beta | December 4 2020 |