From 8f2f167ec208543a84d68b4982bfed33959eeb3c Mon Sep 17 00:00:00 2001 From: Mak Ahmad Date: Mon, 14 Nov 2022 11:54:45 -0800 Subject: [PATCH 01/11] adopt google's style guide --- aip/general/0008/aip.md | 177 ++++++++++++++++++++++++++++++++++++++ aip/general/0008/aip.yaml | 7 ++ 2 files changed, 184 insertions(+) create mode 100644 aip/general/0008/aip.md create mode 100644 aip/general/0008/aip.yaml diff --git a/aip/general/0008/aip.md b/aip/general/0008/aip.md new file mode 100644 index 00000000..1420baa9 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/aip/general/0008/aip.yaml b/aip/general/0008/aip.yaml new file mode 100644 index 00000000..6ac71c77 --- /dev/null +++ b/aip/general/0008/aip.yaml @@ -0,0 +1,7 @@ +--- +id: 8 +state: draft +created: 2022-11-14 +placement: + category: meta + order: 10 \ No newline at end of file From 18ff74ceb5df10a6ec9e0c8e32ec1016d9432ef4 Mon Sep 17 00:00:00 2001 From: Mak Ahmad <19351474+makahmad@users.noreply.github.com> Date: Thu, 17 Nov 2022 23:20:23 -0800 Subject: [PATCH 02/11] Update aip/general/0008/aip.md Co-authored-by: Mike Kistler --- aip/general/0008/aip.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/aip/general/0008/aip.md b/aip/general/0008/aip.md index 1420baa9..c45413e8 100644 --- a/aip/general/0008/aip.md +++ b/aip/general/0008/aip.md @@ -3,7 +3,7 @@ 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 +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 From 5c9974ad138a44660d3085c9022bb41495becf37 Mon Sep 17 00:00:00 2001 From: Mak Ahmad <19351474+makahmad@users.noreply.github.com> Date: Thu, 17 Nov 2022 23:20:57 -0800 Subject: [PATCH 03/11] Update aip/general/0008/aip.md Co-authored-by: Mike Kistler --- aip/general/0008/aip.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/aip/general/0008/aip.md b/aip/general/0008/aip.md index c45413e8..aef43406 100644 --- a/aip/general/0008/aip.md +++ b/aip/general/0008/aip.md @@ -150,7 +150,7 @@ terms **must not** be used). ### Code examples -API design examples in AIPs **should** use [protocol buffers][]. Examples +API design examples in AIPs **should** use both [OpenAPI]{} and [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. From dcacfe132bc85b817b4d9ecc478198a2ecd6def8 Mon Sep 17 00:00:00 2001 From: Mak Ahmad <19351474+makahmad@users.noreply.github.com> Date: Thu, 17 Nov 2022 23:21:47 -0800 Subject: [PATCH 04/11] Update aip/general/0008/aip.md Co-authored-by: Mike Kistler --- aip/general/0008/aip.md | 1 + 1 file changed, 1 insertion(+) diff --git a/aip/general/0008/aip.md b/aip/general/0008/aip.md index aef43406..c041ec65 100644 --- a/aip/general/0008/aip.md +++ b/aip/general/0008/aip.md @@ -168,6 +168,7 @@ 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 From 27b5f905288641d720b33219c5886a038458b1b6 Mon Sep 17 00:00:00 2001 From: Mak Ahmad <19351474+makahmad@users.noreply.github.com> Date: Thu, 17 Nov 2022 23:23:28 -0800 Subject: [PATCH 05/11] Update aip/general/0008/aip.md Co-authored-by: Mike Kistler --- aip/general/0008/aip.md | 1 + 1 file changed, 1 insertion(+) diff --git a/aip/general/0008/aip.md b/aip/general/0008/aip.md index c041ec65..8e0197d5 100644 --- a/aip/general/0008/aip.md +++ b/aip/general/0008/aip.md @@ -85,6 +85,7 @@ of the following after the guidance, in the following order: 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. +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: From 17a6c708fdc3e2cf79e071de0ede3677182c90cb Mon Sep 17 00:00:00 2001 From: Mak Ahmad Date: Thu, 17 Nov 2022 23:32:46 -0800 Subject: [PATCH 06/11] updated guide based on comments --- aip/general/0008/aip.md | 18 +++++++----------- 1 file changed, 7 insertions(+), 11 deletions(-) diff --git a/aip/general/0008/aip.md b/aip/general/0008/aip.md index 8e0197d5..2d37ca3b 100644 --- a/aip/general/0008/aip.md +++ b/aip/general/0008/aip.md @@ -22,11 +22,11 @@ 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 +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. +AIPs **must** have appropriate front matter that lives in the `aip.yaml` file. ```yaml --- @@ -35,10 +35,6 @@ aip: state: reviewing created: 2019-05-28 permalink: /8 -redirect_from: - - /08 - - /008 - - /0008 --- ``` @@ -57,7 +53,7 @@ Front matter for AIPs **must** include: 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}` +- The `redirect_from` key: This should include a ist 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 @@ -82,10 +78,10 @@ of the following after the guidance, in the following order: - "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 +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. +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: @@ -151,7 +147,7 @@ terms **must not** be used). ### Code examples -API design examples in AIPs **should** use both [OpenAPI]{} and [protocol buffers][]. 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. From c98923fd447bac4319f041179cb74c11a7e5d0e6 Mon Sep 17 00:00:00 2001 From: Mak Ahmad Date: Thu, 17 Nov 2022 23:35:41 -0800 Subject: [PATCH 07/11] updated guide based on comments --- aip/general/0008/aip.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/aip/general/0008/aip.md b/aip/general/0008/aip.md index 2d37ca3b..0950fddd 100644 --- a/aip/general/0008/aip.md +++ b/aip/general/0008/aip.md @@ -53,8 +53,8 @@ Front matter for AIPs **must** include: 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 ist of any `/{aip.id}` - permutations that a reader would be likely to enter, including: +- 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`). From cd6f8eda86b9206fcd4d6ba9e8b481fd405e0474 Mon Sep 17 00:00:00 2001 From: Richard Frankel Date: Fri, 18 Nov 2022 14:45:29 -0800 Subject: [PATCH 08/11] Update aip/general/0008/aip.md Co-authored-by: Richard Frankel --- aip/general/0008/aip.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/aip/general/0008/aip.md b/aip/general/0008/aip.md index 0950fddd..44cca9ba 100644 --- a/aip/general/0008/aip.md +++ b/aip/general/0008/aip.md @@ -56,8 +56,6 @@ Front matter for AIPs **must** include: - 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 From db9cf2d6e7a311e40c566cdadd848b20b900238d Mon Sep 17 00:00:00 2001 From: Richard Frankel Date: Fri, 18 Nov 2022 14:45:48 -0800 Subject: [PATCH 09/11] Update aip/general/0008/aip.md Co-authored-by: Richard Frankel --- aip/general/0008/aip.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/aip/general/0008/aip.md b/aip/general/0008/aip.md index 44cca9ba..df2a5f12 100644 --- a/aip/general/0008/aip.md +++ b/aip/general/0008/aip.md @@ -54,8 +54,9 @@ Front matter for AIPs **must** include: - 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) + 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 From de79a0b58ddff8eafdbc667169ea0571a5ee22df Mon Sep 17 00:00:00 2001 From: Mak Ahmad Date: Tue, 22 Nov 2022 10:16:08 -0800 Subject: [PATCH 10/11] changed formatting --- aip/general/0008/aip.md | 38 +++++++++++++++++++++----------------- 1 file changed, 21 insertions(+), 17 deletions(-) diff --git a/aip/general/0008/aip.md b/aip/general/0008/aip.md index df2a5f12..d48a2be9 100644 --- a/aip/general/0008/aip.md +++ b/aip/general/0008/aip.md @@ -3,8 +3,8 @@ 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. +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 @@ -22,9 +22,9 @@ 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** 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. @@ -36,7 +36,6 @@ aip: created: 2019-05-28 permalink: /8 --- - ``` Front matter for AIPs **must** include: @@ -53,10 +52,9 @@ Front matter for AIPs **must** include: 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. +- 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 @@ -79,8 +77,12 @@ of the following after the guidance, in the following order: 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. +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: @@ -146,9 +148,10 @@ 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. +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 @@ -164,11 +167,12 @@ 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 +[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. \ No newline at end of file +- **2019-08-23**: Added guidance for internal AIP links. From c9cac0dd9c53e6107771b8f99c8e238ed5918c80 Mon Sep 17 00:00:00 2001 From: Mak Ahmad Date: Tue, 22 Nov 2022 10:21:15 -0800 Subject: [PATCH 11/11] updated redirect_from --- aip/general/0008/aip.md | 1 + aip/general/0008/aip.yaml | 3 ++- 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/aip/general/0008/aip.md b/aip/general/0008/aip.md index d48a2be9..e822d337 100644 --- a/aip/general/0008/aip.md +++ b/aip/general/0008/aip.md @@ -35,6 +35,7 @@ aip: state: reviewing created: 2019-05-28 permalink: /8 +redirect_from: style-guide --- ``` diff --git a/aip/general/0008/aip.yaml b/aip/general/0008/aip.yaml index 6ac71c77..e67d4a45 100644 --- a/aip/general/0008/aip.yaml +++ b/aip/general/0008/aip.yaml @@ -4,4 +4,5 @@ state: draft created: 2022-11-14 placement: category: meta - order: 10 \ No newline at end of file + order: 10 +redirect_from: style-guide \ No newline at end of file