AIP-193: Update error messages section (including rationale)

Note: this removes the "message alignment" section which I found confusing.
We could restore and edit it should we wish.

Author: jskeet

aip/general/0193.md

@@ -240,64 +240,36 @@ authentication.
 
 ### Error messages
 
-The following sections describe best practices for error messages not
-described previously.
+Textual error messages can be present in both `Status.message` and
+`LocalizedMessage.message` fields. Messages should be succinct but
+actionable, with request-specific information (such as a resource name
+or region) providing precise details where appropriate. Any request-specific
+details **must** be present in [`ErrorInfo.metadata`](#errorinfo).
 
 #### Changing error messages
 
-##### Method
+Changing the content of `Status.message` over time must be done carefully,
+to avoid breaking clients who have previously had to rely on the message
+for all information. See [the rationale section](#updating-statusmessage)
+for more details.
 
-The method of changing error messages depends on whether an ErrorInfo
-payload is present in the message.
+For a given RPC:
 
-If the error message contains ErrorInfo payload (a machine-readable
-identifier):
+- If the RPC has *always* returned `ErrorInfo` with machine-readable
+  information, the content of `Status.message` **may** change over time.
+  (For example, the API producer may provide a clearer explanation,
+  or more request-specific information.)
+- Otherwise, the content of `Status.message` **must** be stable,
+  providing the same text with the same request-specific information.
+  Instead of changing `Status.message`, the API **should** include a
+  [`LocalizedMessage`](#localizedmessage) within `Status.details`.
 
-- `Status.message` *string* and `LocalizedMessage.message` *string* can
-   change
-- New metadata fields can be added
-- However, existing metadata fields **must not** be removed and existing
-  metadata field keys cannot be modified.
 
-If the error message does *not* contain ErrorInfo payload (usually for
-pre-existing APIs):
+Even if an RPC has always returned `ErrorInfo`, the API **may** keep
+the existing `Status.message` stable and add a
+[`LocalizedMessage`](#localizedmessage) within `Status.details`.
 
-- The `LocalizedMessage.message` *string* can change
-- However, the `Status.message` *string* **must** not be changed, as
-  this change is backward-incompatible.
-
-##### Message alignment
-
-`LocalizedMessage` is populated with the same message as
-`Status.message`. Should you choose, you can also present a different
-`LocalizedMessage.message` from `Status.message`. For reasons why or why not,
- see [the rationale](#LocalizedMessage).
-
-Keeping the aforementioned guidance in mind, the safest and recommended
-method to update an error message for a service is to add
-[`google.rpc.LocalizedMessage`][LocalizedMessage] to
-[`Status.details`][Status details].  `LocalizedMessage` is meant for
-displaying messages to end users.
-
-Add as much information as the consumer of the error needs to resolve
-the error, but succinctly.
-
-When including `LocalizedMessage`, both `locale` and `message` **must**
-be populated. If the service is to be localized, the value of `locale`
-**must** change dynamically. See "[Localization](#localization)".
-Otherwise, `locale` **must** always present the service's default
-locale; for example, "en-US".
-
-When adding an error message using `LocalizedMessage`, `ErrorInfo`
-**must** be introduced either before or at the same time. If there are
-dynamic segments found in the text, the values of these variables
-**must** be included in `ErrorInfo.metadata`. See, "[Dynamic
-variables](#dynamic-variables)".
-
-**Warning:** If `LocalizedMessage` is released without `ErrorInfo`, the
-same concerns regarding changing the value of the `message` field of
-`LocalizedMissage` apply: clients may misuse this textual error
-message--matching on string content.
+The content of `LocalizedMessage.details` **may** change over time.
 
 ### Partial errors
 
@@ -445,16 +417,24 @@ differs from `Status.message` include the following:
 
 ### Updating Status.message
 
-**Because Status.message is part of the API contract**, avoid updating
-it entirely in favor of updating LocalizedMessage; for example, clients
-often perform string matches on the text to differentiate one error for
-another and even parse the error message to extract variables from
-dynamic segments. 
-
-Clients **must** only perform string matches if their only option for
-extracting dynamic information is the message itself. If structured data
-is present in metadata, the recommended practice is to key into that
-data instead.
+If a client has ever observed an error with `Status.message` populated
+(which it always will be) but without `ErrorInfo`, the developer of that client
+may well have had to resort to parsing `Status.message` in order to find out
+information beyond just what `Status.code` conveys. That information may be
+found by matching specific text (e.g. "Connection closed with unknown cause")
+or by parsing the message to find out metadata values (e.g. a region with
+insufficient resources). At that point, `Status.message` is implicitly part
+of the API contract, so **must not** be updated - that would be a breaking
+change. This is one reason for introducing `LocalizedMessage` into the
+`Status.details`.
+
+RPCs which have **always** included `ErrorInfo` are in a better position:
+the contract is then more about the stability of `ErrorInfo` for any given
+error: the reason and domain need to be consistent over time, and the
+metadata provided for any given (reason,domain) can only be expanded.
+It's still possible that clients could be parsing `Status.message` instead of
+using `ErrorInfo`, but they will always have had a more robust option
+available to them.
 
 ## Further reading