---
id: 1
state: approved
created: 2018-08-20
placement:
  category: meta
  order: 10
js_scripts:
  - /assets/js/graphviz/viz.js
  - /assets/js/graphviz/lite.render.js
  - /assets/js/aip/aip-graphviz.js
---

# AIP Purpose and Guidelines

As the corpus of Google APIs has grown and the API Governance team has grown to
meet the demand of supporting them, it is increasingly necessary to have a
corpus of documentation for API producers, reviewers, and other interested
parties to reference. The API style guide and introductory One Platform
documentation are intentionally terse and high-level. The AIP collection
provides a way to provide consistent documentation for API design guidance.

## What is an AIP?

AIP stands for **API Improvement Proposal**, which is a design document
providing high-level, concise documentation for API development. They are to
serve as the source of truth for API-related documentation at Google and the
means by which API teams discuss and come to consensus on API guidance. AIPs
are maintained as Markdown files in the [AIP GitHub repository][].

## Types of AIPs

There are several different types of AIPs, described below. The list of AIP
types may evolve over time as necessary.

### Guidance

These AIPs describe guidance on API design. These are provided as instruction
for API producers to help write simple, intuitive, and consistent APIs, and are
used by API reviewers as a basis for review comments.

### Process

These AIPs describe a process surrounding API design. They often affect the AIP
process itself and are used to enhance the way in which AIPs are handled.

## Stakeholders

As with any process there are many different stakeholders when it comes to
reviewing and working with AIPs. Below is a summary of the escalation path
starting with the API producer.

```graphviz
digraph d_front_back {
  rankdir=BT;
  ranksep=0.3;
  node [ style="filled,solid" shape=box fontname="Roboto" ];

  producer [ label="API Producer" ];
  editors [ label="AIP Editors" ];
  tl_infra [ label="Infrastructure TL" ];
  tl_design [ label="Design TL" ];
  tl [ label="TL" ];

  producer -> editors;
  editors -> tl_infra -> tl;
  editors -> tl_design -> tl;
}
```

As noted in the diagram above, the TL is the final decision-maker on the AIP
process and the final point of escalation if necessary.

### Editors

The editors are the set of people who make decisions on AIPs. The general goal
is that the AIP process is collaborative and that we largely work on the basis
of consensus. However, a limited number of designated approvers is necessary,
and these Googlers will be approvers for each AIP in the general scope.

The list of AIP editors is currently:

- Angie Lin ([@alin04][])
- Jon Skeet ([@jskeet][])
- Jose Juan Zavala Iglesias ([@itsStrobe][])
- Louis Dejardin ([@loudej][])
- Noah Dietz ([@noahdietz][])
- Sam Levenick ([@slevenick][])
- Sam Woodard ([@shwoodard][])

The editors are also responsible for the administrative and editorial aspects
of shepherding AIPs and managing the AIP pipeline and workflow. They approve
PRs to AIPs, assign proposal numbers, manage the agenda, set AIP states, and so
forth. They also ensure that AIPs are readable (proper spelling, grammar,
sentence structure, markup, etc.).

AIP editorship is by invitation of the current editors.

## Domain-specific AIPs

Some AIPs may be specific to a particular domain (for example, only to APIs
within a certain PA, or even a certain team). In this situation, the group will
be given a particular block of AIPs to use in accordance with AIP-2, and the
applicable AIPs will clearly indicate their scope.

## States

At any given time, AIPs may exist in a variety of states as they work their way
through the process. The following is a summary of each state.

### Draft

The initial state for an AIP is the "Draft" state. This means that the AIP is
being discussed and iterated upon, primarily by the original authors. While the
editors _may_ get involved at this stage, it is not necessary.

**Note:** If significant, high-level iteration is required, it is recommended
to draft AIPs in a Google doc instead of a PR. AIPs that are migrated into the
AIP system from Google Docs **may** skip the draft state and go directly to
reviewing provided there is sufficient approval.

### Reviewing

Once discussion on an AIP has generally concluded, but before it is formally
accepted it moves to the "Reviewing" state. This means that the authors have
reached a general consensus on the proposal and the editors are now involved.
At this stage the editors may request changes or suggest alternatives to the
proposal before moving forward.

**Note:** As a formal matter, one AIP approver (other than the author) **must**
provide formal signoff to advance an AIP to the reviewing state. Additionally,
there **must not** be formal objections ("changes requested" on the GitHub PR)
from other approvers.

### Approved

Once an approved AIP has been agreed upon, it enters "approved" state and is
considered "best current practice".

**Note:** As a formal matter, two AIP approvers (other than the author)
**must** provide formal signoff to advance an AIP to the approved state.
Additionally, there **must not** be formal objections ("changes requested" on
the GitHub PR) from other approvers.

### Withdrawn

If an AIP is withdrawn by the author or champion, it enters "withdrawn" state.
AIPs that are withdrawn may be taken up by another champion.

### Rejected

If an AIP is rejected by the AIP editors, it enters "rejected" state. AIPs that
are rejected remain, and provide documentation and reference to inform future
discussions.

### Deferred

If an AIP has not been acted upon for a significant period of time, the editors
may mark it as "deferred".

### Replaced

If an AIP has been replaced by another AIP, it enters "replaced" state. AIP
editors are responsible to provide a notice explaining the replacement and
rationale (the replacement AIP should also clearly explain the rationale).

