+ View on GitHub
+ 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 +offers a method 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;
+}
+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
+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.
Searchmethods
+ - 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. +