Create style guide

aip/general/0008/aip.md

@@ -0,0 +1,177 @@
+# 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.
+
+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
+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.
+
+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
+printed pages.
+
+### File structure
+
+AIPs **must** be written in Markdown, and **must** be named using their
+four-digit number (example: `0008.md`). AIPs that serve a specific scope
+**must** be in the subdirectory for that scope.
+
+AIPs **must** have appropriate front matter.
+
+```yaml
+---
+aip:
+  id: 8
+  state: reviewing
+  created: 2019-05-28
+permalink: /8
+redirect_from:
+  - /08
+  - /008
+  - /0008
+---
+
+```
+
+Front matter for AIPs **must** include:
+
+- The `aip` key:
+  - `id`: Required. The ID for the given AIP, as an integer.
+  - `state`: Required. The current state of the AIP, in all lower-case. The
+    valid states are listed in [AIP-1][], and common states are `draft`,
+    `reviewing`, and `approved`.
+  - `created`: Required. The ISO-8601 date (`yyyy-mm-dd`) when the AIP was
+    originally drafted, with no quotes.
+  - `updated`: The ISO-8601 date (`yyyy-mm-dd`) when the AIP was last revised.
+  - `scope`: The scope for the AIP. This **must** match the directory name for
+    that scope. Required for AIPs with IDs >= 1000, prohibited otherwise.
+- The `permalink` key (required): This **must** be set to
+  `/{aip.scope}/{aip.id}`. If there is no scope, use `/{aip.id}` instead.
+- The `redirect_from` key: This should include a list of any `/{aip.id}`
+  permutations that a reader would be likely to enter, including:
+  - `/{aip.id}` (for AIPs where the permalink includes the scope)
+  - AIP IDs with zero-padding, for each level of zero-padding up to four digits
+    (for example: `/08`, `/008`, `/0008`).
+
+### Document structure
+
+AIPs **must** begin with a top-level heading with the AIP's title (`# Title`).
+The title **should** be a noun (not an imperative). For example, "Bad API
+precedents" not "Avoid breaking API precedent".
+
+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.
+- "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
+  alternatives considered to help explain the guidance.
+- "Changelog" is a bulleted list of changes made to the AIP since the first
+  writing.
+
+The guidance section **may** include subsections that elaborate further on
+details. Subsections will automatically create an entry in the table of
+contents, and an anchor for citations.
+
+Below is an example AIP shell that uses each major section:
+
+```md
+# AIP title
+
+The introductory text explains the background and reason why the AIP exists. It
+lays out the basic question, but does not tell the reader what to do.
+
+## Guidance
+
+The "guidance" section helps the reader know what to do. A common format for
+the guidance section is a high-level imperative, followed by an example,
+followed by a bulleted list explaining the example.
+
+### Subsection
+
+Individual subsections can be cited individually, and further elaborate
+details.
+
+## 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
+format:
+
+- **2020-02-18**: Specified ordering.
+- **2019-07-01**: Added a subsection clarifying XYZ.
+```
+
+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).
+
+**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
+(`##`, `###`).
+
+### Requirement keywords
+
+AIPs **should** use the following requirement level keywords: "MUST", "MUST
+NOT", "SHOULD", "SHOULD NOT", and "MAY", which are to be interpreted as
+described in [RFC 2119][].
+
+When using these terms in AIPs, they **must** be lower-case and **bold**. These
+terms **should not** be used in other ways.
+
+**Important:** If an appendix is used, it exists to provide background and a
+more complete understanding, but **must not** contain guidance (and RFC-2119
+terms **must not** be used).
+
+### Code examples
+
+API design examples in AIPs **should** use [protocol buffers][]. Examples
+**should** cover only enough syntax to explain the concept. When using RPCs in
+examples, a `google.api.http` annotation **should** be included.
+
+### Referencing AIPs
+
+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.
+
+**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
+subdirectory); this ensures that the link works both on the AIP site, when
+viewing the Markdown file on GitHub, using the local development server, or a
+branch.
+
+[aip-1]: ./0001.md
+[protocol buffers]: https://developers.google.com/protocol-buffers/
+[rfc 2119]: https://www.ietf.org/rfc/rfc2119.txt
+
+## Changelog
+
+- **2020-02-18**: Specified reverse chronological ordering for changelog items.
+- **2019-08-23**: Added guidance for internal AIP links.

aip/general/0008/aip.yaml

@@ -0,0 +1,7 @@
+---
+id: 8
+state: draft
+created: 2022-11-14
+placement:
+  category: meta
+  order: 10