Skip to content

Commit 01eb304

Browse files
mkistlermkistler
authored
Add AEP-8 - AEP Style and Guidance (#97)
* Content from Google AIP-8 * AEP changes * Fix prettier issues * Address PR review comments
1 parent 32f2e1f commit 01eb304

2 files changed

Lines changed: 258 additions & 6 deletions

File tree

‎aep/general/0008/aep.md‎

Lines changed: 256 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,257 @@
1-
# AIP Style guide
1+
# AEP Style and Guidance
22

3-
**Note:** This AEP has not yet been adopted. See
4-
[this GitHub issue](https://github.com/aep-dev/aep.dev/issues/32) for more
5-
information.
3+
AEP stands for **API Enhancement Proposal**, which is a design document
4+
providing high-level, concise documentation for API design and development. The
5+
goal is for these documents to serve as the source of truth for API-related
6+
documentation and the way API teams discuss and come to consensus on API
7+
guidance.
8+
9+
AEPs are most useful when they are clear and concise, and cover a single topic
10+
or inquiry well. In the same way that AEPs describe consistent patterns and
11+
style for use in APIs, they also _follow_ consistent patterns and style.
12+
13+
## Guidance
14+
15+
- AEPs **must** cover a single, discrete topic, and provide clear, actionable
16+
guidance.
17+
- AEPs **must not** duplicate or contradict guidance in another AEP.
18+
- AEPs **may** also cover what _not_ to do, but **should not** cover _only_
19+
anti-patterns.
20+
- If AEP guidance is conditional (e.g. a design pattern such as Jobs), the
21+
guidance **must** clearly explain under what conditions the guidance should
22+
be followed.
23+
24+
Guidance contained within an AEP **must** be beneficial to one or more types of
25+
clients or their authors, including but not limited to:
26+
27+
- Asset inventories which can be used to audit and analyze resources.
28+
- Command line interfaces for exploration and simple automation.
29+
- Custom controllers (e.g. auto-scalers) which poll live state and adjust
30+
resource configuration accordingly.
31+
- [IaC][] clients for orchestration and automation of multiple resources.
32+
- Recommendation tools which provide guidance on which APIs are useful for
33+
specific use cases, and how to use them.
34+
- SDKs to interact with an API from a programming language, often used heavily
35+
for data-plane operations.
36+
- Security orchestration, automation, and remediation tools.
37+
- Simple scripts to automate or orchestrate tasks.
38+
- Test frameworks.
39+
- Tools that operate on resource data at rest.
40+
- Visual User Interfaces for visualization and one-off manual actions.
41+
- Users.
42+
43+
Examples of enhancements include:
44+
45+
- Requiring new proto annotations that enable more descriptive interfaces on
46+
clients (e.g. requiring `singular` and `plural` on a `google.api.resource`
47+
annotation).
48+
49+
AEP guidance **must not** be a significant detriment to a client's usability or
50+
implementation difficulty, or maintenance difficulty.
51+
52+
Examples of detriments include:
53+
54+
- Introduction of a non-uniform pattern in a standard method such that all
55+
clients must introduce additional code without sufficient benefit (e.g. List
56+
behaves like this _except_ for resources that start with the name Foo).
57+
- Renames of well-established fields for minor enhancements in readability
58+
(e.g. rename `expire_time` to `lapse_time` since `lapse` is a common term in
59+
my service).
60+
61+
While the length of AEPs will necessarily vary based on the complexity of the
62+
question, most AEPs **should** be able to cover their content in roughly two
63+
printed pages.
64+
65+
### File structure
66+
67+
AEPs **must** be written in Markdown, and **must** be named using their
68+
four-digit number (example: `0008.md`). AEPs that serve a specific scope
69+
**must** be in the subdirectory for that scope.
70+
71+
AEPs **must** have appropriate front matter.
72+
73+
```yaml
74+
---
75+
id: 8
76+
state: reviewing
77+
created: 2019-05-28
78+
permalink: /8
79+
redirect_from:
80+
- /08
81+
- /008
82+
- /0008
83+
---
84+
```
85+
86+
Front matter for AEPs **must** include:
87+
88+
- The `aep` key:
89+
- `id`: Required. The ID for the given AEP, as an integer.
90+
- `state`: Required. The current state of the AEP, in all lower-case. The
91+
valid states are listed in [AEP-1][], and common states are `draft`,
92+
`reviewing`, and `approved`.
93+
- `created`: Required. The ISO-8601 date (`yyyy-mm-dd`) when the AEP was
94+
originally drafted, with no quotes.
95+
- `updated`: The ISO-8601 date (`yyyy-mm-dd`) when the AEP was last revised.
96+
- `scope`: The scope for the AEP. This **must** match the directory name for
97+
that scope. Required for AEPs with IDs >= 1000, prohibited otherwise.
98+
- The `permalink` key (required): This **must** be set to
99+
`/{aep.scope}/{aep.id}`. If there is no scope, use `/{aep.id}` instead.
100+
- The `redirect_from` key: This should include a list of any `/{aep.id}`
101+
permutations that a reader would be likely to enter, including:
102+
- `/{aep.id}` (for AEPs where the permalink includes the scope)
103+
- AEP IDs with zero-padding, for each level of zero-padding up to four digits
104+
(for example: `/08`, `/008`, `/0008`).
105+
106+
### Document structure
107+
108+
AEPs **must** begin with a top-level heading with the AEP's title (`# Title`).
109+
The title **should** be a noun (not an imperative). For example, "Bad API
110+
precedents" not "Avoid breaking API precedent".
111+
112+
AEPs **should** then begin with an introduction (with no additional heading),
113+
followed by a `## Guidance` heading. If necessary, the AEP **may** include any
114+
of the following after the guidance, in the following order:
115+
116+
- "Further reading" is a bulleted list of links to other AEPs that are useful
117+
to fully understand the current AEP.
118+
- "Appendices" covering further explanation in the same AEP. These are
119+
relatively rare but are important in cases where an AEP requires a lot of
120+
justification for the decision. Often this is primarily an explanation of
121+
alternatives considered to help explain the guidance.
122+
- "Changelog" is a bulleted list of changes made to the AEP since the first
123+
writing.
124+
125+
The guidance section **may** include subsections that elaborate further on
126+
details. Subsections will automatically create an entry in the table of
127+
contents, and an anchor for citations.
128+
129+
Below is an example AEP shell that uses each major section:
130+
131+
```md
132+
# AEP title
133+
134+
The introductory text explains the background and reason why the AEP exists. It
135+
lays out the basic question, but does not tell the reader what to do.
136+
137+
## Guidance
138+
139+
The "guidance" section helps the reader know what to do. A common format for
140+
the guidance section is a high-level imperative, followed by an example,
141+
followed by a bulleted list explaining the example.
142+
143+
### Subsection
144+
145+
Individual subsections can be cited individually, and further elaborate
146+
details.
147+
148+
## Rationale
149+
150+
The "rationale" section is optional, and helps the reader understand the
151+
motivation behind specific guidance within the AEP.
152+
153+
Deeper explanations of design justification and tradeoffs **must** be in the
154+
rationale instead of other sections, to ensure the rest of the document acts as
155+
an easily actionable reference.
156+
157+
## History
158+
159+
The "history" section is optional, and documents events and context around a
160+
significant edit to an AEP. For example, explanation of rewrite would be
161+
included in this section
162+
163+
While the changelog is a dotted list of one-line summaries of changes to an
164+
AEP, the history section should elaborate on significant events in a
165+
descriptive format.
166+
167+
The section **must not** be used to exhaustively enumerate all changes. This is
168+
what the changelog provides.
169+
170+
## Further reading
171+
172+
A bulleted list of (usually) other AEPs, in the following format:
173+
174+
- [AEP-1](./0001.md): AEP purpose and guidelines
175+
176+
## Changelog
177+
178+
A bulleted list of changes in reverse chronological order, using the following
179+
format:
180+
181+
- **2020-02-18**: Specified ordering.
182+
- **2019-07-01**: Added a subsection clarifying XYZ.
183+
```
184+
185+
AEPs **should** attempt to follow this overall format if possible, but AEPs
186+
**may** deviate from it if necessary (in particular, if the AEP would be more
187+
difficult to understand, even for a reader already accustomed to reading AEPs
188+
in the usual format).
189+
190+
**Note:** Except for the title, AEPs **must** only use the second heading level
191+
(`##`) and above. AEPs **should** only use the second and third heading levels
192+
(`##`, `###`).
193+
194+
### Requirement keywords
195+
196+
AEPs **should** use the following requirement level keywords: "MUST", "MUST
197+
NOT", "SHOULD", "SHOULD NOT", and "MAY", which are to be interpreted as
198+
described in [RFC 2119][].
199+
200+
When using these terms in AEPs, they **must** be lower-case and **bold**. These
201+
terms **should not** be used in other ways.
202+
203+
If "SHOULD" or "SHOULD NOT" are used, they **must** include valid examples of
204+
where other concerns may override the guidance.
205+
206+
**Important:** If rationale is used, it exists to provide background and a more
207+
complete understanding, but **must not** contain guidance (and RFC-2119 terms
208+
**must not** be used).
209+
210+
### Code examples
211+
212+
API design examples in AEPs **should** be presented in both [OpenAPI][] and
213+
[protocol buffers][]. Examples **should** cover only enough syntax to explain
214+
the concept. When using RPCs in examples, a `google.api.http` annotation
215+
**should** be included.
216+
217+
AEPs should use snake-case naming for parameters and properties (fields), for
218+
consistency across OpenAPI and protocol buffers, but other casing conventions
219+
may be used as long as they are applied uniformly.
220+
221+
### Referencing AEPs
222+
223+
When AEPs reference other AEPs, the prosaic text **must** use the format
224+
`AEP-XXXX` without zero-padding (e.g., `AEP-8`, not `AEP-0008`), and **must**
225+
link to the relevant AEP. AEP links **may** point to a particular section of
226+
the AEP if appropriate.
227+
228+
**Important:** AEP links **must** use the relative path to the file in the
229+
repository (such as `./0008.md` for core AEPs, or `../0008.md` for AEPs in a
230+
subdirectory); this ensures that the link works both on the AEP site, when
231+
viewing the Markdown file on GitHub, using the local development server, or a
232+
branch.
233+
234+
## Rationale
235+
236+
### Designing for a broad set of clients
237+
238+
API guidance, similar to any software, is most beneficial when there is a clear
239+
purpose and target beneficiary.
240+
241+
The beneficiaries of improved API design are users. These users interact with
242+
APIs via a variety of clients, depending on their use case as enumerated above.
243+
244+
API guidance must in turn consider the impact broadly across these clients.
245+
246+
## Changelog
247+
248+
- **2024-03-02**: From from https://google.aip.dev/8
249+
250+
<!-- Links -->
251+
252+
[aep-1]: ./0001.md
253+
[Infrastructure as Code]: ./0009.md#iac
254+
[IaC]: ./0009.md#iac
255+
[OpenAPI]: https://www.openapis.org/
256+
[protocol buffers]: https://developers.google.com/protocol-buffers/
257+
[rfc 2119]: https://www.ietf.org/rfc/rfc2119.txt

‎aep/general/0008/aep.yaml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
id: 8
3-
state: reviewing
3+
state: approved
44
slug: style-guide
5-
created: 2023-01-22
5+
created: 2024-03-02
66
placement:
77
category: meta

0 commit comments

Comments
 (0)