Skip to content

Commit

Permalink
Rebrand from AIP to AEP. (#59)
Browse files Browse the repository at this point in the history
* 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
  • Loading branch information
rofrankel authored Oct 9, 2023
1 parent cb14388 commit db2e45d
Show file tree
Hide file tree
Showing 58 changed files with 133 additions and 132 deletions.
10 changes: 5 additions & 5 deletions ADOPTERS.md
Original file line number Diff line number Diff line change
@@ -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). |
6 changes: 3 additions & 3 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion GOVERNANCE.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# API Improvement Proposals: Project Charter
# API Enhancement Proposals: Project Charter

## Article I: Purpose

Expand Down
2 changes: 1 addition & 1 deletion MAINTAINERS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Expand Down
5 changes: 3 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
128 changes: 64 additions & 64 deletions aip/general/0001/aip.md → aep/general/0001/aep.md
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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:

Expand All @@ -52,93 +52,93 @@ 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.

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

Expand All @@ -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/
File renamed without changes.
2 changes: 1 addition & 1 deletion aip/general/0126/aip.md.j2 → aep/general/0126/aep.md.j2
Original file line number Diff line number Diff line change
Expand Up @@ -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
File renamed without changes.
File renamed without changes.
File renamed without changes.
Loading

0 comments on commit db2e45d

Please sign in to comment.