feat(AIP-148): move annotations from AIP-128 (#1183)

consolidating standard fields to make them more discoverable.

fixes #1082

Author: toumorokoshi

aip/general/0128.md

@@ -49,24 +49,6 @@ message Book {
 }
 ```
 
-### Annotations
-
-Declarative-friendly resources **must** include a
-`map<string, string> annotations` field to allow clients to store small amounts
-of arbitrary data.
-
-The `annotations` field **must** use the [Kubernetes limits][] to maintain wire
-compatibility, and **should** require dot-namespaced annotation keys to prevent
-tools from trampling over one another.
-
-**Note:** Annotations are distinct from various forms of labels. Labels can be
-used by server-side policies, such as IAM conditions. Annotations exist to
-allow client tools to store their own state information without requiring a
-database.
-
-<!-- prettier-ignore -->
-[kubernetes limits]: https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/#syntax-and-character-set
-
 ### Reconciliation
 
 If a resource takes time (more than a few seconds) for updates to be realized,
@@ -95,8 +77,16 @@ is a comprehensive reference to declarative-friendly guidance in other AIPs:
 - Resources **should not** implement soft-delete. If the id cannot be re-used,
   the resource **must** implement soft-delete and the undelete RPC: see AIP-164
 
+
+### Annotations
+
+See [AIP-148 annotations]().
+
 ## Changelog
 
+- **2023-07-13**: Move `annotations` from AIP-148.
 - **2023-06-17**: Definition of plane was removed and incorporated into AIP-111.
 - **2023-05-11**: Removed must on resource_id, which was upstreamed to a general
-  must.
+  must.
+
+[AIP-148 annotations]: ./0148.md#annotations

aip/general/0148.md

@@ -118,6 +118,26 @@ Resources that support soft delete **should** include this field.
 Services **may** provide a `purge_time` value that is inexact, but the resource
 **must not** be purged from the system before that time.
 
+### Annotations
+
+To store small amounts of arbitrary data, a `map<string, string> annotations`
+field **may** be added.
+
+The `annotations` field **must** use the [Kubernetes limits][] to maintain wire
+compatibility, and **should** require dot-namespaced annotation keys to prevent
+tools from trampling over one another.
+
+Examples of information that might be valuable to store in annotations include:
+
+- For CI/CD, an identifier of the pipeline run or version control identifier
+  used to propagate.
+
+**Note:** Annotations are distinct from various forms of labels. Labels can be
+used by server-side policies, such as IAM conditions. Annotations exist to
+allow client tools to store their own state information without requiring a
+database.
+
+
 ## Further reading
 
 - For standardized codes, see AIP-143.
@@ -135,8 +155,11 @@ Before 2023-07, `purge_time` for soft-deleted resources was also called
 
 ## Changelog
 
+- **2023-08-14**: Introduce the term `annotations` from AIP-128.
 - **2023-07-13**: Introduce the term `purge_time`.
 - **2021-04-06**: Require output only field behavior for `uid` and `delete_time`
   fields.
 
+<!-- prettier-ignore -->
 [declarative-friendly resources]: ./0128.md#resources
+[kubernetes limits]: https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/#syntax-and-character-set