feat(AIP-203): document field behavior compatibility (#1172)

Author: noahdietz

aip/general/0134.md

@@ -284,6 +284,7 @@ does not exist, the service **must** error with `NOT_FOUND` (HTTP 404) unless
 
 ## Changelog
 
+- **2023-07-17**: Make `update_mask` name guidance a **must**.
 - **2022-11-04**: Aggregated error guidance to AIP-193.
 - **2022-06-02**: Changed suffix descriptions to eliminate superfluous "-".
 - **2021-11-04**: Changed the permission check if `allow_missing` is set.

aip/general/0161.md

@@ -146,3 +146,7 @@ service considers invalid).
 When writing data, field masks **should** return an `INVALID_ARGUMENT` error if
 an entry points to a value that can not exist; however, the service **may**
 permit deletions.
+
+## Changelog
+
+- **2023-07-17**: Move `update_mask` guidance to AIP-134.

aip/general/0180.md

@@ -235,6 +235,7 @@ version.
 
 ## Further reading
 
+- For compatibility around field behavior, see [AIP-203][].
 - For compatibility around pagination, see [AIP-158][].
 - For compatibility around long-running operations, see [AIP-151][].
 - For understanding stability levels and expectations, see [AIP-181][].
@@ -243,6 +244,7 @@ version.
 
 ## Changelog
 
+- **2023-07-26**: Added reference to field behavior compatibility.
 - **2023-07-26**: Added note on APIs which have limited clients.
 - **2022-08-11**: Added "Moving components between files" section.
 - **2022-06-01**: Added more links to other AIPs with compatibility concerns
@@ -254,6 +256,7 @@ version.
 [aip-151]: ./0151.md
 [aip-158]: ./0158.md
 [aip-181]: ./0181.md
+[aip-203]: ./0203.md
 [aip-4231]: ./client-libraries/4231.md
 [aip-4232]: ./client-libraries/4232.md
 [ec2]: https://aws.amazon.com/blogs/aws/theyre-here-longer-ec2-resource-ids-now-available/

aip/general/0203.md

@@ -161,6 +161,29 @@ the user's behalf.
 A resource with an unordered list **may** return the list in a stable order, or
 **may** return the list in a randomized, unstable order.
 
+## Backwards compatibility
+
+Adding or changing `google.api.field_behavior` values can represent a semantic
+change in the API that is perceived as incompatible for existing clients. The
+following are examples of backwards incompatible changes with
+`google.api.field_behavior`:
+
+* Adding `REQUIRED` to an existing field previously considered `OPTIONAL`
+(implicitly or otherwise).
+* Adding a new field annotated as `REQUIRED` to an existing request message.
+* Adding `OUTPUT_ONLY` to an existing field previously accepted as input
+* Removing `OUTPUT_ONLY` from an existing field previously ignored as input
+* Adding `INPUT_ONLY` to an existing field previously emitted as output
+* Adding `IMMUTABLE` to an existing field previously considered mutable
+
+There are some changes that *are* backwards compatible, which are as follows:
+
+* Adding `OPTIONAL` to an existing field
+* Changing from `REQUIRED` to `OPTIONAL` on an existing field
+* Removing `REQUIRED` from an existing field
+* Removing `INPUT_ONLY` from an existing field previously excluded in responses
+* Removing `IMMUTABLE` from an existing field previously considered immutable
+
 ## Rationale
 
 ### Required set of annotations
@@ -181,29 +204,34 @@ behavior improves programmatic clients and user understanding.
 Requiring the annotation also forces the API author to explicitly consider the
 behavior when initially authoring of the API.
 
-Modifying field behavior after initial authoring results in
+Modifying field behavior after initial authoring can result in
 backwards-incompatible changes in clients. For example, making an optional field
-required, results in backwards-incompatible changes in the method signature of
-an RPC or a resource in an [IaC][] client.
+required results in backwards-incompatible changes in the method signature of an
+RPC or a resource in an [IaC][] client. See the
+[Backwards compatibility](#backwards-compatibility) section for more detailed
+compatibility guidance.
 
 ## History
 
 In 2023-05 field_behavior was made mandatory. Prior to this change, the
-annotation was often omitted. Its values, e.g. REQUIRED, OUTPUT_ONLY, and
-IMMUTABLE, are relied upon to produce high quality clients. Further, when the
-value is added after the fact or changes, within a major version, it is
-backwards-incompatible, which is likely to break clients.
+annotation was often omitted. Its values are relied upon to produce high quality
+clients. Furthermore, adding or changing some of the field_behavior values after
+the fact within a major version can be backwards-incompatible. See the
+[Backwards compatibility](#backwards-compatibility) section for more detailed
+compatibility guidance.
 
-The benefits of requiring field_behavior, at the time that the API is authored,
+The benefits of requiring field_behavior at the time that the API is authored
 surpass the costs to clients and API users of not doing so.
 
 [aip-133]: ./0133.md
 [aip-134]: ./0134.md
+[aip-180]: ./0180.md
 [google.api.FieldBehavior]: https://github.com/googleapis/googleapis/blob/master/google/api/field_behavior.proto#L49
 [IaC]: ./0009.md#iac
 
 ## Changelog
 
+- **2023-07-20**: Describe compatibility guidance with new section.
 - **2023-05-24**: Clarify that `IMMUTABLE` does not imply input nor required.
 - **2023-05-10**: Added guidance to require the annotation.
 - **2020-12-15**: Added guidance for `UNORDERED_LIST`.