api: initial STYLE.md. (#392)

This is intended to capture some recent threads, it can grow as we learn
new lessons.

Signed-off-by: Harvey Tuch <htuch@google.com>

Signed-off-by: Harvey Tuch <htuch@google.com>

* Fix format.

Signed-off-by: Harvey Tuch <htuch@google.com>

API_OVERVIEW.md

@@ -72,11 +72,6 @@ for the v2 API change process.
 * Custom components (e.g. filters, resolvers, loggers) will use a reverse DNS naming scheme,
   e.g. `com.google.widget`, `com.lyft.widget`.
 
-* [Wrapped](https://github.com/google/protobuf/blob/master/src/google/protobuf/wrappers.proto)
-  protobuf fields should be used for all non-string [scalar
-  types](https://developers.google.com/protocol-buffers/docs/proto3#scalar)
-  where non-zero default values are needed.
-
 ## APIs
 
 Unless otherwise stated, the APIs with the same names as v1 APIs have a similar role.

CONTRIBUTING.md

@@ -2,6 +2,8 @@
 
 ## API changes
 
+All API changes should follow the [style guide](STYLE.md).
+
 The following high level procedure is used to make Envoy changes that require API changes.
 
 1. Create a PR in this repo for the API/configuration changes. (If it helps to discuss the

STYLE.md

@@ -0,0 +1,45 @@
+# API style guidelines
+
+Generally follow guidance at https://cloud.google.com/apis/design/, in
+particular for proto3 as described at:
+
+* https://cloud.google.com/apis/design/proto3
+* https://cloud.google.com/apis/design/naming_convention
+* https://developers.google.com/protocol-buffers/docs/style
+
+In addition, the following conventions should be followed:
+
+* The data plane APIs are primarily intended for machine generation and consumption.
+  It is expected that the management server is responsible for mapping higher
+  level configuration concepts to concrete API concepts. Similarly, static configuration
+  fragments may be generated by tools and UIs, etc. The APIs and tools used
+  to generate xDS configuration are beyond the scope of the definitions in this
+  repository.
+
+* Use [wrapped scalar
+  types](https://github.com/google/protobuf/blob/master/src/google/protobuf/wrappers.proto)
+  where there is a real need for the field to have a default value that does not
+  match the proto3 default (0/false/""). This should not be done for fields
+  where the proto3 defaults make sense. All things being equal, pick appropriate
+  logic, e.g. enable vs. disable for a `bool` field, such that the proto3
+  defaults work, but only where this doesn't result in API gymnastics.
+
+* Always use plural field names for `repeated` fields.
+
+* Prefer `oneof` selections to boolean overloads of fields, for example, prefer:
+
+  ```proto
+  oneof path_secifier {
+    string simple_path = 1;
+    string regex_path = 2;
+  }
+  ```
+
+  to
+
+  ```proto
+  string path = 1;
+  bool path_is_regex = 2;
+  ```
+
+  This is more efficient, extendable and self-describing.