feat(AIP-8) rm appendix, add rationale and history

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.