Merge remote-tracking branch 'upstream/main' into yft/arrays

CODE_OF_CONDUCT.md

@@ -0,0 +1,93 @@
+## Community Code of Conduct
+
+As contributors, maintainers, and participants in our community, and in the
+interest of fostering an open and welcoming community, we pledge to respect all
+people who participate or contribute through reporting issues, posting feature
+requests, updating documentation, submitting pull requests or patches,
+attending conferences or events, or engaging in other community or project
+activities.
+
+We are committed to making participation in our community a harassment-free
+experience for everyone, regardless of age, body size, caste, disability,
+ethnicity, level of experience, family status, gender, gender identity and
+expression, marital status, military or veteran status, nationality, personal
+appearance, race, religion, sexual orientation, socioeconomic status, tribe, or
+any other dimension of diversity.
+
+## Scope
+
+This code of conduct applies:
+
+- within project and community spaces,
+- in other spaces when an individual community participant's words or actions
+  are directed at or are about a project, our community, or another community
+  participant.
+
+## Our Standards
+
+Our Community is open, inclusive and respectful. Every member of our community
+has the right to have their identity respected.
+
+Examples of behavior that contributes to a positive environment include but are
+not limited to:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+- Focusing on what is best not just for us as individuals, but for the overall
+  community
+- Using welcoming and inclusive language
+
+Examples of unacceptable behavior include but are not limited to:
+
+- The use of sexualized language or imagery
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment in any form
+- Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+- Violence, threatening violence, or encouraging others to engage in violent
+  behavior
+- Stalking or following someone without their consent
+- Unwelcome physical contact
+- Unwelcome sexual or romantic attention or advances
+- Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+The following behaviors are also prohibited:
+
+- Providing knowingly false or misleading information in connection with a Code
+  of Conduct investigation or otherwise intentionally tampering with an
+  investigation.
+- Retaliating against a person because they reported an incident or provided
+  information about an incident as a witness.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct. By adopting this Code of Conduct,
+project maintainers commit themselves to fairly and consistently applying these
+principles to every aspect of managing a project. Project maintainers who do
+not follow or enforce the Code of Conduct may be temporarily or permanently
+removed from the project team.
+
+## Reporting
+
+For incidents occurring in our community, please contact any of the individual
+maintainers of the GitHub organization or Slack workspace.
+
+## Enforcement
+
+Upon review and investigation of a reported incident, the AEP maintainers that
+has jurisdiction will determine what action is appropriate based on this Code
+of Conduct and its related documentation.
+
+## Acknowledgements
+
+This code of conduct is based on and consistent with the [CNCF Community Code
+of Conduct v1.3], which is adapted from the Contributor Covenant
+(http://contributor-covenant.org), version 2.0 available at
+http://contributor-covenant.org/version/2/0/code_of_conduct/
+
+[CNCF Community Code of Conduct v1.3]:
+  https://github.com/cncf/foundation/blob/main/code-of-conduct.md

README.md

@@ -18,7 +18,7 @@ following channels of communication are available:
 
 - [The #aep channel in the CNCF Slack](https://cloud-native.slack.com/archives/C04TX46UCTV).
   Sign up at https://slack.cncf.io.
-- [The AEP Google Calendar, to view any upcoming meetings](https://calendar.google.com/calendar/u/0?cid=N2UzNWRkM2RmMTk0YTMyZjRmYTdjMDNhMzQ1NGUyNGJhMzY1MWU2ZjU2ODI0OGVmZTFkZGYxZTM0YTdiZWU5ZUBncm91cC5jYWxlbmRhci5nb29nbGUuY29t).
+- [The AEP Google Calendar, to view any upcoming meetings](https://calendar.google.com/calendar?cid=N2UzNWRkM2RmMTk0YTMyZjRmYTdjMDNhMzQ1NGUyNGJhMzY1MWU2ZjU2ODI0OGVmZTFkZGYxZTM0YTdiZWU5ZUBncm91cC5jYWxlbmRhci5nb29nbGUuY29t).
   - A weekly project meeting is held, which anyone interested is welcome to
     attend!
 

aep/general/0003/aep.md.j2

@@ -99,6 +99,12 @@ Examples of complexities that declarative clients abstract away include:
 
 [Terraform][] is an example of such a client.
 
+### Schema
+
+A schema describes the structure of the request or response of an [API
+method](#api-method), or a [resource](#api-resource). It refers both to an
+OpenAPI schema as well as a protobuf message.
+
 ### User
 
 A human being which is using an API directly, such as with cURL. This term is

aep/general/0157/aep.md.j2

@@ -1,5 +1,91 @@
 # Partial responses
 
-**Note:** This AEP has not yet been adopted. See
-[this GitHub issue](https://github.com/aep-dev/aep.dev/issues/11) for more
-information.
+Sometimes, a resource can be either large or expensive to compute, and the API
+needs to give the user control over which fields it sends back.
+
+## Guidance
+
+APIs **may** support partial responses in one of two ways:
+
+### Field masks parameter
+
+Field masks (`google.protobuf.FieldMask`) can be used for granting the user
+fine-grained control over what fields are returned. An API **should** support
+the mask in a side channel. For example, the parameter can be specified either
+using an HTTP query parameter, an HTTP header, or a [gRPC metadata entry][].
+
+Field masks **should not** be specified in the
+[request](./0157.md#read-masks-as-a-request-field).
+
+- The value of the field mask parameter **must** be a
+  `google.protobuf.FieldMask`.
+- The field mask parameter **must** be optional:
+  - An explicit value of `"*"` **should** be supported, and **must** return all
+    fields.
+  - If the field mask parameter is omitted, it **must** default to `"*"`,
+    unless otherwise documented.
+- An API **may** allow read masks with non-terminal repeated fields (unlike
+  update masks), but is not obligated to do so.
+
+  **Warning:** There is a known conflict between this guidance and the
+  documentation of `FieldMask` itself:
+  [google/protobuf/field_mask.proto](https://github.com/protocolbuffers/protobuf/blob/5e84a6169cf0f9716c9285c95c860bcb355dbdc1/src/google/protobuf/field_mask.proto#L85-L86)
+  states that
+  `A repeated field is not allowed except at the last position of a paths string.`
+  As such, official libraries (such as `Merge` for FieldMasks) may not support
+  wildcards without additional work. Track the issue
+  [here](https://github.com/protocolbuffers/protobuf/issues/8547#issuecomment-2005180068).
+  Consider using the view enumeration pattern described below instead instead.
+
+**Note:** Changing the default value of the field mask parameter is a
+[breaking change](./backwards-compatibility#semantic-changes).
+
+### View enumeration
+
+Alternatively, an API **may** support partial responses with view enums. View
+enums are useful for situations where an API only wants to expose a small
+number of permutations to the user:
+
+```proto
+enum BookView {
+  // The default / unset value.
+  // The API will default to the BASIC view.
+  BOOK_VIEW_UNSPECIFIED = 0;
+
+  // Include basic metadata about the book, but not the full contents.
+  // This is the default value (for both ListBooks and GetBook).
+  BOOK_VIEW_BASIC = 1;
+
+  // Include everything.
+  BOOK_VIEW_FULL = 2;
+}
+```
+
+- The enum **should** be specified as a `view` field on the request message.
+- The enum **should** be named something ending in `-View`
+- The enum **should** at minimum have values named `BASIC` and `FULL` (although
+  it **may** have values other than these).
+- The `UNSPECIFIED` value **must** be valid (not an error), and the API
+  **must** document what the unspecified value will do.
+  - For List RPCs, the effective default value **should** be `BASIC`.
+  - For Get RPCs, the effective default value **should** be either `BASIC` or
+    `FULL`.
+- The enum **should** be defined at the top level of the proto file (as it is
+  likely to be needed in multiple requests, e.g. both `Get` and `List`). See
+  [enumerations](./enumerations) for more guidance on top-level enumerations.
+- APIs **may** add fields to a given view over time. APIs **must not** remove a
+  field from a given view (this is a breaking change).
+
+  **Note:** If a service requires (or might require) multiple views with
+  overlapping but distinct values, there is a potential for a namespace
+  conflict. In this situation, the service **should** nest the view enum within
+  the individual resource.
+
+### Read masks as a request field
+
+**Warning:** Read masks as a single field on the request message, for example:
+`google.protobuf.FieldMask read_mask` are **DEPRECATED**.
+
+<!-- prettier-ignore-start -->
+[gRPC metadata entry]: https://grpc.io/docs/what-is-grpc/core-concepts/#metadata
+<!-- prettier-ignore-end -->

aep/general/0157/aep.yaml

@@ -1,6 +1,6 @@
 ---
 id: 157
-state: reviewing
+state: approved
 slug: partial-responses
 created: 2023-01-22
 placement: