= API Evolution
:page-toclevels: 1

One of the major goals of the JUnit Platform architecture 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 now uses a defined lifecycle for all publicly available interfaces,
classes, and methods.

[[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 (`6.*`).
|===

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.

[[experimental-apis]]
== Experimental APIs

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

include::partial$experimental-apis-table.adoc[]

[[deprecated-apis]]
== Deprecated APIs

The following tables list 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::partial$deprecated-apis-table.adoc[]

[[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.
