style: recent lessons learned on package namespace moves. (#439)

* style: recent lessons learned on package namespace moves.

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

STYLE.md

@@ -14,10 +14,6 @@ In addition, the following conventions should be followed:
 
   * Fields should not be renumbered or have their types changed. This is standard proto development
     procedure.
-  * Fields should not be **renamed**. This is stricter than standard proto development procedure
-    in the sense that it does not break binary wire format. However, it **does** break loading
-    of YAML/JSON into protos as well as text protos. Since we consider YAML/JSON to be first class
-    inputs, we must not change field names.
   * If fields are deleted, the following syntax should be put in their place:
 
   ```proto
@@ -30,6 +26,27 @@ In addition, the following conventions should be followed:
   reserved 15;
   ```
 
+  * Renaming of fields or package namespaces for a proto must not occur. This is inherently dangerous, since:
+    * Fields renames break wire compatibility. This is stricter than standard proto development procedure
+      in the sense that it does not break binary wire format. However, it **does** break loading
+      of YAML/JSON into protos as well as text protos. Since we consider YAML/JSON to be first class
+      inputs, we must not change field names.
+
+    * For service definitions, the gRPC endpoint URL is inferred from package
+      namespace, so this will break client/server communication.
+
+    * For a message embedded in an `Any` object, the type URL, which the package
+      namespace is a part of, may be used by Envoy or other API consuming code.
+      Currently, this applies to the top-level resources embedded in
+      `DiscoveryResponse` objects, e.g. `Cluster`, `Listener`, etc.
+
+    * Consuming code will break and require source change to match the changes.
+
+* Non-frozen fields should be tagged with `[#not-implemented-hide:]`, `[#not-implemented-warn:]`,  `[#proto-status: draft]` or `[#proto-status: experimental]`.
+
+* Every proto directory should have a `README.md` describing its content. See
+  for example [envoy.service](envoy/service/README.md).
+
 * 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

envoy/api/v2/README.md

@@ -0,0 +1 @@
+Protocol buffer definitions for core API messages.

envoy/api/v2/filter/README.md

@@ -1,3 +1,5 @@
+Protocol buffer definitions for filters.
+
 ## NOTE
 
 If a filter configuration is not captured in the proto specification, you

envoy/config/README.md

@@ -0,0 +1 @@
+Protocol buffer definitions for Envoy's bootstrap and service configuration.

envoy/service/README.md

@@ -0,0 +1 @@
+Protocol buffer definitions for gRPC and REST services.