documentation/src/docs/asciidoc/user-guide/api-evolution.adoc

[[api-evolution]]
== API Evolution

One of the major goals of JUnit 5 is to improve maintainers' capabilities to evolve JUnit
despite its being used in many projects. With JUnit 4 a lot of stuff that was originally
added as an internal construct only got used by external extension writers and tool
builders. That made changing JUnit 4 especially difficult and sometimes impossible.

That's why JUnit 5 introduces a defined lifecycle for all publicly available interfaces,
classes, and methods.

[[api-evolution-version-and-status]]
=== API Version and Status

Every published artifact has a version number `<major>.<minor>.<patch>`, and all publicly
available interfaces, classes, and methods are annotated with {API} from the
{API_Guardian} project. The annotation's `status` attribute can be assigned one of the
following values.

[cols="20,80"]
|===
| Status           | Description

| `INTERNAL`       | Must not be used by any code other than JUnit itself. Might be removed without prior notice.
| `DEPRECATED`     | Should no longer be used; might disappear in the next minor release.
| `EXPERIMENTAL`   | Intended for new, experimental features where we are looking for feedback. +
                     Use this element with caution; it might be promoted to `MAINTAINED` or
                     `STABLE` in the future, but might also be removed without prior notice, even in a patch.
| `MAINTAINED`     | Intended for features that will not be changed in a backwards-
                     incompatible way for *at least* the next minor release of the current
                     major version. If scheduled for removal, it will be demoted to `DEPRECATED` first.
| `STABLE`         | Intended for features that will not be changed in a backwards-
                     incompatible way in the current major version (`5.*`).
|===

If the `@API` annotation is present on a type, it is considered to be applicable for all
public members of that type as well. A member is allowed to declare a different `status`
value of lower stability.

[[api-evolution-experimental-apis]]
=== Experimental APIs

The following table lists which APIs are currently designated as _experimental_ via
`@API(status = EXPERIMENTAL)`. Caution should be taken when relying on such APIs.

include::{experimentalApisTableFile}[]

[[api-evolution-deprecated-apis]]
=== Deprecated APIs

The following table lists which APIs are currently designated as _deprecated_ via
`@API(status = DEPRECATED)`. You should avoid using deprecated APIs whenever possible,
since such APIs will likely be removed in an upcoming release.

include::{deprecatedApisTableFile}[]

[[api-evolution-tooling]]
=== @API Tooling Support

The {API_Guardian} project plans to provide tooling support for publishers and consumers
of APIs annotated with {API}. For example, the tooling support will likely provide a
means to check if JUnit APIs are being used in accordance with `@API` annotation
declarations.