From 9302932a2d9a04b5c49dc099b40df1b0a575b2d4 Mon Sep 17 00:00:00 2001 From: Richard Frankel Date: Mon, 9 Oct 2023 18:43:33 -0400 Subject: [PATCH] Rebrand from AIP to AEP. (#59) * Rebrand from AIP to AEP. * Rebrand more comprehensively. * Revert change to publish workflow trigger. * Even more rebranding * Temporarily re-enable publishing from this branch. * Disable publishing from this branch again. * Yet another rebranding pass * Fix build-and-publish-protos workflow * Add proto changes I forgot to save, whoops * Revert accidental workflow change --- ADOPTERS.md | 10 +- CONTRIBUTING.md | 6 +- GOVERNANCE.md | 2 +- MAINTAINERS.md | 2 +- README.md | 5 +- .../0001/aip.md => aep/general/0001/aep.md | 128 +++++++++--------- .../aip.yaml => aep/general/0001/aep.yaml | 0 .../aip.md.j2 => aep/general/0126/aep.md.j2 | 2 +- .../aip.yaml => aep/general/0126/aep.yaml | 0 {aip => aep}/general/0126/enum.oas.yaml | 0 {aip => aep}/general/0126/enum.proto | 0 .../aip.md.j2 => aep/general/0131/aep.md.j2 | 10 +- .../aip.yaml => aep/general/0131/aep.yaml | 0 {aip => aep}/general/0131/get.oas.yaml | 0 {aip => aep}/general/0131/get.proto | 0 .../aip.md.j2 => aep/general/0132/aep.md.j2 | 12 +- .../aip.yaml => aep/general/0132/aep.yaml | 0 {aip => aep}/general/0132/list.oas.yaml | 0 {aip => aep}/general/0132/list.proto | 0 .../aip.md.j2 => aep/general/0136/aep.md.j2 | 2 +- .../aip.yaml => aep/general/0136/aep.yaml | 0 {aip => aep}/general/0136/library.oas.yaml | 0 {aip => aep}/general/0136/library.proto | 0 {aip => aep}/general/0136/translate.oas.yaml | 0 {aip => aep}/general/0136/translate.proto | 0 .../0141/aip.md => aep/general/0141/aep.md | 0 .../aip.yaml => aep/general/0141/aep.yaml | 0 .../0142/aip.md => aep/general/0142/aep.md | 0 .../aip.yaml => aep/general/0142/aep.yaml | 0 {aip => aep}/general/0144/add_remove.oas.yaml | 0 {aip => aep}/general/0144/add_remove.proto | 0 .../aip.md.j2 => aep/general/0144/aep.md.j2 | 4 +- .../aip.yaml => aep/general/0144/aep.yaml | 0 .../0145/aip.md => aep/general/0145/aep.md | 0 .../aip.yaml => aep/general/0145/aep.yaml | 0 .../aip.md.j2 => aep/general/0151/aep.md.j2 | 2 +- .../aip.yaml => aep/general/0151/aep.yaml | 0 {aip => aep}/general/0151/lro.oas.yaml | 0 {aip => aep}/general/0151/lro.proto | 0 .../0154/aip.md => aep/general/0154/aep.md | 2 +- .../aip.yaml => aep/general/0154/aep.yaml | 0 .../0158/aip.md => aep/general/0158/aep.md | 0 .../aip.yaml => aep/general/0158/aep.yaml | 0 .../aip.md.j2 => aep/general/0164/aep.md.j2 | 30 ++-- .../aip.yaml => aep/general/0164/aep.yaml | 0 {aip => aep}/general/0164/undelete.oas.yaml | 0 {aip => aep}/general/0164/undelete.proto | 0 .../0210/aip.md => aep/general/0210/aep.md | 0 .../aip.yaml => aep/general/0210/aep.yaml | 0 .../0211/aip.md => aep/general/0211/aep.md | 2 +- .../aip.yaml => aep/general/0211/aep.yaml | 0 {aip => aep}/general/scope.yaml | 0 .../proto/{aip => aep}/type/decimal.proto | 8 +- .../proto/{aip => aep}/type/money.proto | 10 +- common-components/proto/buf.yaml | 2 +- config/header.yaml | 2 +- config/hero.yaml | 22 +-- pages/general/licensing.md | 2 +- 58 files changed, 133 insertions(+), 132 deletions(-) rename aip/general/0001/aip.md => aep/general/0001/aep.md (62%) rename aip/general/0001/aip.yaml => aep/general/0001/aep.yaml (100%) rename aip/general/0126/aip.md.j2 => aep/general/0126/aep.md.j2 (98%) rename aip/general/0126/aip.yaml => aep/general/0126/aep.yaml (100%) rename {aip => aep}/general/0126/enum.oas.yaml (100%) rename {aip => aep}/general/0126/enum.proto (100%) rename aip/general/0131/aip.md.j2 => aep/general/0131/aep.md.j2 (96%) rename aip/general/0131/aip.yaml => aep/general/0131/aep.yaml (100%) rename {aip => aep}/general/0131/get.oas.yaml (100%) rename {aip => aep}/general/0131/get.proto (100%) rename aip/general/0132/aip.md.j2 => aep/general/0132/aep.md.j2 (97%) rename aip/general/0132/aip.yaml => aep/general/0132/aep.yaml (100%) rename {aip => aep}/general/0132/list.oas.yaml (100%) rename {aip => aep}/general/0132/list.proto (100%) rename aip/general/0136/aip.md.j2 => aep/general/0136/aep.md.j2 (98%) rename aip/general/0136/aip.yaml => aep/general/0136/aep.yaml (100%) rename {aip => aep}/general/0136/library.oas.yaml (100%) rename {aip => aep}/general/0136/library.proto (100%) rename {aip => aep}/general/0136/translate.oas.yaml (100%) rename {aip => aep}/general/0136/translate.proto (100%) rename aip/general/0141/aip.md => aep/general/0141/aep.md (100%) rename aip/general/0141/aip.yaml => aep/general/0141/aep.yaml (100%) rename aip/general/0142/aip.md => aep/general/0142/aep.md (100%) rename aip/general/0142/aip.yaml => aep/general/0142/aep.yaml (100%) rename {aip => aep}/general/0144/add_remove.oas.yaml (100%) rename {aip => aep}/general/0144/add_remove.proto (100%) rename aip/general/0144/aip.md.j2 => aep/general/0144/aep.md.j2 (98%) rename aip/general/0144/aip.yaml => aep/general/0144/aep.yaml (100%) rename aip/general/0145/aip.md => aep/general/0145/aep.md (100%) rename aip/general/0145/aip.yaml => aep/general/0145/aep.yaml (100%) rename aip/general/0151/aip.md.j2 => aep/general/0151/aep.md.j2 (99%) rename aip/general/0151/aip.yaml => aep/general/0151/aep.yaml (100%) rename {aip => aep}/general/0151/lro.oas.yaml (100%) rename {aip => aep}/general/0151/lro.proto (100%) rename aip/general/0154/aip.md => aep/general/0154/aep.md (98%) rename aip/general/0154/aip.yaml => aep/general/0154/aep.yaml (100%) rename aip/general/0158/aip.md => aep/general/0158/aep.md (100%) rename aip/general/0158/aip.yaml => aep/general/0158/aep.yaml (100%) rename aip/general/0164/aip.md.j2 => aep/general/0164/aep.md.j2 (86%) rename aip/general/0164/aip.yaml => aep/general/0164/aep.yaml (100%) rename {aip => aep}/general/0164/undelete.oas.yaml (100%) rename {aip => aep}/general/0164/undelete.proto (100%) rename aip/general/0210/aip.md => aep/general/0210/aep.md (100%) rename aip/general/0210/aip.yaml => aep/general/0210/aep.yaml (100%) rename aip/general/0211/aip.md => aep/general/0211/aep.md (98%) rename aip/general/0211/aip.yaml => aep/general/0211/aep.yaml (100%) rename {aip => aep}/general/scope.yaml (100%) rename common-components/proto/{aip => aep}/type/decimal.proto (88%) rename common-components/proto/{aip => aep}/type/money.proto (85%) diff --git a/ADOPTERS.md b/ADOPTERS.md index f2743e5d..8a161a30 100644 --- a/ADOPTERS.md +++ b/ADOPTERS.md @@ -1,12 +1,12 @@ # Adopters -The following enumerates organizations who have adopted the AIPs in some form +The following enumerates organizations who have adopted the AEPs in some form (directly, fork, or otherwise). -If you are using the AIPs at your organization, please add your organization's +If you are using the AEPs at your organization, please add your organization's name to this list (in alphabetical order). -| Organization | Contact | How you use the AIPs | +| Organization | Contact | How you use the AEPs | | ---------------------------------- | ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [Google](https://about.google/) | [@toumorokoshi](https://github.com/toumorokoshi) | Google maintains a fork at [google.aip.dev](http://google.aip.dev) which is adhered to for all APIs. Google also runs the [api-linter](https://linter.aip.dev/) across the company internally. | -| [Roblox](https://corp.roblox.com/) | [@rofrankel](https://github.com/rofrankel) | Roblox maintains a private fork of the AIPs, and is using them as a style guide for new APIs. Roblox also maintains private forks of the [api-linter](https://linter.aip.dev) and [site generator](https://github.com/aip-dev/site-generator). | +| [Google](https://about.google/) | [@toumorokoshi](https://github.com/toumorokoshi) | Google maintains a fork at [google.aep.dev](http://google.aep.dev) which is adhered to for all APIs. Google also runs the [api-linter](https://linter.aep.dev/) across the company internally. | +| [Roblox](https://corp.roblox.com/) | [@rofrankel](https://github.com/rofrankel) | Roblox maintains a private fork of the AEPs, and is using them as a style guide for new APIs. Roblox also maintains private forks of the [api-linter](https://linter.aep.dev) and [site generator](https://github.com/aep-dev/site-generator). | diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e6e51a10..29a30a3a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,7 +4,7 @@ We'd love to accept your patches and contributions to this project. ## Development Environment -If you are contributing AIP content (rather than code) and want to be able to +If you are contributing AEP content (rather than code) and want to be able to view it in your browser, the easiest way to do so is to run the provided development server. @@ -45,7 +45,7 @@ how to do so correctly is: [pyenv][5] is probably the best way if you have other Python projects). - Create a Python 3.8 [venv][6]. Once it is created, activate it in your shell (`source path/to/venv/bin/activate`). -- `pip install git+https://github.com/aip-dev/site-generator.git` +- `pip install git+https://github.com/aep-dev/site-generator.git` - `aep-site-serve .` ## Contributor License Agreement @@ -74,7 +74,7 @@ to ensure a consistent style throughout our source. You can add prettier as a plugin in most development environments. [1]: https://pages.github.com/ -[2]: https://github.com/aip-dev/site-generator +[2]: https://github.com/aep-dev/site-generator [3]: https://docker.com/ [4]: https://prettier.io/ [5]: https://github.com/pyenv/pyenv diff --git a/GOVERNANCE.md b/GOVERNANCE.md index 6f2ca936..aa8b190d 100644 --- a/GOVERNANCE.md +++ b/GOVERNANCE.md @@ -1,4 +1,4 @@ -# API Improvement Proposals: Project Charter +# API Enhancement Proposals: Project Charter ## Article I: Purpose diff --git a/MAINTAINERS.md b/MAINTAINERS.md index 642c7f57..95ca5173 100644 --- a/MAINTAINERS.md +++ b/MAINTAINERS.md @@ -21,7 +21,7 @@ approval privileges to the aep-dev organization. ## Emiritus -The following table enumerates previous maintainers of aip.dev, the original +The following table enumerates previous maintainers of aep.dev, the original style guide from which aep.dev was forked. | Name | GitHub | Organization | diff --git a/README.md b/README.md index 955e847f..77e8737c 100644 --- a/README.md +++ b/README.md @@ -13,13 +13,14 @@ See [GOVERNANCE.md](./GOVERNANCE.md). ## Learn and Connect -If you'd like to get involved in the AIP community, we'd love to have you! The +If you'd like to get involved in the AEP community, we'd love to have you! The following channels of communication are available: - [The #aep channel in the CNCF Slack](https://cloud-native.slack.com/archives/C04TX46UCTV). Sign up at https://slack.cncf.io. - [The AEP Google Calendar, to view any upcoming meetings](https://calendar.google.com/calendar/u/0?cid=N2UzNWRkM2RmMTk0YTMyZjRmYTdjMDNhMzQ1NGUyNGJhMzY1MWU2ZjU2ODI0OGVmZTFkZGYxZTM0YTdiZWU5ZUBncm91cC5jYWxlbmRhci5nb29nbGUuY29t). - - A weekly project meeting is held, which anyone interested is welcome to attend! + - A weekly project meeting is held, which anyone interested is welcome to + attend! ## License diff --git a/aip/general/0001/aip.md b/aep/general/0001/aep.md similarity index 62% rename from aip/general/0001/aip.md rename to aep/general/0001/aep.md index a953eb22..0c11ab94 100644 --- a/aip/general/0001/aip.md +++ b/aep/general/0001/aep.md @@ -1,4 +1,4 @@ -# AIP Purpose and Guidelines +# AEP Purpose and Guidelines Service APIs on the Internet continue to proliferate; having a machine-readable API is an expectation and prerequisite to adoption for many services. By some @@ -9,40 +9,40 @@ even as companies grow and disparate teams work to deliver discrete services, APIs ought to remain simple, intuitive, and consistent. Therefore, it is increasingly necessary to have a corpus of documentation for -API producers, reviewers, and other interested parties to reference. The AIP +API producers, reviewers, and other interested parties to reference. The AEP collection provides a way to provide consistent documentation for API design guidance. -## What is an AIP? +## What is an AEP? -AIP stands for **API Improvement Proposal**, which is a design document +AEP stands for **API Enhancement Proposal**, which is a design document providing high-level, concise documentation for API development. -Companies that adopt the AIP program use them as a source of truth for +Companies that adopt the AEP program use them as a source of truth for API-related documentation, and the means by which service producers discuss and -come to consensus on API guidance. AIPs are maintained as Markdown files with -metadata in the AIP GitHub repository. +come to consensus on API guidance. AEPs are maintained as Markdown files with +metadata in the AEP GitHub repository. -## Adopting AIPs +## Adopting AEPs -Companies **may** adopt the AIP system in one of two ways: +Companies **may** adopt the AEP system in one of two ways: -- By applying the guidance described at [aip.dev][]. -- By "forking" the AIP system and setting up their own subdomain. +- By applying the guidance described at [aep.dev][]. +- By "forking" the AEP system and setting up their own subdomain. Companies with an already-established corpus of services are unlikely to have -exactly followed the guidance at [aip.dev][]. Forking the system is valuable +exactly followed the guidance at [aep.dev][]. Forking the system is valuable because the guidance becomes comparable. Forks **must** retain the same -numbering system (AIP-2) to provide that comparability. +numbering system (AEP-2) to provide that comparability. ### Technical leadership -The AIP system, as well as the guidance on [aip.dev][], is overseen by the AIP +The AEP system, as well as the guidance on [aep.dev][], is overseen by the AEP technical steering committee. The committee is the set of people who make -decisions on AIPs. The general goal is that the AIP process is collaborative +decisions on AEPs. The general goal is that the AEP process is collaborative and that we largely work on the basis of consensus. However, a limited number of designated approvers is necessary, and these committee members will be -approvers for each AIP on [aip.dev][]. +approvers for each AEP on [aep.dev][]. The technical steering committee membership is currently: @@ -52,26 +52,26 @@ The technical steering committee membership is currently: - Luke Sneeringer (@lukesneeringer), Google The committee is 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, +of shepherding AEPs and managing the AEP pipeline and workflow. They approve +PRs to AEPs, assign proposal numbers, manage the agenda, set AEP states, and so +forth. They also ensure that AEPs are readable (proper spelling, grammar, sentence structure, markup, etc.). Committee membership is by invitation of the current committee. The committee **must not** include more than two members from the same company. -**Note:** Companies that maintain their own fork of [aip.dev][] select their +**Note:** Companies that maintain their own fork of [aep.dev][] select their own leadership and have full control of their fork's content. ## States -At any given time, AIPs may exist in a variety of states as they work their way +At any given time, AEPs may exist in a variety of states as they work their way through the process. The following is a summary of each state. ### Reviewing -Initial discussion on most AIPs occurs in the initial pull request to submit -the AIP. Once this PR is merged, the AIP exists in the "Reviewing" state. This +Initial discussion on most AEPs occurs in the initial pull request to submit +the AEP. Once this PR is merged, the AEP exists in the "Reviewing" state. This means that the authors and the technical steering committee have reached a general consensus on the proposal. @@ -79,66 +79,66 @@ At this stage, the committee may request changes or suggest alternatives to the proposal before moving forward, but there is a general expectation that the proposal will move forward and it is usually safe to "early adopt" it. -An AIP **must** be in the reviewing state for at least 14 days before being +An AEP **must** be in the reviewing state for at least 14 days before being approved, and the committee **should** send appropriate communication regarding the pending approval. -**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, +**Note:** As a formal matter, one AEP approver (other than the author) **must** +provide formal signoff to advance an AEP to the reviewing state. Additionally, there **must not** be formal objections ("changes requested" on the GitHub PR) from other approvers. ### Approved -Once an AIP has been agreed upon, it enters "approved" state and is considered +Once an AEP has been agreed upon, it enters "approved" state and is considered "best current practice". -AIPs **may** be edited after they are approved, either to correct grammar or +AEPs **may** be edited after they are approved, either to correct grammar or word choices, or to clarify semantic guidance (in response to reader questions). In rare occasions, new guidance **may** be added. Clarifications and new guidance **must** be reflected in the changelog. Correction of typos or minor language alterations **may** be done silently. -**Note:** As a formal matter, two AIP approvers (other than the author) -**must** provide formal signoff to advance an AIP to the approved state. +**Note:** As a formal matter, two AEP approvers (other than the author) +**must** provide formal signoff to advance an AEP to the approved state. Additionally, there **must not** be formal objections ("changes requested" on the GitHub PR) from other approvers. ### Final -If an AIP has been approved for a significant period and the technical steering +If an AEP has been approved for a significant period and the technical steering committee is certain that no further guidance will be needed, they **may** move -the AIP in to "final" state. +the AEP in to "final" state. -AIPs in the final state **must not** be amended with new guidance. They **may** +AEPs in the final state **must not** be amended with new guidance. They **may** be editied to correct spelling, grammar, or clarity provided there are no semantic changes. -**Note:** As a formal matter, two AIP approvers **must** provide formal signoff -to advance an AIP to the final state. Additionally, there **must not** be +**Note:** As a formal matter, two AEP approvers **must** provide formal signoff +to advance an AEP to the final state. Additionally, there **must not** be formal objections ("changes requested" on the GItHub PR) from other approvers. ### Replaced -If an AIP has been replaced by another AIP, it enters "replaced" state. The AIP +If an AEP has been replaced by another AEP, it enters "replaced" state. The AEP **must** include a notice explaining the replacement and rationale (the -replacement AIP **should** also clearly explain the rationale). +replacement AEP **should** also clearly explain the rationale). -In general, service producers rely primarily on AIPs in the "approved" state. -Service producers **may** rely on AIPs in the "reviewing" state +In general, service producers rely primarily on AEPs in the "approved" state. +Service producers **may** rely on AEPs in the "reviewing" state ### Withdrawn -If an AIP is withdrawn by the author or champion, or is rejected by the +If an AEP is withdrawn by the author or champion, or is rejected by the technical steering committee after reaching the "reviewing" state, it enters -"withdrawn" state. Withdrawn AIPs remain accessible, but are removed from the +"withdrawn" state. Withdrawn AEPs remain accessible, but are removed from the indexes; they provide documentation and reference to inform future discussions. ## Workflow -The following workflow describes the process for proposing an AIP, and moving -an AIP from proposal to implementation to final acceptance. +The following workflow describes the process for proposing an AEP, and moving +an AEP from proposal to implementation to final acceptance. ### Overview @@ -162,60 +162,60 @@ digraph d_front_back { } ``` -### Proposing an AIP +### Proposing an AEP -In order to propose an AIP, first open a pull request with a draft AIP; the AIP -should conform to the guidance in AIP-8. Most AIPs **should** be no more than +In order to propose an AEP, first open a pull request with a draft AEP; the AEP +should conform to the guidance in AEP-8. Most AEPs **should** be no more than two pages if printed out. -If the technical steering committee has suggested an AIP number, use that; +If the technical steering committee has suggested an AEP number, use that; otherwise use 99 (and expect to change it during the course of the review). **Important:** Ensure that the PR is editable by maintainers. -In most circumstances, the committee will assign the proposal an AIP number and +In most circumstances, the committee will assign the proposal an AEP number and begin discussion. Once there is consensus, the committee will merge the PR, and -the AIP will enter the "reviewing" state. +the AEP will enter the "reviewing" state. -The committee **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 +The committee **may** reject an AEP outright if they have an obvious reason to +do so (e.g. the proposal was already discussed and rejected in another AEP or is fundamentally unsound), in which case the PR is not merged. -### Accepting an AIP +### Accepting an AEP 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, two members +To gain final approval, an AEP **must** be approved by, at minimum, two members of the technical steering committee. Additionally, there **should not** be any committee members requesting significant changes (indicated by the use of the "changes requested" feature on GitHub). -**Note:** If an AIP editor is the primary author of an AIP, then at least two +**Note:** If an AEP editor is the primary author of an AEP, then at least two _other_ editors must approve it. -### Withdrawing or Rejecting an AIP +### Withdrawing or Rejecting an AEP -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 +The author of an AEP may decide, after further consideration, that an AEP +should not advance. If so, the author may withdraw the AEP 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 -technical steering committee may elect to reject the AIP. In this situation, +technical steering committee may elect to reject the AEP. In this situation, the committee shall amend the PR adding a notice of rejection with an explanation of the rationale. In both cases, the committee **must** update the state accordingly and submit the PR. -### Replacing an AIP +### Replacing an AEP -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 AIPs +In rare cases, it may be necessary to replace an AEP with another one. This is +not general practice: minor edits to approved AEPs are acceptable, and AEPs only enter final state when there is high confidence that further edits will not be necessary. However, if new guidance fundamentally alters the old guidance in some way, -then the technical steering committee **should** create a new AIP that, once +then the technical steering committee **should** create a new AEP that, once approved, will replace the old one. The old one then enters "Replaced" state, -and will link to the new, current AIP. +and will link to the new, current AEP. -[aip.dev]: https://aip.dev/ +[aep.dev]: https://aep.dev/ diff --git a/aip/general/0001/aip.yaml b/aep/general/0001/aep.yaml similarity index 100% rename from aip/general/0001/aip.yaml rename to aep/general/0001/aep.yaml diff --git a/aip/general/0126/aip.md.j2 b/aep/general/0126/aep.md.j2 similarity index 98% rename from aip/general/0126/aip.md.j2 rename to aep/general/0126/aep.md.j2 index 786f5583..2a028fae 100644 --- a/aip/general/0126/aip.md.j2 +++ b/aep/general/0126/aep.md.j2 @@ -132,7 +132,7 @@ choice (although `google.protobuf.BoolValue` is also available). ## Further reading -- For states, a special type of enum, see AIP-216. +- For states, a special type of enum, see AEP-216. [bcp-47]: https://en.wikipedia.org/wiki/IETF_language_tag [media types]: https://en.wikipedia.org/wiki/Media_type diff --git a/aip/general/0126/aip.yaml b/aep/general/0126/aep.yaml similarity index 100% rename from aip/general/0126/aip.yaml rename to aep/general/0126/aep.yaml diff --git a/aip/general/0126/enum.oas.yaml b/aep/general/0126/enum.oas.yaml similarity index 100% rename from aip/general/0126/enum.oas.yaml rename to aep/general/0126/enum.oas.yaml diff --git a/aip/general/0126/enum.proto b/aep/general/0126/enum.proto similarity index 100% rename from aip/general/0126/enum.proto rename to aep/general/0126/enum.proto diff --git a/aip/general/0131/aip.md.j2 b/aep/general/0131/aep.md.j2 similarity index 96% rename from aip/general/0131/aip.md.j2 rename to aep/general/0131/aep.md.j2 index 3fb804eb..489c150c 100644 --- a/aip/general/0131/aip.md.j2 +++ b/aep/general/0131/aep.md.j2 @@ -13,7 +13,7 @@ APIs **should** generally provide a `GET` method for resources unless it is not valuable for users to do so. When the `GET` method is used on a URI ending in a resource ID or resource ID alias, the result should be a single resource. For more information about using the `GET` method on a URI ending with a resource -collection identifier, see AIP-132. +collection identifier, see AEP-132. ### Requests @@ -33,7 +33,7 @@ Accept: application/json **must not** cause an error. - The request **must not** require any fields in the query string. The request **should not** include optional fields in the query string unless described - in another AIP. + in another AEP. ### Responses @@ -77,7 +77,7 @@ Get operations are specified using the following pattern: - The response message **must** be the resource itself. (There is no `GetBookResponse`.) - The response **should** usually include the fully-populated resource unless - there is a reason to return a partial response (see AIP-157). + there is a reason to return a partial response (see AEP-157). - The HTTP verb **must** be `GET`. - The URI **should** contain a single variable field corresponding to the resource name. @@ -100,7 +100,7 @@ Get operations also implement a common request message pattern: - The comment for the `name` field **should** document the resource pattern. - The request message **must not** contain any other required fields, and **should not** contain other optional fields except those described in - another AIP. + another AEP. **Note:** The `name` field in the request object corresponds to the `name` variable in the `google.api.http` annotation on the RPC. This causes the `name` @@ -119,7 +119,7 @@ metadata: - The response content **must** be the resource itself. For example: `#/components/schemas/Book` - The response **should** usually include the fully-populated resource unless - there is a reason to return a partial response (see AIP-157). + there is a reason to return a partial response (see AEP-157). - The URI **should** contain a variable for each individual ID in the resource hierarchy. - The path parameter for all resource IDs **must** be in the form diff --git a/aip/general/0131/aip.yaml b/aep/general/0131/aep.yaml similarity index 100% rename from aip/general/0131/aip.yaml rename to aep/general/0131/aep.yaml diff --git a/aip/general/0131/get.oas.yaml b/aep/general/0131/get.oas.yaml similarity index 100% rename from aip/general/0131/get.oas.yaml rename to aep/general/0131/get.oas.yaml diff --git a/aip/general/0131/get.proto b/aep/general/0131/get.proto similarity index 100% rename from aip/general/0131/get.proto rename to aep/general/0131/get.proto diff --git a/aip/general/0132/aip.md.j2 b/aep/general/0132/aep.md.j2 similarity index 97% rename from aip/general/0132/aip.md.j2 rename to aep/general/0132/aep.md.j2 index 31bedb5f..a42fe6af 100644 --- a/aip/general/0132/aip.md.j2 +++ b/aep/general/0132/aep.md.j2 @@ -11,7 +11,7 @@ APIs **should** generally provide a `GET` method for resource collections unless it is not valuable for users to do so. When the `GET` method is used on a URI ending in a resource collection, the result should be a list of resources. For more information about using the `GET` method on a URI ending -with a discrete resource ID, see AIP-131. +with a discrete resource ID, see AEP-131. ### Requests @@ -67,7 +67,7 @@ individual result being a resource: - The `string nextPageToken` field **must** be included in the list response schema. It **must** be set if there are subsequent pages, and **must not** be set if the response represents the final page. For more information, see - AIP-158. + AEP-158. - The response struct **may** include a `int32 totalSize` (or `int64 totalSize`) field with the number of items in the collection. - The value **may** be an estimate (the field **should** clearly document @@ -118,7 +118,7 @@ always possible to add ordering later, but removing it is a breaking change. List methods **may** allow clients to specify filters; if they do, the request message **should** contain a `string filter` field. Filtering is described in -more detail in AIP-160. +more detail in AEP-160. **Note:** Only include filtering if there is an established need to do so. It is always possible to add filtering later, but removing it is a breaking @@ -147,7 +147,7 @@ List operations are specified using the following pattern: - The request message **must** match the RPC name, with a `-Request` suffix. - The response message **must** match the RPC name, with a `-Response` suffix. - The response **should** usually include fully-populated resources unless - there is a reason to return a partial response (see AIP-157). + there is a reason to return a partial response (see AEP-157). - The HTTP verb **must** be `GET`. - The URI **should** contain a single variable field corresponding to the collection parent's name. @@ -170,7 +170,7 @@ List operations also implement a common request message pattern: being listed. - The `max_page_size` and `page_token` fields, which support pagination, **must** be specified on all list request messages. For more information, see - AIP-158. + AEP-158. **Note:** The `parent` field in the request object corresponds to the `parent` variable in the `google.api.http` annotation on the RPC. This causes the @@ -198,7 +198,7 @@ metadata: - The response content **must** be the resource itself. For example: `#/components/schemas/Book` - The response **should** usually include the fully-populated resource unless - there is a reason to return a partial response (see AIP-157). + there is a reason to return a partial response (see AEP-157). - The URI **should** contain a variable for each individual ID in the resource hierarchy. - The path parameter for all resource IDs **must** be in the form diff --git a/aip/general/0132/aip.yaml b/aep/general/0132/aep.yaml similarity index 100% rename from aip/general/0132/aip.yaml rename to aep/general/0132/aep.yaml diff --git a/aip/general/0132/list.oas.yaml b/aep/general/0132/list.oas.yaml similarity index 100% rename from aip/general/0132/list.oas.yaml rename to aep/general/0132/list.oas.yaml diff --git a/aip/general/0132/list.proto b/aep/general/0132/list.proto similarity index 100% rename from aip/general/0132/list.proto rename to aep/general/0132/list.proto diff --git a/aip/general/0136/aip.md.j2 b/aep/general/0136/aep.md.j2 similarity index 98% rename from aip/general/0136/aip.md.j2 rename to aep/general/0136/aep.md.j2 index 87336913..89835616 100644 --- a/aip/general/0136/aip.md.j2 +++ b/aep/general/0136/aep.md.j2 @@ -116,7 +116,7 @@ have no permanent effect on data within the API. Declarative-friendly resources usually **should not** employ custom operations (except specific declarative-friendly custom operations discussed in other -AIPs), because declarative-friendly tools are unable to automatically determine +AEPs), because declarative-friendly tools are unable to automatically determine what to do with them. An exception to this is for rarely-used, fundamentally imperative operations, diff --git a/aip/general/0136/aip.yaml b/aep/general/0136/aep.yaml similarity index 100% rename from aip/general/0136/aip.yaml rename to aep/general/0136/aep.yaml diff --git a/aip/general/0136/library.oas.yaml b/aep/general/0136/library.oas.yaml similarity index 100% rename from aip/general/0136/library.oas.yaml rename to aep/general/0136/library.oas.yaml diff --git a/aip/general/0136/library.proto b/aep/general/0136/library.proto similarity index 100% rename from aip/general/0136/library.proto rename to aep/general/0136/library.proto diff --git a/aip/general/0136/translate.oas.yaml b/aep/general/0136/translate.oas.yaml similarity index 100% rename from aip/general/0136/translate.oas.yaml rename to aep/general/0136/translate.oas.yaml diff --git a/aip/general/0136/translate.proto b/aep/general/0136/translate.proto similarity index 100% rename from aip/general/0136/translate.proto rename to aep/general/0136/translate.proto diff --git a/aip/general/0141/aip.md b/aep/general/0141/aep.md similarity index 100% rename from aip/general/0141/aip.md rename to aep/general/0141/aep.md diff --git a/aip/general/0141/aip.yaml b/aep/general/0141/aep.yaml similarity index 100% rename from aip/general/0141/aip.yaml rename to aep/general/0141/aep.yaml diff --git a/aip/general/0142/aip.md b/aep/general/0142/aep.md similarity index 100% rename from aip/general/0142/aip.md rename to aep/general/0142/aep.md diff --git a/aip/general/0142/aip.yaml b/aep/general/0142/aep.yaml similarity index 100% rename from aip/general/0142/aip.yaml rename to aep/general/0142/aep.yaml diff --git a/aip/general/0144/add_remove.oas.yaml b/aep/general/0144/add_remove.oas.yaml similarity index 100% rename from aip/general/0144/add_remove.oas.yaml rename to aep/general/0144/add_remove.oas.yaml diff --git a/aip/general/0144/add_remove.proto b/aep/general/0144/add_remove.proto similarity index 100% rename from aip/general/0144/add_remove.proto rename to aep/general/0144/add_remove.proto diff --git a/aip/general/0144/aip.md.j2 b/aep/general/0144/aep.md.j2 similarity index 98% rename from aip/general/0144/aip.md.j2 rename to aep/general/0144/aep.md.j2 index 2c6ca05c..6320e698 100644 --- a/aip/general/0144/aip.md.j2 +++ b/aep/general/0144/aep.md.j2 @@ -63,7 +63,7 @@ back. This is fine for many situations, particularly when the array field is expected to have a small size (fewer than 10 or so) and race conditions are not an issue, or can be guarded against with [ETags][aip-154]. -**Note:** Declarative-friendly resources (AIP-128) **must** use the standard +**Note:** Declarative-friendly resources (AEP-128) **must** use the standard `Update` method, and not introduce `Add` and `Remove` methods. If declarative tools need to reason about particular relationships while ignoring others, consider using a subresource instead. @@ -144,7 +144,7 @@ subresource instead. - The field **should** be [annotated as required][aip-203]. - The request message **must not** contain any other required fields, and **should not** contain other optional fields except those described in this - or another AIP. + or another AEP. {% tab oas %} diff --git a/aip/general/0144/aip.yaml b/aep/general/0144/aep.yaml similarity index 100% rename from aip/general/0144/aip.yaml rename to aep/general/0144/aep.yaml diff --git a/aip/general/0145/aip.md b/aep/general/0145/aep.md similarity index 100% rename from aip/general/0145/aip.md rename to aep/general/0145/aep.md diff --git a/aip/general/0145/aip.yaml b/aep/general/0145/aep.yaml similarity index 100% rename from aip/general/0145/aip.yaml rename to aep/general/0145/aep.yaml diff --git a/aip/general/0151/aip.md.j2 b/aep/general/0151/aep.md.j2 similarity index 99% rename from aip/general/0151/aip.md.j2 rename to aep/general/0151/aep.md.j2 index e6d41723..29c1f943 100644 --- a/aip/general/0151/aip.md.j2 +++ b/aep/general/0151/aep.md.j2 @@ -115,7 +115,7 @@ time has elapsed after the request completed. ### Errors Errors that prevent a long-running request from _starting_ **must** return an -error response (AIP-193), similar to any other method. +error response (AEP-193), similar to any other method. Errors that occur over the course of a request **may** be placed in the metadata message. The errors themselves **must** still be represented with a diff --git a/aip/general/0151/aip.yaml b/aep/general/0151/aep.yaml similarity index 100% rename from aip/general/0151/aip.yaml rename to aep/general/0151/aep.yaml diff --git a/aip/general/0151/lro.oas.yaml b/aep/general/0151/lro.oas.yaml similarity index 100% rename from aip/general/0151/lro.oas.yaml rename to aep/general/0151/lro.oas.yaml diff --git a/aip/general/0151/lro.proto b/aep/general/0151/lro.proto similarity index 100% rename from aip/general/0151/lro.proto rename to aep/general/0151/lro.proto diff --git a/aip/general/0154/aip.md b/aep/general/0154/aep.md similarity index 98% rename from aip/general/0154/aip.md rename to aep/general/0154/aep.md index b2fad5ca..8e6c3f68 100644 --- a/aip/general/0154/aip.md +++ b/aep/general/0154/aep.md @@ -103,7 +103,7 @@ not equivalent to the old one). ## Further reading -- For how to retry on errors in client libraries, see AIP-194. +- For how to retry on errors in client libraries, see AEP-194. ## Changelog diff --git a/aip/general/0154/aip.yaml b/aep/general/0154/aep.yaml similarity index 100% rename from aip/general/0154/aip.yaml rename to aep/general/0154/aep.yaml diff --git a/aip/general/0158/aip.md b/aep/general/0158/aep.md similarity index 100% rename from aip/general/0158/aip.md rename to aep/general/0158/aep.md diff --git a/aip/general/0158/aip.yaml b/aep/general/0158/aep.yaml similarity index 100% rename from aip/general/0158/aip.yaml rename to aep/general/0158/aep.yaml diff --git a/aip/general/0164/aip.md.j2 b/aep/general/0164/aep.md.j2 similarity index 86% rename from aip/general/0164/aip.md.j2 rename to aep/general/0164/aep.md.j2 index 8db72334..23526584 100644 --- a/aip/general/0164/aip.md.j2 +++ b/aep/general/0164/aep.md.j2 @@ -16,8 +16,8 @@ system. If the method behaves this way, it **should** return `200 OK` with the updated resource instead of `204 No Content`. Resources that support soft delete **should** have an `expire_time` field as -described in AIP-148. Additionally, resources **should** include a `DELETED` -state value if the resource includes a `state` field (AIP-216). +described in AEP-148. Additionally, resources **should** include a `DELETED` +state value if the resource includes a `state` field (AEP-216). ### Undelete @@ -44,7 +44,7 @@ A resource that supports soft delete **should** provide an `Undelete` method: - The comment for the field **should** document the resource pattern. - The request message **must not** contain any other required fields, and **should not** contain other optional fields except those described in this - or another AIP. + or another AEP. {% tab oas %} @@ -56,7 +56,7 @@ A resource that supports soft delete **should** provide an `Undelete` method: infeasible to do so. - The operation **must not** require any other fields, and **should not** contain other optional query parameters except those described in this or - another AIP. + another AEP. {% endtabs %} @@ -64,27 +64,27 @@ A resource that supports soft delete **should** provide an `Undelete` method: Some resources take longer to undelete a resource than is reasonable for a regular API request. In this situation, the API **should** follow the -long-running request pattern (AIP-151). +long-running request pattern (AEP-151). ### List and Get -Soft-deleted resources **should not** be returned in `List` (AIP-132) responses +Soft-deleted resources **should not** be returned in `List` (AEP-132) responses by default (unless `bool show_deleted` is true). -A `Get` (AIP-131) request for a soft deleted resource **should** error with +A `Get` (AEP-131) request for a soft deleted resource **should** error with `410 Gone` unless `bool show_deleted` is true, in which case soft-deleted resources **must** return the resource. Services that soft delete resources **may** choose a reasonable strategy for purging those resources, including automatic purging after a reasonable time -(such as 30 days), allowing users to set an expiry time (AIP-214), or retaining +(such as 30 days), allowing users to set an expiry time (AEP-214), or retaining the resources indefinitely. Regardless of what strategy is selected, the service **should** document when soft deleted resources will be completely removed. ### Declarative-friendly resources -A resource that is declarative-friendly (AIP-128) **should** support soft +A resource that is declarative-friendly (AEP-128) **should** support soft delete and undelete. **Important:** There is an ambiguity in declarative tooling between "create" @@ -100,8 +100,8 @@ Declarative-friendly resources **must** use long-running operations for both soft delete and undelete. The service **may** return an LRO that is already set to done if the request is effectively immediate. -Declarative-friendly resources **must** include `validate_only` (AIP-163) and -`etag` (AIP-154) in their `Undelete` methods. +Declarative-friendly resources **must** include `validate_only` (AEP-163) and +`etag` (AEP-154) in their `Undelete` methods. ### Errors @@ -123,7 +123,7 @@ resource is not deleted, the service **must** error with `409 Conflict`. ## Further reading -- For the `Delete` standard method, see AIP-135. -- For long-running operations, see AIP-151. -- For resource freshness validation (`etag`), see AIP-154. -- For change validation (`validate_only`), see AIP-163. +- For the `Delete` standard method, see AEP-135. +- For long-running operations, see AEP-151. +- For resource freshness validation (`etag`), see AEP-154. +- For change validation (`validate_only`), see AEP-163. diff --git a/aip/general/0164/aip.yaml b/aep/general/0164/aep.yaml similarity index 100% rename from aip/general/0164/aip.yaml rename to aep/general/0164/aep.yaml diff --git a/aip/general/0164/undelete.oas.yaml b/aep/general/0164/undelete.oas.yaml similarity index 100% rename from aip/general/0164/undelete.oas.yaml rename to aep/general/0164/undelete.oas.yaml diff --git a/aip/general/0164/undelete.proto b/aep/general/0164/undelete.proto similarity index 100% rename from aip/general/0164/undelete.proto rename to aep/general/0164/undelete.proto diff --git a/aip/general/0210/aip.md b/aep/general/0210/aep.md similarity index 100% rename from aip/general/0210/aip.md rename to aep/general/0210/aep.md diff --git a/aip/general/0210/aip.yaml b/aep/general/0210/aep.yaml similarity index 100% rename from aip/general/0210/aip.yaml rename to aep/general/0210/aep.yaml diff --git a/aip/general/0211/aip.md b/aep/general/0211/aep.md similarity index 98% rename from aip/general/0211/aip.md rename to aep/general/0211/aep.md index 53d682db..037c21a9 100644 --- a/aip/general/0211/aip.md +++ b/aep/general/0211/aep.md @@ -49,7 +49,7 @@ another's. [RFC 7231 ยง6.5.3][] states that services are permitted to use `404 Not Found` in lieu of `403 Forbidden` in situations where the service does not want to -divulge existance, whereas this AIP argues for the use of `403 Forbidden` +divulge existance, whereas this AEP argues for the use of `403 Forbidden` instead. We take this position for the following reasons: - The practice of "getting `404 Not Found` until you have enough permission to diff --git a/aip/general/0211/aip.yaml b/aep/general/0211/aep.yaml similarity index 100% rename from aip/general/0211/aip.yaml rename to aep/general/0211/aep.yaml diff --git a/aip/general/scope.yaml b/aep/general/scope.yaml similarity index 100% rename from aip/general/scope.yaml rename to aep/general/scope.yaml diff --git a/common-components/proto/aip/type/decimal.proto b/common-components/proto/aep/type/decimal.proto similarity index 88% rename from common-components/proto/aip/type/decimal.proto rename to common-components/proto/aep/type/decimal.proto index 46a32787..93d19ca3 100644 --- a/common-components/proto/aip/type/decimal.proto +++ b/common-components/proto/aep/type/decimal.proto @@ -1,13 +1,13 @@ syntax = "proto3"; -package aip.type; +package aep.type; option cc_enable_arenas = true; -option go_package = "aip.golang.org/genproto/common-components/type/decimal;decimal"; +option go_package = "aep.golang.org/genproto/common-components/type/decimal;decimal"; option java_multiple_files = true; option java_outer_classname = "DecimalProto"; -option java_package = "dev.aip.type"; -option objc_class_prefix = "AIP"; +option java_package = "dev.aep.type"; +option objc_class_prefix = "AEP"; // Represents a decimal number in a form similar to scientific notation. // diff --git a/common-components/proto/aip/type/money.proto b/common-components/proto/aep/type/money.proto similarity index 85% rename from common-components/proto/aip/type/money.proto rename to common-components/proto/aep/type/money.proto index 885489db..45d6a91e 100644 --- a/common-components/proto/aip/type/money.proto +++ b/common-components/proto/aep/type/money.proto @@ -1,15 +1,15 @@ syntax = "proto3"; -package aip.type; +package aep.type; option cc_enable_arenas = true; -option go_package = "aip.golang.org/genproto/common-components/type/money;money"; +option go_package = "aep.golang.org/genproto/common-components/type/money;money"; option java_multiple_files = true; option java_outer_classname = "MoneyProto"; -option java_package = "dev.aip.type"; -option objc_class_prefix = "AIP"; +option java_package = "dev.aep.type"; +option objc_class_prefix = "AEP"; -import "aip/type/decimal.proto"; +import "aep/type/decimal.proto"; // Represents an amount of money with its currency type. // diff --git a/common-components/proto/buf.yaml b/common-components/proto/buf.yaml index 7adae4ec..f973afb1 100644 --- a/common-components/proto/buf.yaml +++ b/common-components/proto/buf.yaml @@ -1,5 +1,5 @@ version: v1 -name: buf.build/aip/common-components +name: buf.build/aep/type breaking: use: - FILE diff --git a/config/header.yaml b/config/header.yaml index dd207061..26dddf4d 100644 --- a/config/header.yaml +++ b/config/header.yaml @@ -1,6 +1,6 @@ type: static links: - - title: Browse AIPs + - title: Browse AEPs relative_url: /general - title: Contributing relative_url: /contributing diff --git a/config/hero.yaml b/config/hero.yaml index f73960c3..36d52444 100644 --- a/config/hero.yaml +++ b/config/hero.yaml @@ -1,30 +1,30 @@ --- buttons: - - text: Explore the AIPs + - text: Explore the AEPs href: /general - text: Learn how it works href: /1 shortcuts: - title: Curious about the basics? description: | - AIPs are a combination of design guidance and a system we use to manage - and track that guidance. Learn more about how the AIP program works in - the first AIP! + AEPs are a combination of design guidance and a system we use to manage + and track that guidance. Learn more about how the AEP program works in + the first AEP! button: href: /1 - text: Read AIP-1 + text: Read AEP-1 - title: Want to help? description: | - Interested in helping with AIPs? Contribute by proposing new guidance, - commenting on existing AIPs, or fixing typos. All contributions are + Interested in helping with AEPs? Contribute by proposing new guidance, + commenting on existing AEPs, or fixing typos. All contributions are welcome! button: href: /contributing text: Contribute to the project - - title: Want to use AIPs for your organization? + - title: Want to use AEPs for your organization? description: | - AIPs are designed to be useful outside of Google. Take a look at how you - might choose which AIPs are best suited to your API design needs. + AEPs are designed to be useful outside of Google. Take a look at how you + might choose which AEPs are best suited to your API design needs. button: href: /adopting text: Learn more @@ -34,5 +34,5 @@ shortcuts: questions. If you don't find an answer there, file an issue on our GitHub repository. button: - href: https://github.com/aip-dev/google.aip.dev/issues + href: https://github.com/aep-dev/aep.dev/issues text: Ask us on GitHub diff --git a/pages/general/licensing.md b/pages/general/licensing.md index ed6bb11b..7a25f8e0 100644 --- a/pages/general/licensing.md +++ b/pages/general/licensing.md @@ -1,6 +1,6 @@ # Content licensing -We are pleased to license much of the AIP content under terms that explicitly +We are pleased to license much of the AEP content under terms that explicitly encourage people to take, modify, reuse, re-purpose, and remix our work as they see fit.