In general, API producers should rely primarily on AIPs in the "approved"
state.

## Workflow

The following workflow describes the process for proposing an AIP, and moving
an AIP from proposal to implementation to final acceptance.

### Overview

```graphviz
digraph d_front_back {
  rankdir=LR;
  node [ style="filled,solid" shape=box fontname="Roboto" ];
  draft [ label="Draft" fillcolor="orange" ];
  reviewing [ label="Reviewing" fillcolor="lightskyblue" ];
  approved [ label="Approved" fillcolor="palegreen" ];
  withdrawn [ label="Withdrawn" fillcolor="mistyrose" ];
  rejected [ label="Rejected" fillcolor="mistyrose" ];
  deferred [ label="Deferred" fillcolor="lightsteelblue" ];
  replaced [ label="Replaced" fillcolor="lightsteelblue" ];

  draft -> reviewing;
  draft -> withdrawn [ style=dashed, color=mistyrose3 ];
  draft -> rejected [ style=dashed, color=mistyrose3 ];
  reviewing -> approved;
  reviewing -> withdrawn [ style=dashed, color=mistyrose3 ];
  reviewing -> rejected [ style=dashed, color=mistyrose3 ];
  draft -> deferred [ style=dashed, color=lightsteelblue3 ];
  reviewing -> deferred [ style=dashed, color=lightsteelblue3 ];
  approved -> replaced [ style=dashed, color=lightsteelblue3 ];
  reviewing -> replaced [ style=dashed, color=lightsteelblue3 ];
}
```

### Proposing an AIP

In order to propose an AIP, first [open an issue][] to circulate the
fundamental idea for initial feedback. It should generally be possible to
describe the idea in a couple of pages.

When proposing a new AIP or changes to an existing one, it is best to reference
prior art and/or example use cases that the proposal will impact, so as to
ensure that the proposal is grounded in a realistic problem space. So, proposals
**should** provide concrete references and/or well-defined examples. Appropriate
material includes, but is not limited to, the following:

- Existing external RFCs or standards
- A corpus of APIs that have aligned on a similar pattern e.g. `Search` methods
- A concrete use case that has yet to be solved that exists or could exist in
  one or more APIs e.g. adding an AIP-202 Format for AIP-143 Unicode CLDR
  region codes

Once ready, create a PR with a new file in the AIP directory using a file
titled `aip/new.md`. Ensure that the PR is editable by maintainers.

In most circumstances, the editors will assign the proposal an AIP number and
submit the PR with the AIP in the "Reviewing" state. The editors may reject an
AIP outright if they have an obvious reason to do so (e.g. the proposal was
already discussed and rejected in another AIP or is fundamentally unsound), in
which case the PR is not merged.

### Discussing an AIP

Once the PR is merged, the AIP author is responsible for championing the AIP on
a follow-up approval pull request. This means that the author is responsible
for pushing towards consensus around the proposal. This may involve a
discussion at the regularly scheduled meetings for the API Governance team.

The AIP author may modify the AIP over the course of discussion by submitting
follow-up commits to the PR.

### Accepting an AIP

The editors will work together to ensure that qualified proposals do not linger
in review.

To gain final approval, an AIP **must** be approved by, at minimum, the TL with
responsibility over the domain covered by the AIP (either design or
infrastructure) and at least one other editor, with no editors actively
requesting changes.

**Note:** If an AIP editor is the primary author of an AIP, then at least two
_other_ editors must approve it.

Once the AIP is approved, the editors will update the state of the AIP to
reflect this and submit the PR.

### Withdrawing or Rejecting an AIP

The author of an AIP may decide, after further consideration, that an AIP
should not advance. If so, the author may withdraw the AIP by updating the PR
adding a notice of withdrawal with an explanation of the rationale.
Additionally, the author may be unable to get consensus among the group and the
AIP editors may elect to reject the AIP. In this situation, the AIP editors
shall amend the PR adding a notice of rejection with an explanation of the
rationale. In both cases, the AIP editors update the state accordingly and
submit the PR.

### Replacing an AIP

In rare cases, it may be necessary to replace an AIP with another one. This is
not general practice: minor edits to approved AIPs are acceptable, and will be
the common way to tweak guidance. However, if new guidance fundamentally alters
the old guidance in some way, then the AIP editors shall create a new AIP that,
once approved, will replace the old one. The old one then enters "Replaced"
state, and will link to the new, current AIP.

## Changelog

- **2025-01-09**: Add requirement to include references/examples in proposals.
- **2024-09-04**: Updated names of current editors and remove TLs.
- **2023-05-10**: Updated names of current and editors and TLs.
- **2019-07-30**: Further clarified AIP quorum requirements.
- **2019-05-12**: Collapsed AIP approvers and editors into a single position,
  relaxed approval rules from full quorum.
- **2019-05-04**: Updated the AIP to refer to GitHub processes, rather than
  internal processes.

[aip github repository]: https://github.com/googleapis/aip
[open an issue]: https://github.com/googleapis/aip/issues
[@alin04]:https://github.com/alin04
[@jskeet]: https://github.com/jskeet
[@loudej]: https://github.com/loudej
[@noahdietz]: https://github.com/noahdietz
[@slevenick]: https://github.com/slevenick
[@shwoodard]: https://github.com/shwoodard
[@itsStrobe]: https://github.com/itsStrobe