Skip to content

Commit 55afe46

Browse files
authored
Address bullet point indentation formatting issues. (#1387)
* Address bullet point indentation formatting issues. * Use minus consistently for bullets.
1 parent 458e911 commit 55afe46

1 file changed

Lines changed: 68 additions & 66 deletions

File tree

aip/general/0193.md

Lines changed: 68 additions & 66 deletions
Original file line numberDiff line numberDiff line change
@@ -90,8 +90,8 @@ Services must return a [`google.rpc.Status`][Status] message when an API
9090
error occurs. For each error the service **must** populate the `message`
9191
string in [`google.rpc.Status`][Status] as follows:
9292

93-
+ present a developer-facing, human-readable "debug message"
94-
+ present the message in the service's native language to explain both
93+
- present a developer-facing, human-readable "debug message"
94+
- present the message in the service's native language to explain both
9595
the error and offer an actionable resolution to it ([citation][Error
9696
model])
9797

@@ -102,14 +102,14 @@ bases, such as StackOverflow™.
102102

103103
Important points:
104104

105-
+ This `message` string is considered a problem description. It is
105+
- This `message` string is considered a problem description. It is
106106
intended for developers to understand the problem and is more
107107
detailed than [`ErrorInfo.reason`][ErrorInfo-reason], discussed in the
108108
next section.
109-
+ Use simple descriptive language that is easy to understand (without
109+
- Use simple descriptive language that is easy to understand (without
110110
technical jargon) to clearly state the problem that results in an
111111
error.
112-
+ For pre-existing (brownfield) APIs, the information in
112+
- For pre-existing (brownfield) APIs, the information in
113113
`google.rpc.Status` already exists and can’t be changed. In this
114114
case, do not edit anything in this `google.rpc.Status`, because some
115115
users might have automation running against the pre-existing content.
@@ -122,21 +122,21 @@ Important points:
122122
Details of this object are summarized in the following fields, field
123123
descriptions, and examples:
124124

125-
+ `code int32`
126-
+ The status code, which **must** be an enum value of
125+
- `code int32`
126+
- The status code, which **must** be an enum value of
127127
[`google.rpc.Code`][Code].
128-
+ *Example*: 8
129-
+ `message string`
130-
+ A developer-facing error message, which **should** be in English.
128+
- *Example*: 8
129+
- `message string`
130+
- A developer-facing error message, which **should** be in English.
131131
Any user-facing error message **should** be located in the
132132
LocalizedMessage payload.
133-
+ *Example message*: \"The zone \'us-east1-a\' does not have enough
133+
- *Example message*: \"The zone \'us-east1-a\' does not have enough
134134
resources available to fulfill the request. Try a different zone, or
135135
try again later.\"
136-
+ `details Object (repeated)`
137-
+ Additional text details about the error, which includes
136+
- `details Object (repeated)`
137+
- Additional text details about the error, which includes
138138
`ErrorInfo`,`LocalizedMessage`, and so on.
139-
+ *Example*: Described in the [ErrorDetails](#error-details) section.
139+
- *Example*: Described in the [ErrorDetails](#error-details) section.
140140

141141
#### [ErrorDetails][details]
142142

@@ -183,16 +183,16 @@ exactly one `ErrorInfo`. It is required.
183183
Details of this object are summarized in the following fields, field
184184
descriptions, and examples:
185185

186-
+ `reason string`
187-
+ A short snake_case description of why the error occurred. Error
186+
- `reason string`
187+
- A short snake_case description of why the error occurred. Error
188188
reasons are unique within a particular domain of errors. The error
189189
reason **must** do the following:
190-
+ Be at most 63 characters and match a regular expression of
190+
- Be at most 63 characters and match a regular expression of
191191
`/[A-Z][A-Z0-9_]+[A-Z0-9]/`, which represents UPPER_SNAKE_CASE.
192-
+ Be meaningful enough for a human reader to understand what the
192+
- Be meaningful enough for a human reader to understand what the
193193
reason refers to.
194-
+ Be unique and consumable by machine actors for automation.
195-
+ *Example*: CPU_AVAILABILITY<br>
194+
- Be unique and consumable by machine actors for automation.
195+
- *Example*: CPU_AVAILABILITY<br>
196196
Distill your error message into its simplest form. For example, the
197197
`reason string` could be one of the following text examples in
198198
UPPER_SNAKE_CASE: `UNAVAILABLE`, `NO_STOCK`, `CHECKED_OUT`,
@@ -201,29 +201,31 @@ descriptions, and examples:
201201
> The Book, "The Great Gatsby", is unavailable at the Library,
202202
> "Garfield East". It is expected to be available again on 2199-05-13.
203203
204-
+ In contrast, using either of the following reasons is not
204+
- In contrast, using either of the following reasons is not
205205
recommended: `THE_BOOK_YOU_WANT_IS_NOT_AVAILABLE`, `ERROR`. And,
206206
using either of the following reasons breaches the required
207207
formatting and is not allowed: `librariesAreGreat`, `noBooks`.
208-
+ `domain string`
209-
+ The logical grouping to which the `reason` belongs. The error domain
208+
209+
- `domain string`
210+
- The logical grouping to which the `reason` belongs. The error domain
210211
is typically the registered service name of the tool or product that
211212
generated the error. The domain must be a globally unique value.
212-
+ *Example*:<br>`pubsub.googleapis.com`
213-
+ `metadata map`
214-
+ Additional structured details about this error, which **should**
213+
- *Example*:<br>`pubsub.googleapis.com`
214+
215+
- `metadata map`
216+
- Additional structured details about this error, which **should**
215217
provide important context for customers to identify resolution
216218
steps. Keys **should** match `/[a-z][a-zA-Z0-9-_]+/`, and be
217219
limited to 64 characters in length. When identifying the current
218220
value of an exceeded limit, the units **should** be contained in the
219221
key, not the value.
220-
+ *Example*:
221-
```
222-
"vmType": "e2-medium",
223-
"attachment": "local-ssd=3,nvidia-t4=2",
224-
"zone": "us-east1-a"
225-
```
226-
+ For guidance on using the metadata map, see [Dynamic
222+
- *Example*:
223+
```
224+
"vmType": "e2-medium",
225+
"attachment": "local-ssd=3,nvidia-t4=2",
226+
"zone": "us-east1-a"
227+
```
228+
- For guidance on using the metadata map, see [Dynamic
227229
Variables](#dynamic-variables).
228230
229231
##### Dynamic variables
@@ -301,18 +303,18 @@ will differ from the `message` string in `google.rpc.status`.
301303
Details of this object are summarized in the following fields, field
302304
descriptions, and examples:
303305
304-
+ `locale string`
305-
+ The locale that follows the specification defined in [IETF
306+
- `locale string`
307+
- The locale that follows the specification defined in [IETF
306308
bcp47](https://www.rfc-editor.org/rfc/bcp/bcp47.txt) (Tags for
307309
Identifying Languages).
308-
+ *Example*: **"en-US"**, **"fr-CH"**, **"es-MX"**
309-
+ `message string`
310-
+ The error message that the customer will receive through their
310+
- *Example*: **"en-US"**, **"fr-CH"**, **"es-MX"**
311+
- `message string`
312+
- The error message that the customer will receive through their
311313
chosen service, which **should** include a brief description of the
312314
error and a call to action to resolve the error. The message
313315
**should** include, where needed, data provided in other fields such
314316
as metadata.
315-
+ Give users clear and concise instructions for resolving the error,
317+
- Give users clear and concise instructions for resolving the error,
316318
which **must** be explicit as possible; for example:
317319
318320
> Consider trying your request in the <AVAILABLE-ZONE-1>,
@@ -321,11 +323,11 @@ descriptions, and examples:
321323
> again with a different VM hardware configuration or at a later
322324
> time.
323325
324-
+ If the error resolution exceeds the number of characters supported in
326+
- If the error resolution exceeds the number of characters supported in
325327
the problem description (`message` string of `google.rpc.Status`),
326-
or requires multiple troubleshooting steps, include the most common
327-
resolution in the message and use the `Help` payload to link to
328-
relevant documentation.
328+
or requires multiple troubleshooting steps, include the most
329+
common resolution in the message and use the `Help` payload to
330+
link to relevant documentation.
329331
330332
##### Help payload
331333
@@ -353,7 +355,7 @@ descriptions, and examples:
353355
- The URL of the link. For error documentation this must follow the
354356
standardized format listed in the following example.
355357
- *Example*:
356-
https://cloud.google.com/PRODUCT/docs/ERROR-REASON
358+
https://cloud.google.com/PRODUCT/docs/ERROR-REASON
357359
358360
### Error messages
359361
@@ -370,17 +372,17 @@ payload is present in the message.
370372
If the error message contains ErrorInfo payload (a machine-readable
371373
identifier):
372374
373-
+ `Status.message` *string* and `LocalizedMessage.message` *string* can
375+
- `Status.message` *string* and `LocalizedMessage.message` *string* can
374376
change
375-
+ New metadata fields can be added
376-
+ However, existing metadata fields **must not** be removed and existing
377+
- New metadata fields can be added
378+
- However, existing metadata fields **must not** be removed and existing
377379
metadata field keys cannot be modified.
378380
379381
If the error message does *not* contain ErrorInfo payload (usually for
380382
pre-existing APIs):
381383
382-
+ The `LocalizedMessage.message` *string* can change
383-
+ However, the `Status.message` *string* **must** not be changed, as
384+
- The `LocalizedMessage.message` *string* can change
385+
- However, the `Status.message` *string* **must** not be changed, as
384386
this change is backward-incompatible.
385387
386388
##### Message alignment
@@ -469,17 +471,17 @@ message, which would be a backwards incompatible change.
469471
470472
Reasons to present the same error message in both locations include the following:
471473
472-
+ The service plans to localize either immediately or in the near future. See,
473-
"[Localization](#localization)".
474-
+ This practice enables clients to find an error message consistently in one
474+
- The service plans to localize either immediately or in the near future. See,
475+
"[Localization](#localization)".
476+
- This practice enables clients to find an error message consistently in one
475477
location, `LocalizedMessaage.message`, across all methods of the API Service.
476478
477479
Reasons to present an error message in `LocalizedMessage.message` that
478480
differs from `Status.message` include the following:
479481
480-
+ The service requires an end-user-facing error message that differs
482+
- The service requires an end-user-facing error message that differs
481483
from the "debug message".
482-
+ Ongoing, iterative error message improvements are expected.
484+
- Ongoing, iterative error message improvements are expected.
483485
484486
### Updating Status.message
485487
@@ -496,25 +498,25 @@ data instead.
496498
497499
## Further reading
498500
499-
+ For which error codes to retry, see [AIP-194][aip-194].
500-
+ For how to retry errors in client libraries, see
501+
- For which error codes to retry, see [AIP-194][aip-194].
502+
- For how to retry errors in client libraries, see
501503
[AIP-4221][aip-4221].
502504
503505
## Changelog
504506
505-
+ **2024-01-10**: Incorporate guidance for writing effective messages.
506-
+ **2023-05-17**: Change the recommended language for `Status.message` to be
507+
- **2024-01-10**: Incorporate guidance for writing effective messages.
508+
- **2023-05-17**: Change the recommended language for `Status.message` to be
507509
the service's native language rather than English.
508-
+ **2023-05-17**: Specify requirements for changing error messages.
509-
+ **2023-05-10**: Require [`ErrorInfo`][ErrorInfo] for all error responses.
510-
+ **2023-05-04**: Require uniqueness by message type for error details.
511-
+ **2022-11-04**: Added guidance around PERMISSION_DENIED errors previously
510+
- **2023-05-17**: Specify requirements for changing error messages.
511+
- **2023-05-10**: Require [`ErrorInfo`][ErrorInfo] for all error responses.
512+
- **2023-05-04**: Require uniqueness by message type for error details.
513+
- **2022-11-04**: Added guidance around PERMISSION_DENIED errors previously
512514
found in other AIPs.
513-
+ **2022-08-12**: Reworded/Simplified intro to add clarity to the intent.
514-
+ **2020-01-22**: Added a reference to the [`ErrorInfo`][ErrorInfo] message.
515-
+ **2019-10-14**: Added guidance restricting error message mutability to if
515+
- **2022-08-12**: Reworded/Simplified intro to add clarity to the intent.
516+
- **2020-01-22**: Added a reference to the [`ErrorInfo`][ErrorInfo] message.
517+
- **2019-10-14**: Added guidance restricting error message mutability to if
516518
there is a machine-readable identifier present.
517-
+ **2019-09-23**: Added guidance about error message strings being able to
519+
- **2019-09-23**: Added guidance about error message strings being able to
518520
change.
519521
520522
<!-- prettier-ignore-start -->

0 commit comments

Comments
 (0)