Add compatibility guidelines for Go library

This commit updates the Go library compatibility policy with guidelines for Go
client libraries for a particular CRD version. The guidelines are based on the
discussions in tektoncd#5634, tektoncd#2748, and in the API WG on Oct 10, 2022.

Co-authored-by: Lee Bernick <[email protected]>
Signed-off-by: Dibyo Mukherjee <[email protected]>

api_compatibility_policy.md

@@ -110,11 +110,11 @@ See the current list of [alpha features](https://github.com/tektoncd/pipeline/bl
 
 ### GA/Stable features
 
-- GA/Stable features are present in a [GA CRD](#ga-crds) only.
+- GA/Stable features are present in a [GA CRD](#ga-crds) only
 
 - GA/Stable features are enabled by default
 
-- GA/Stable features will not be removed or changed in a backwards incompatible manner.
+- GA/Stable features will not be removed or changed in a backwards incompatible manner without incrementing  the API version
 
 ## Approving API changes
 
@@ -146,9 +146,16 @@ These changes must be approved by [more than half of the project OWNERS](OWNERS)
 Tekton Pipelines [maintains a list of features that have been deprecated](https://github.com/tektoncd/pipeline/tree/main/docs/deprecations.md)
 which includes the earliest date each feature will be removed.
 
-## Go libraries compatibility policy
+## Go Libraries
 
-Tekton Pipelines may introduce breaking changes to its Go client libraries, as long as these changes
-do not impact users' yaml/json CRD definitions. For example, a change that renames a field of a CRD
-would need to follow the policy on [backwards incompatible changes](#backwards-incompatible-changes),
-but a change that renames the Go struct type for that field is allowed.
+The following guidelines describe backwards incompatible changes and how they relate to release versioning for the public Go packages under `github.com/tektoncd/pipeline/pkg`.
+
+Packages that are part of the Go client library for a particular CRD version should adhere to the stability guarantees for that version. This includes the Go structs for the API types in `pkg/apis/pipeline/$apiVersion` and the client libraries generated from those in `pkg/client`. This means:
+
+- Changing or removing a field in a go struct in `pkg/apis/pipeline/v1alpha1` (or another alpha API) is not considered a backwards incompatible change.
+
+- Renaming a field in `pkg/apis/pipeline/v1beta1` (or another beta API) is not considered a backwards incompatible change. However, removing a field is considered a backwards incompatible change and requires a major version bump.
+
+- For `pkg/apis/pipeline/v1` (or any other stable APIs), any [backwards incompatible change](https://go.dev/blog/module-compatibility) will require a major version bump.
+
+For other packages, backwards incompatible changes are discouraged but they do not require a major version bump as long as they do not impact a user's YAML/JSON resource definitions.