diff --git a/aip/general/0008/aip.md b/aip/general/0008/aip.md new file mode 100644 index 00000000..e822d337 --- /dev/null +++ b/aip/general/0008/aip.md @@ -0,0 +1,179 @@ +# 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 +redirect_from: style-guide +--- +``` + +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, such as "get" for the AIP about the standard method `Get`. + This means a link like `aip.dev/get` will redirect a user to that AIP. + +### 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. diff --git a/aip/general/0008/aip.yaml b/aip/general/0008/aip.yaml new file mode 100644 index 00000000..e67d4a45 --- /dev/null +++ b/aip/general/0008/aip.yaml @@ -0,0 +1,8 @@ +--- +id: 8 +state: draft +created: 2022-11-14 +placement: + category: meta + order: 10 +redirect_from: style-guide \ No newline at end of file