fix(AIP-128): clarify usage of annotations field for Declarative-friendly resources

[amirkaromashkin]

In #1183, guide was moved from AIP-128 to AIP-148.
As a result, the information whether Declarative-friendly interfaces must include annotations field was lost.
This PR or related issue do not justify the reason of recommendation change, therefore I consider it as a bug.

This change returns the recommendation to the one before the change and puts it in both AIP-128 and AIP-148

[yordis]

Would you say that this field has a similar intent as https://stripe.com/docs/api/metadata

Useful for correlation or putting extra metadata that could be used late.

[bgrant0607]

They are intended to have the same purpose as https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/

[amirkaromashkin]

I can only agree with both comments above :)

[yordis]

I understand the usage of annotations in the context of Kubernetes, but I am trying to find the usefulness from the AIP perspective outside that given Domain.

It should be a less technical-focused product and more general in the public domain (fintech, education, etc.).

Related to #1288 (comment)

The topic of transient data and/or user-controlled (external clients own the data) instead of system-controlled (internal to systems, not intended outside programmers that own the system).

The AIPs can clarify and help with the decision-making here.

[bgrant0607]

The intent of moving annotations to AIP 148 was that all resource types should support annotations.

[amirkaromashkin]

The intent of moving annotations to AIP 148 was that all resource types should support annotations.

Yes, and since #1183, annotations may be added to all resources.

Current PR does not touch this part of the recommendation, but returns a must recommendation for Declarative-friendly resources.