diff --git a/aip/general/0008.md b/aip/general/0008.md index 6c3aeda700..8d62fe6a3b 100644 --- a/aip/general/0008.md +++ b/aip/general/0008.md @@ -10,10 +10,9 @@ placement: # AIP Style guide AIP stands for **API Improvement Proposal**, which is a design document -providing high-level, concise documentation for API development. The goal is -for these documents to serve as the source of truth for API-related -documentation at Google and the way API teams discuss and come to consensus on -API guidance. +providing high-level, concise documentation for API development. The goal is for +these documents to serve as the source of truth for API-related documentation at +Google and the way API teams discuss and come to consensus on API guidance. AIPs are most useful when they are clear and concise, and cover a single topic or inquiry well. In the same way that AIPs describe consistent patterns and @@ -22,8 +21,8 @@ style for use in APIs, they also _follow_ consistent patterns and style. ## Guidance AIPs **must** cover a single, discrete topic, and **should** fundamentally -answer the question, "What do I do?" with actionable guidance. AIPs **may** -also cover what _not_ to do, but **should not** cover _only_ anti-patterns. +answer the question, "What do I do?" with actionable guidance. AIPs **may** also +cover what _not_ to do, but **should not** cover _only_ anti-patterns. While the length of AIPs will necessarily vary based on the complexity of the question, most AIPs **should** be able to cover their content in roughly two @@ -82,8 +81,8 @@ AIPs **should** then begin with an introduction (with no additional heading), followed by a `## Guidance` heading. If necessary, the AIP **may** include any of the following after the guidance, in the following order: -- "Further reading" is a bulleted list of links to other AIPs that are useful - to fully understand the current AIP. +- "Further reading" is a bulleted list of links to other AIPs that are useful to + fully understand the current AIP. - "Appendices" covering further explanation in the same AIP. These are relatively rare but are important in cases where an AIP requires a lot of justification for the decision. Often this is primarily an explanation of @@ -114,18 +113,34 @@ followed by a bulleted list explaining the example. Individual subsections can be cited individually, and further elaborate details. +## Rationale + +The "rationale" section is optional, and helps the reader understand the +motivation behind specific guidance within the AIP. + +Deeper explanations of design justification and tradeoffs **must** be in the +rationale instead of other sections, to ensure the rest of the document acts as +an easily actionable reference. + +## History + +The "history" section is optional, and documents events and context around a +significant edit to an AIP. For example, explanation of rewrite would be +included in this section + +While the changelog is a dotted list of one-line summaries of changes to an AIP, +the history section should elaborate on significant events in a descriptive +format. + +The section **must not** be used to exhaustively enumerate all changes. This +is what the changelog provides. + ## Further reading A bulleted list of (usually) other AIPs, in the following format: - [AIP-1](./0001.md): AIP purpose and guidelines -## Appendix - -An appendix is appropriate when a non-trivial side discussion is necessary. It -may explain historical reasons for the guidance, alternatives considered, or -other issues potentially of interest to the reader. - ## Changelog A bulleted list of changes in reverse chronological order, using the following @@ -137,8 +152,8 @@ format: AIPs **should** attempt to follow this overall format if possible, but AIPs **may** deviate from it if necessary (in particular, if the AIP would be more -difficult to understand, even for a reader already accustomed to reading AIPs -in the usual format). +difficult to understand, even for a reader already accustomed to reading AIPs in +the usual format). **Note:** Except for the title, AIPs **must** only use the second heading level (`##`) and above. AIPs **should** only use the second and third heading levels @@ -167,8 +182,8 @@ examples, a `google.api.http` annotation **should** be included. When AIPs reference other AIPs, the prosaic text **must** use the format `AIP-XXXX` without zero-padding (e.g., `AIP-8`, not `AIP-0008`), and **must** -link to the relevant AIP. AIP links **may** point to a particular section of -the AIP if appropriate. +link to the relevant AIP. AIP links **may** point to a particular section of the +AIP if appropriate. **Important:** AIP links **must** use the relative path to the file in the repository (such as `./0008.md` for core AIPs, or `../0008.md` for AIPs in a @@ -182,5 +197,6 @@ branch. ## Changelog +- **2023-03-30**: Removed appendix, added rationale and history to the template. - **2020-02-18**: Specified reverse chronological ordering for changelog items. -- **2019-08-23**: Added guidance for internal AIP links. +- **2019-08-23**: Added guidance for internal AIP links. \ No newline at end of file