Skip to content

Commit 4e84ff8

Browse files
authored
fix(AIP-1): Add guidance for including examples in proposals (#1472)
1 parent d497eaf commit 4e84ff8

1 file changed

Lines changed: 13 additions & 0 deletions

File tree

aip/general/0001.md

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -205,6 +205,18 @@ In order to propose an AIP, first [open an issue][] to circulate the
205205
fundamental idea for initial feedback. It should generally be possible to
206206
describe the idea in a couple of pages.
207207

208+
When proposing a new AIP or changes to an existing one, it is best to reference
209+
prior art and/or example use cases that the proposal will impact, so as to
210+
ensure that the proposal is grounded in a realistic problem space. So, proposals
211+
**should** provide concrete references and/or well-defined examples. Appropriate
212+
material includes, but is not limited to, the following:
213+
214+
- Existing external RFCs or standards
215+
- A corpus of APIs that have aligned on a similar pattern e.g. `Search` methods
216+
- A concrete use case that has yet to be solved that exists or could exist in
217+
one or more APIs e.g. adding an AIP-202 Format for AIP-143 Unicode CLDR
218+
region codes
219+
208220
Once ready, create a PR with a new file in the AIP directory using a file
209221
titled `aip/new.md`. Ensure that the PR is editable by maintainers.
210222

@@ -262,6 +274,7 @@ state, and will link to the new, current AIP.
262274

263275
## Changelog
264276

277+
- **2025-01-09**: Add requirement to include references/examples in proposals.
265278
- **2024-09-04**: Updated names of current editors and remove TLs.
266279
- **2023-05-10**: Updated names of current and editors and TLs.
267280
- **2019-07-30**: Further clarified AIP quorum requirements.

0 commit comments

Comments
 (0)