Skip to content

Commit 8f2f167

Browse files
author
Mak Ahmad
committed
adopt google's style guide
1 parent 5748816 commit 8f2f167

2 files changed

Lines changed: 184 additions & 0 deletions

File tree

‎aip/general/0008/aip.md‎

Lines changed: 177 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,177 @@
1+
# AIP Style guide
2+
3+
AIP stands for **API Improvement Proposal**, which is a design document
4+
providing high-level, concise documentation for API development. The goal is
5+
for these documents to serve as the source of truth for API-related
6+
documentation at Google and the way API teams discuss and come to consensus on
7+
API guidance.
8+
9+
AIPs are most useful when they are clear and concise, and cover a single topic
10+
or inquiry well. In the same way that AIPs describe consistent patterns and
11+
style for use in APIs, they also _follow_ consistent patterns and style.
12+
13+
## Guidance
14+
15+
AIPs **must** cover a single, discrete topic, and **should** fundamentally
16+
answer the question, "What do I do?" with actionable guidance. AIPs **may**
17+
also cover what _not_ to do, but **should not** cover _only_ anti-patterns.
18+
19+
While the length of AIPs will necessarily vary based on the complexity of the
20+
question, most AIPs **should** be able to cover their content in roughly two
21+
printed pages.
22+
23+
### File structure
24+
25+
AIPs **must** be written in Markdown, and **must** be named using their
26+
four-digit number (example: `0008.md`). AIPs that serve a specific scope
27+
**must** be in the subdirectory for that scope.
28+
29+
AIPs **must** have appropriate front matter.
30+
31+
```yaml
32+
---
33+
aip:
34+
id: 8
35+
state: reviewing
36+
created: 2019-05-28
37+
permalink: /8
38+
redirect_from:
39+
- /08
40+
- /008
41+
- /0008
42+
---
43+
44+
```
45+
46+
Front matter for AIPs **must** include:
47+
48+
- The `aip` key:
49+
- `id`: Required. The ID for the given AIP, as an integer.
50+
- `state`: Required. The current state of the AIP, in all lower-case. The
51+
valid states are listed in [AIP-1][], and common states are `draft`,
52+
`reviewing`, and `approved`.
53+
- `created`: Required. The ISO-8601 date (`yyyy-mm-dd`) when the AIP was
54+
originally drafted, with no quotes.
55+
- `updated`: The ISO-8601 date (`yyyy-mm-dd`) when the AIP was last revised.
56+
- `scope`: The scope for the AIP. This **must** match the directory name for
57+
that scope. Required for AIPs with IDs >= 1000, prohibited otherwise.
58+
- The `permalink` key (required): This **must** be set to
59+
`/{aip.scope}/{aip.id}`. If there is no scope, use `/{aip.id}` instead.
60+
- The `redirect_from` key: This should include a list of any `/{aip.id}`
61+
permutations that a reader would be likely to enter, including:
62+
- `/{aip.id}` (for AIPs where the permalink includes the scope)
63+
- AIP IDs with zero-padding, for each level of zero-padding up to four digits
64+
(for example: `/08`, `/008`, `/0008`).
65+
66+
### Document structure
67+
68+
AIPs **must** begin with a top-level heading with the AIP's title (`# Title`).
69+
The title **should** be a noun (not an imperative). For example, "Bad API
70+
precedents" not "Avoid breaking API precedent".
71+
72+
AIPs **should** then begin with an introduction (with no additional heading),
73+
followed by a `## Guidance` heading. If necessary, the AIP **may** include any
74+
of the following after the guidance, in the following order:
75+
76+
- "Further reading" is a bulleted list of links to other AIPs that are useful
77+
to fully understand the current AIP.
78+
- "Appendices" covering further explanation in the same AIP. These are
79+
relatively rare but are important in cases where an AIP requires a lot of
80+
justification for the decision. Often this is primarily an explanation of
81+
alternatives considered to help explain the guidance.
82+
- "Changelog" is a bulleted list of changes made to the AIP since the first
83+
writing.
84+
85+
The guidance section **may** include subsections that elaborate further on
86+
details. Subsections will automatically create an entry in the table of
87+
contents, and an anchor for citations.
88+
89+
Below is an example AIP shell that uses each major section:
90+
91+
```md
92+
# AIP title
93+
94+
The introductory text explains the background and reason why the AIP exists. It
95+
lays out the basic question, but does not tell the reader what to do.
96+
97+
## Guidance
98+
99+
The "guidance" section helps the reader know what to do. A common format for
100+
the guidance section is a high-level imperative, followed by an example,
101+
followed by a bulleted list explaining the example.
102+
103+
### Subsection
104+
105+
Individual subsections can be cited individually, and further elaborate
106+
details.
107+
108+
## Further reading
109+
110+
A bulleted list of (usually) other AIPs, in the following format:
111+
112+
- [AIP-1](./0001.md): AIP purpose and guidelines
113+
114+
## Appendix
115+
116+
An appendix is appropriate when a non-trivial side discussion is necessary. It
117+
may explain historical reasons for the guidance, alternatives considered, or
118+
other issues potentially of interest to the reader.
119+
120+
## Changelog
121+
122+
A bulleted list of changes in reverse chronological order, using the following
123+
format:
124+
125+
- **2020-02-18**: Specified ordering.
126+
- **2019-07-01**: Added a subsection clarifying XYZ.
127+
```
128+
129+
AIPs **should** attempt to follow this overall format if possible, but AIPs
130+
**may** deviate from it if necessary (in particular, if the AIP would be more
131+
difficult to understand, even for a reader already accustomed to reading AIPs
132+
in the usual format).
133+
134+
**Note:** Except for the title, AIPs **must** only use the second heading level
135+
(`##`) and above. AIPs **should** only use the second and third heading levels
136+
(`##`, `###`).
137+
138+
### Requirement keywords
139+
140+
AIPs **should** use the following requirement level keywords: "MUST", "MUST
141+
NOT", "SHOULD", "SHOULD NOT", and "MAY", which are to be interpreted as
142+
described in [RFC 2119][].
143+
144+
When using these terms in AIPs, they **must** be lower-case and **bold**. These
145+
terms **should not** be used in other ways.
146+
147+
**Important:** If an appendix is used, it exists to provide background and a
148+
more complete understanding, but **must not** contain guidance (and RFC-2119
149+
terms **must not** be used).
150+
151+
### Code examples
152+
153+
API design examples in AIPs **should** use [protocol buffers][]. Examples
154+
**should** cover only enough syntax to explain the concept. When using RPCs in
155+
examples, a `google.api.http` annotation **should** be included.
156+
157+
### Referencing AIPs
158+
159+
When AIPs reference other AIPs, the prosaic text **must** use the format
160+
`AIP-XXXX` without zero-padding (e.g., `AIP-8`, not `AIP-0008`), and **must**
161+
link to the relevant AIP. AIP links **may** point to a particular section of
162+
the AIP if appropriate.
163+
164+
**Important:** AIP links **must** use the relative path to the file in the
165+
repository (such as `./0008.md` for core AIPs, or `../0008.md` for AIPs in a
166+
subdirectory); this ensures that the link works both on the AIP site, when
167+
viewing the Markdown file on GitHub, using the local development server, or a
168+
branch.
169+
170+
[aip-1]: ./0001.md
171+
[protocol buffers]: https://developers.google.com/protocol-buffers/
172+
[rfc 2119]: https://www.ietf.org/rfc/rfc2119.txt
173+
174+
## Changelog
175+
176+
- **2020-02-18**: Specified reverse chronological ordering for changelog items.
177+
- **2019-08-23**: Added guidance for internal AIP links.

‎aip/general/0008/aip.yaml‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
---
2+
id: 8
3+
state: draft
4+
created: 2022-11-14
5+
placement:
6+
category: meta
7+
order: 10

0 commit comments

Comments
 (0)