AIP-1

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.

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;
}

Technical leads

The current TL (technical lead) for APIs is Eric Brewer; he has delegated some responsibilities for API Design to the API Design TL (Yusuke Tsutsumi (@toumorokoshi)).

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:

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

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.

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

  • 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.