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.

[Ark-kun]

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

However the implementation did the exact opposite. It removed the requirement to have annotations by replacing "must" with "may".

I think this is a regression and needs to be fixed.

[Ark-kun]

@bgrant0607 Can you please approve this PR and fix this issue.

I needed to internally link to the annotations field requirement and just found out that this information was deleted and neutered.