Create style guide

aip/general/0008/aip.md

@@ -0,0 +1,175 @@
+# 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 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 placed in corresponding directory using their
+four-digit number (example: `0008/aip.md`). AIPs that serve a specific scope
+**must** be in the subdirectory for that scope.
+
+AIPs **must** have appropriate front matter that lives in the `aip.yaml` file.
+
+```yaml
+---
+aip:
+  id: 8
+  state: reviewing
+  created: 2019-05-28
+permalink: /8
+---
+
+```
+
+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 one path
+   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 **should** include subsections that elaborate further on
+details. Subsections will automatically create an entry in the table of
+contents, and an anchor for citations.
+The guidance section **may** include abstract descriptions of structures and wherever possible these should use TypeScript syntax.  TypeScript is easy to follow for anyone familiar with either dynamic languages (like JavaScript or Python) or static languages (like Java or C++). These descriptions are intended as pseudo-code and are not intended to represent the actual implementation of the API in a TypeScript library.
+
+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 both [OpenAPI]{} and [protocol buffers][] in tabs. 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
+[OpenAPI]: https://github.com/OAI/OpenAPI-Specification/blob/3.0.3/versions/3.0.3.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