feat(AIP-180): describe default breaking changes (#1076)

Add specific examples of breaking semantic changes for default values & serialization of default values

Author: slevenick

aip/general/0180.md

@@ -139,6 +139,93 @@ code, as such changes will be seen as breaking by those users.
 whether a proposed change is likely to break users, and an expansive reading of
 this guidance could ostensibly prevent _any_ change (which is not the intent).
 
+#### Default values must not change
+
+Default values are the values set by servers for resources when they are not
+specified by the client. This section only applies to static default values within
+fields on resources and does not apply to dynamic defaults such as the default IP
+address of a resource.
+
+Changing the default value is considered breaking and **must not** be done. The
+default behavior for a resource is determined by its default values, and this
+**must not** change across minor versions.
+
+For example:
+
+```proto
+message Book {
+    string name = 1;
+    // The genre of the book
+    // If this is not set when the book is created, the field will be given a value of FICTION.
+    enum Genre {
+      UNSPECIFIED = 0;
+      FICTION = 1;
+      NONFICTION = 2;
+    }
+}
+```
+
+Changing to:
+
+```proto
+message Book {
+    string name = 1;
+    // The genre of the book
+    // If this is not set when the book is created, the field will be given a value of NONFICTION.
+    enum Genre {
+      UNSPECIFIED = 0;
+      FICTION = 1;
+      NONFICTION = 2;
+    }
+}
+```
+
+would constitute a breaking change.
+
+#### Serializing defaults
+
+APIs **must not** change the way a field with a default value is serialized. For
+example if a field does not appear in the response if the value is equal to the
+default, the serialization **must not** change to include the field with the
+default. Clients may depend on the presence or absence of a field in a resource
+as semantically meaningful, so a change to how serialization is done for absent
+values **must not** occur in a minor version.
+
+Consider the following proto, where the default value of `wheels` is `2`:
+
+```proto
+// A representation of an automobile
+message Automobile {
+    // The name of the automobile.
+    string name = 1;
+
+    // The number of wheels on the automobile.
+    // The default value is 2, when no value is sent by the client.
+    int wheels = 2;
+}
+```
+
+First the proto serializes to JSON when the value of `wheels` is `2` as follows:
+
+```json
+{
+    "name": "my-car"
+}
+```
+
+Then, the API service changes the serialization to include `wheel` even if the
+value is equal to the default value, `2` as follows:
+
+```json
+{
+    "name": "my-car",
+    "wheels": 2
+}
+```
+
+This constitutes a change that is not backwards compatible within a major
+version.
+
 ## Further reading
 
 - For compatibility around pagination, see [AIP-158][].