AEP Editions

This AEP describes how the AEP specification is versioned.

Edition-based versioning

AEPs will be published in editions, similar but not identical to specifications such as those for the C++ or Rust programming languages:

• There are two types of editions: “stable” editions which do not change, and “preview” editions which represent any edition not yet stablized.
• The naming of a stable edition will be based on the year in which it is published (e.g. aep-2025).
• The specification will not change for a stable edition after it is published.
• Upon promoting a preview edition to a stable edition, the next preview edition will be created (e.g. aep-2027-preview). This preview edition will accumulate changes until it is promoted.
• AEP editions MAY have patch version updates which adhere to semantic versioning (e.g. aep-2025.25).
  • The patch version will not make any breaking changes. For example, fixing typos or clarifying existing guidance.
  • The patch version will only contain fixes to typos in, and clarification on, existing guidance.
• Editions will be published every 2 years.

Breaking changes

A breaking change is a change to the specification that would result in one of the following:

• A change which could cause a previously compliant API to become non-compliant.
• A change which would break client functionality that was leveraging guidance explicitly stated in the specification.

A new AEP edition may have breaking changes.

The AEP specification will generally strive to minimize breaking changes, even across editions.

First-party clients and tooling

NOTE: This proposal only applies to AEP first-party clients. Third party open source projects or organizations are governed outside of this project, and may have their own guarantees.

Client versioning

• Clients SHOULD adhere to Semantic Versioning 2.0.0

Client and edition compatibilty

The newest major version of clients and tools MUST be compatible with, at minimum, the 3 latest stable AEP editions.

The following guidance applies to the most recent major versions of clients:

• Clients may provide different support guarantees for older major versions.
• Each major version will state which AEP editions are supported by those clients.
• This guidance does not apply to accepting PRs on older major versions: those may be accepted for any maintained branch of the project, at the discretion of the client maintainers.
• Clients and tools may support features in preview editions, but support for preview edition features in all clients and tools is not guaranteed.

Examples of AEP specification changes

The following are examples of specification changes:

• renaming a field (e.g. name to path)
• changing the syntax for a filter or query language
• updating versioning guidance
• adding a new standard method
• removing guidance
• updating a design pattern (e.g. singletons or revisions)
• adding a new design pattern

Rationale

Editions and breaking changes

After enumerating all the possible types of changes to the specification, it was determined that, to either some API publisher or client, any change to the specification would be breaking some use case.

Some cases, such as renaming a standard field, were straightforward. Others, like adding a new design pattern, could conflict with the design of an existing API, therefore possibly invalidating the API compatibility with a specification.

Removing guidance could also result in breaking a client which relied upon that guidance existing (for example, an API that may treat revisions as a first-class concept for rollback, aliasing, and rolling forward).

Therefore, rather than attempt to scope the breaking changes, all changes of any kind are left until the next edition.

Why an edition-based scheme

The AEPs have two goals that are difficult to achieve in concert:

1. Providing a set of modern best practices for remote APIs.
2. Providing a stable ecosystem of tooling that organizations can adopt for their use.

This is due to the need to constantly evolve the best practices, which may contradict older best practices and therefore result in a breaking change. These breaking changes can be difficult for both services producing these APIs to adopt, as well as complicate clients with multiple different code paths to handle these different versions of clients.

An edition-based system will help provide clear expectations around the cadence in which breaking changes could be introduced, as well as act as an anchor on which other durations could be based (for example, support for a number of editions in major versions of clients).

Why clients are versioned separately

Although clients are expected to support recent AEP editions and could have a similar versioning scheme, clients may also need to introduce breaking changes for a variety of reasons unrelated to a new AEP edition, including:

1. An interface change in the client itself.
2. A change to support a new integration or interface (for example, supporting a new version of the Terraform SDK, or a major version of the MCP server protocol).

This necessitates the ability to express these changes to consumers. As such, decoupling the client version from the AEP editions is a critical requirement.